MCP Vale Server

Um servidor Model Context Protocol (MCP) para verificação de qualidade de texto usando Vale, permitindo análise de estilo e gramática através de IA.

Funcionalidades

• ✅ Fazer lint de texto com Vale - Analisar qualidade e estilo de texto
• ✅ Verificar status do Vale - Confirmar se Vale está instalado e configurado
• ✅ Múltiplos estilos de verificação - Google, proselint, alex, WC-Styles
• ✅ Interface Web simples - Interface gráfica para teste
• ✅ API HTTP - Endpoints REST para integração
• ✅ Protocolo MCP nativo - Integração direta com assistentes IA

Instalação

1. Clone este repositório

2. Instale as dependências: npm install

3. Instale o Vale (verificador de estilo):

   • macOS brew install vale

   • Ubuntu/Debian sudo apt install vale

   • ou baixe de https://github.com/errata-ai/vale/releases

4. Compile o projeto: npm run build

Observação: Para desenvolver, use npm run dev para modo watch.

🚀 Formas de Usar

Este projeto oferece múltiplas formas de uso para atender diferentes necessidades:

🌟 Comando Único (Mais fácil!)

# ⭐ RECOMENDADO: Inicia ambos servidores com um comando
`npm run start-npm` 

# Alternativas (mesma funcionalidade):
`npm run start-js`     # Versão Node.js
`./start-servers.sh`   # Versão Bash (se disponível)

🖥️ Interface Web Tradicional (Dois comandos)

- Terminal 1: Iniciar API HTTP
`npm run http`

- Terminal 2: Iniciar interface web  
`npm run web`

- Acesse:  `http://localhost:8080/web-interface.html` 

🤖 MCP Server (Para Claude Desktop)

`npm start`

📡 API HTTP Direta

- Testar via curl/API calls

```bash
curl -X POST http://localhost:3000/vale/lint \
  -H "Content-Type: application/json" \
  -d '{"text":"Your text here","fileName":"test.md"}'
```

🧩 Rodando o MCP com Gemini-CLI

Se você usa um cliente/CLI chamado "Gemini-CLI" (ou similar) para gerenciar servidores MCP e conectar assistentes, aqui está um guia prático para executar este servidor com o Gemini-CLI. As instruções abaixo são intencionais e genéricas — adapte flags/nomes/paths para o formato exato do Gemini-CLI que você usa.

1. Pré-requisitos

   • Tenha o projeto compilado (npm run build) ou execute em modo standalone (npm start).
   • Tenha Vale instalado e configurado (veja seção de instalação).
   • Tenha o Gemini-CLI instalado e configurado localmente (siga a documentação do CLI que você utiliza).

2. Iniciando o servidor MCP localmente (modo stdio / MCP)

   • Modo standalone (stdio MCP): npm start

   • Ou, se preferir usar apenas o MCP server (arquivo compilado): node ./dist/index.js

3. Exemplo de configuração do Gemini-CLI

   • Abaixo está um exemplo ilustrativo de um arquivo de configuração JSON que aponta para o servidor MCP deste repositório. Ajuste os caminhos conforme seu ambiente.

   {
       "mcpServers": {
           "vale-server": {
               "command": "node",
               "args": ["./dist/index.js"],
               "env": {
                   "VALE_CONFIG_PATH": "./vale.ini"
               },
               "stdin": true,
               "protocol": "mcp"
           }
       }
   }
   

   • Observações:
     • args: caminho para o dist/index.js gerado pelo npm run build.
     • VALE_CONFIG_PATH: caminho relativo ou absoluto para o vale.ini.
     • stdin/protocol: campos ilustrativos — alguns CLIs usam chaves diferentes para indicar que o processo fala MCP por stdio ou socket; verifique o formato exato do seu Gemini-CLI.

4. Iniciando via Gemini-CLI

   • Com a configuração acima salva (por exemplo gemini-config.json), um comando típico pode ser:

     gemini-cli --config ./gemini-config.json run vale-server

   • Dependendo do cliente, você pode ter subcomandos diferentes, como start, run, attach ou similar. Consulte a documentação do seu Gemini-CLI para a sintaxe correta.

5. Fluxos comuns

   • Fluxo A (CLI gerencia processo):

     • Gemini-CLI inicia o vale-server com stdio MCP.
     • O assistente/cliente conecta via MCP e usa as ferramentas (lint_text, vale_status, etc.).

   • Fluxo B (servidor já em execução):

     • Você executa npm start separadamente.
     • Configure o Gemini-CLI para se conectar ao processo em stdin/socket/porta conforme suportado.

6. Dicas de troubleshooting

   • Se o Gemini-CLI não conectar:
     • Verifique se o processo node ./dist/index.js está rodando e não travou com erro.
     • Confirme VALE_CONFIG_PATH correto e que vale.ini e diretório styles/ existem.
     • Rode npm run build novamente se os arquivos em dist/ estiverem faltando.
   • Se o Vale retornar erros:
     • Vale pode retornar código de saída != 0 quando encontra problemas de lint — isso é comportamento esperado. Use a ferramenta vale_status ou vale --version para validar instalação.
   • Logs:
     • Ative logs detalhados no Gemini-CLI (se disponível) e no MCP server (ex.: variável de ambiente DEBUG ou flags de verbose) para diagnosticar handshake MCP.

7. Exemplo mínimo passo-a-passo

   1. Build: npm run build
   2. Criar gemini-config.json (ajuste caminhos)
   3. Iniciar com o Gemini-CLI: gemini-cli --config ./gemini-config.json run vale-server
   4. No cliente/assistente, selecione o servidor vale-server e execute ferramentas como lint_text.

Se você me disser qual é o repositório/executável exato do Gemini-CLI que está usando (ou colar o exemplo do config esperado), eu adapto o snippet de configuração e o comando final para o formato exato do seu CLI.

Ferramentas Disponíveis

lint_text

Faz lint de texto usando Vale style checker.

Parâmetros:

• text (string): Conteúdo de texto para analisar
• fileName (string, opcional): Nome do arquivo para o texto (padrão: document.md)

check_vale_status

Verifica se Vale está instalado e funcionando corretamente.

Parâmetros: Nenhum

⚡ Comandos Rápidos

# 🚀 Iniciar tudo (RECOMENDADO)
`npm run start-npm`

# 🧪 Testar funcionalidade
`npm run test-server`

# 🔨 Compilar TypeScript
`npm run build`

# 🌐 Apenas interface web
`npm run web`

# 📡 Apenas API HTTP
`npm run http`

💡 Guia de Escolha da Interface

✅ Para iniciantes ou teste rápido:

• Interface Web: http://localhost:8080/web-interface.html
• Visual, intuitiva, sem configuração

🤖 Para integração com Claude Desktop:

• MCP Server: Configuração no claude_desktop_config.json
• Melhor para uso regular com Claude

🔧 Para integração com outras aplicações:

• API HTTP: Endpoints REST para integração
• Ideal para desenvolvimento de outras interfaces

Estrutura do Projeto

    src/
    ├── index.ts           # Servidor MCP principal
    ├── vale-service.ts    # Serviço de integração com Vale
    └── test.ts            # Testes do servidor

Desenvolvimento

- Modo de desenvolvimento (watch)
`npm run dev`

- Build
`npm run build`

- Testes
`npm test`

Variáveis de Ambiente

• VALE_CONFIG_PATH: Caminho para o arquivo vale.ini (padrão: ./vale.ini)

Problemas Comuns

Vale não encontrado

• Certifique-se de que o Vale está instalado:

  • macOS brew install vale

  • Ubuntu/Debian sudo apt install vale

  • Windows choco install vale

  • ou baixe de https://github.com/errata-ai/vale/releases

Problemas de configuração

• Verifique se o arquivo vale.ini está no local correto
• Certifique-se de que os estilos necessários estão no diretório styles/

Licença

MIT