mcp-writechoice-server by writechoiceorg - MCP Server

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

Clone este repositório
Instale as dependências: npm install
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
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.

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).
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
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.
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.
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.
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.
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