🇺🇸 English | 🇧🇷 Português

Unicode Precision MCP: The Exact Writing Guardian for A.I.

What is it?

The Unicode Precision MCP is an analytical infrastructure server designed to provide the absolute truth about the spatial dimension of any text. Unlike common counters, it operates under the mathematical rigor of Unicode 16.0 and the UAX #29 standard, treating text not as a sequence of bytes or memory units, but as Extended Grapheme Clusters — exactly what the human eye sees.

Why is it Vital for Writing A.I.?

Large Language Models (LLMs) are, by nature, statistical token prediction engines. They lack spatial awareness. When you ask an A.I. to write "exactly 100 characters" or create a title that fits in a restricted visual space, it systematically fails when encountering:

• Complex Emojis: A family emoji might count as 11 or more in the A.I.'s counter, but counts as only 1 visually.
• Decomposed Accents: Character sequences that visually combine confuse the A.I.'s token calculation.
• Strict UI Limits: Platforms like Google Ads, Twitter, or SEO meta-tags demand precision that organic A.I. cannot guarantee alone.

This MCP acts as the external measurement tool (the "physical ruler") that allows the A.I. to validate and correct its own output in a perfect feedback loop.

The Differential: Human Analytical Rigor

• NFC Normalization: Automatically unifies decomposed strings before calculation, ensuring that é is always a single code point, regardless of how it was generated.
• UAX #29 Compliance: Differentiates what is a "code unit" from what is a "visual character". Identifies skin tones, zero width joiners (ZWJ), and complex alphabets as a single visual unit.
• Multi-Metric Payload: Simultaneously returns Graphemes (visual), Code Points (logical), UTF-16 (memory), and UTF-8 (disk).

Universal Installation and Execution Guide

For all platforms, the server uses the native MCP protocol via Stdio, powered by instant cloud execution (npx). You do not need to install or clone anything locally.

1. Requirement

You only need to have Node.js/npm installed on your machine. The npx command will take care of downloading and running the gears in the background.

2. Configuration per Platform

Antigravity

1. Open the configuration file mcp_config.json.
2. Add the unicode-mcp entry inside the mcpServers object:

"unicode-mcp": {
  "command": "npx",
  "args": ["-y", "@wagnergpnc/charactercounter-mcp"]
}

Cursor

1. Go to Settings > Cursor Settings > Features > MCP Servers.
2. Click + Add New MCP Server.
3. Choose the stdio type.
4. Name: UnicodeChecker
5. Command: npx
6. Arguments: -y @wagnergpnc/charactercounter-mcp

Claude Code / Codex / Gemini CLI

For A.I.s and assistants operated purely via terminal, the installation commands inject the MCP provider immediately:

Claude Code:

claude mcp add unicode-mcp npx -y @wagnergpnc/charactercounter-mcp

Codex:

codex mcp add unicode-mcp -- npx -y @wagnergpnc/charactercounter-mcp

Gemini CLI:

gemini mcp add unicode-mcp npx -y @wagnergpnc/charactercounter-mcp

Other Go/Python Clients

If the client uses a yaml/json configuration file not generated via CLI:

mcpServers:
  unicode:
    command: "npx"
    args: ["-y", "@wagnergpnc/charactercounter-mcp"]

VS Code (via Cline / Roo Code / Claude Dev)

1. Open the extension settings (gear icon in the extension chat).
2. Look for MCP Config or Edit MCP Settings.
3. Add the JSON:

{
  "mcpServers": {
    "unicode-mcp": {
      "command": "npx",
      "args": ["-y", "@wagnergpnc/charactercounter-mcp"]
    }
  }
}

3. How to Run and Test

Once configured, the server will be started automatically by your editor/client. To test:

1. Via Chat: Ask the Agent: "What is the grapheme count for '👨‍👩‍👧‍👦'?"
2. Via System Prompt: Integrate the system_prompt.md file into your project instructions so that the A.I. uses the server as an automatic loop validator in writing tasks.
3. Error Log: The server emits detailed logs via stderr. If there is a connection failure, check if the npx command is available and working.

Developed under the precepts of Senior AI Engineering for the Bitcurioso ecosystem.

Unicode Precision MCP: O Guardião da Escrita Exata para I.A.

O que é?

O Unicode Precision MCP é um servidor de infraestrutura analítica projetado para fornecer a verdade absoluta sobre a dimensão espacial de qualquer texto. Ao contrário de contadores comuns, ele opera sob o rigor matemático do Unicode 16.0 e o padrão UAX #29, tratando o texto não como uma sequência de bytes ou unidades de memória, mas como Aglomerados de Grafemas Estendidos — exatamente o que o olho humano enxerga.

Por que é Vital para I.A. de Escrita?

Modelos de Linguagem (LLMs) são, por natureza, motores estatísticos de predição de tokens. Eles não possuem consciência espacial. Quando você pede a uma I.A. para escrever "exatamente 100 caracteres" ou criar um título que caiba em um espaço visual restrito, ela falha sistematicamente ao encontrar:

• Emojis Complexos: Um emoji de família pode valer 11 ou mais no contador da I.A., mas conta como apenas 1 visualmente.
• Acentuação Decomposta: Sequências de caracteres que se unem visualmente confundem o cálculo de tokens da I.A.
• Limites Rígidos de UI: Plataformas como Google Ads, Twitter ou meta-tags de SEO exigem precisão que a I.A. orgânica não consegue garantir sozinha.

Este MCP atua como a ferramenta de medição externa (a "régua física") que permite à I.A. validar e corrigir sua própria saída em um loop de feedback perfeito.

O Diferencial: Rigor Analítico Humano

• Normalização NFC: Unifica automaticamente strings decompostas antes do cálculo, garantindo que é seja sempre um único ponto de código, não importa como foi gerado.
• Conformidade UAX #29: Diferencia o que é "unidade de código" do que é "caractere visual". Identifica tons de pele, junções de largura zero (ZWJ) e alfabetos complexos como uma única unidade visual.
• Payload Multi-Métrico: Retorna simultaneamente Graphemes (visual), Code Points (lógico), UTF-16 (memória) e UTF-8 (disco).

Guia Universal de Instalação e Execução

Para todas as plataformas, o servidor utiliza o protocolo MCP nativo via Stdio, alimentado pela execução instantânea em nuvem (npx). Não é necessário instalar ou clonar nada localmente.

1. Requisito

Somente é necessário possuir o Node.js/npm instalado na sua máquina. O comando npx cuidará de baixar e rodar as engrenagens em segundo plano.

2. Configuração por Plataforma

Antigravity

1. Abra o arquivo de configuração mcp_config.json.
2. Adicione a entrada unicode-mcp dentro do objeto mcpServers:

"unicode-mcp": {
  "command": "npx",
  "args": ["-y", "@wagnergpnc/charactercounter-mcp"]
}

Cursor

1. Vá em Settings > Cursor Settings > Features > MCP Servers.
2. Clique em + Add New MCP Server.
3. Escolha o tipo stdio.
4. Nome: UnicodeChecker
5. Command: npx
6. Arguments: -y @wagnergpnc/charactercounter-mcp

Claude Code / Codex / Gemini CLI

Para IAs e assistentes operados puramente via terminal, os comandos de instalação injetam o provedor MCP imediatamente:

Claude Code:

claude mcp add unicode-mcp npx -y @wagnergpnc/charactercounter-mcp

Codex:

codex mcp add unicode-mcp -- npx -y @wagnergpnc/charactercounter-mcp

Gemini CLI:

gemini mcp add unicode-mcp npx -y @wagnergpnc/charactercounter-mcp

Outros Clientes Go/Python

Se o cliente usa configuração em arquivo yaml/json não gerada via CLI:

mcpServers:
  unicode:
    command: "npx"
    args: ["-y", "@wagnergpnc/charactercounter-mcp"]

VS Code (via Cline / Roo Code / Claude Dev)

1. Abra as configurações da extensão (ícone de engrenagem no chat da extensão).
2. Procure por MCP Config ou Edit MCP Settings.
3. Adicione o JSON:

{
  "mcpServers": {
    "unicode-mcp": {
      "command": "npx",
      "args": ["-y", "@wagnergpnc/charactercounter-mcp"]
    }
  }
}

3. Como Rodar e Testar

Uma vez configurado, o servidor será iniciado automaticamente pelo seu editor/cliente. Para testar:

1. Via Chat: Pergunte ao Agente: "Qual a contagem de grafemas de '👨‍👩‍👧‍👦'?"
2. Via Prompt Sistêmico: Integre o arquivo system_prompt.md nas instruções de projeto para que a I.A. use o servidor como validador automático de loop em tarefas de escrita.
3. Log de Erros: O servidor emite logs detalhados via stderr. Se houver falha na conexão, verifique se o caminho do index.js está correto.

Desenvolvido sob os preceitos de Engenharia de IA Sênior para o ecossistema Bitcurioso.