O servidor MCP pinky-mcp

pinky-mcp é como um agente usa o brain: expõe a memória como tools de MCP sobre stdio. O agente busca e salva conhecimento sem fazer grep nem ler arquivos na mão; compartilha o mesmo índice (brain.db) que o CLI pinky.

• Não é um daemon nem escuta em uma porta: é um processo stdio que o cliente MCP (Claude Code ou outro) inicia e com o qual conversa por stdin/stdout.
• Protocolo: JSON-RPC 2.0, mensagens JSON delimitadas por linha. Versão de protocolo 2024-11-05. Métodos: initialize, tools/list, tools/call, ping.
• Todo o logging vai para stderr (PINKY_LOG/RUST_LOG), nunca para stdout, para não sujar o canal JSON-RPC.

As três tools

brain_search — buscar conhecimento

Busca híbrida (BM25 full-text + vetor semântico, fusão RRF) sobre o brain. Registra telemetria de uso (o que é recuperado).

{ "jsonrpc": "2.0", "id": 1, "method": "tools/call",
  "params": { "name": "brain_search",
    "arguments": { "query": "timeout al cerrar el pool de postgres",
                   "type": "gotcha", "project": "sgsvp", "limit": 5 } } }

brain_save — salvar conhecimento novo

Escreve o .md fonte da verdade (em PINKY_SAVE_DIR) e o indexa na hora. Use quando o agente descobre algo reutilizável que valha a pena lembrar.

O scope da entrada salva vem do argumento project ou, se for omitido, da env var PINKY_PROJECT; sem nenhum deles, fica em global.

{ "jsonrpc": "2.0", "id": 2, "method": "tools/call",
  "params": { "name": "brain_save",
    "arguments": { "type": "gotcha", "title": "El pool de PG se cuelga al apagar",
                   "body": "Usar pool.close(timeout=…) antes de salir…",
                   "tags": ["postgres", "pool"] } } }

brain_stats — tamanho do índice

Sem argumentos. Devolve a quantidade de entradas e chunks indexados.

{ "jsonrpc": "2.0", "id": 3, "method": "tools/call",
  "params": { "name": "brain_stats", "arguments": {} } }

Cada tool responde um content: [{ "type": "text", "text": … }]. Diante de um erro (input inválido, índice ausente) responde o mesmo shape com "isError": true — não derruba a conexão.

Configuração (variáveis de ambiente)

pinky-mcp não aceita flags: é configurado por ambiente. Veja também CONFIGURATION.md.

Registrá-lo no Claude Code

Opção A — pinky init (recomendada)

Prepara o projeto e escreve .mcp.json com caminhos relativos (relocáveis entre máquinas/clones), preservando outros servers já definidos:

pinky init

Deixa algo assim:

{
  "mcpServers": {
    "pinky": {
      "command": "pinky-mcp",
      "env": {
        "PINKY_DB": "brain.db",
        "PINKY_SAVE_DIR": "documentation"
      }
    }
  }
}

PINKY_DB=brain.db coincide com o default do CLI (pinky --db brain.db), assim pinky reindex documentation e o agente compartilham índice. Reabra o projeto no Claude Code e o MCP pinky fica disponível.

Opção B — claude mcp add (registro global da máquina)

claude mcp add pinky --env PINKY_DB="$PWD/brain.db" -- pinky-mcp
# o, desde el repo de pinky_brain:
make mcp-register

Outros clientes MCP

Qualquer cliente que fale MCP sobre stdio serve: aponte-o para o binário pinky-mcp (no PATH) como command, com as env vars de cima. O core é agnóstico — somente os hooks são específicos do Claude Code.

Testá-lo na mão (debug)

Como ele fala JSON-RPC por linhas, dá para exercitá-lo sem um cliente:

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"brain_stats","arguments":{}}}' \
  | PINKY_DB=brain.db pinky-mcp

Você deveria ver o serverInfo ("name":"pinky-brain"), a listagem das três tools e as stats do índice.

As três peças compartilham o mesmo índice: MCP pinky-mcp (isto, para o agente), CLI pinky (CLI.md, para você/scripts) e hooks pinky-hooks (Claude Code). Panorama completo em HOW-IT-WORKS.md.