Il server MCP pinky-mcp

pinky-mcp è il modo in cui un agente usa il brain: espone la memoria come tool di MCP su stdio. L'agente cerca e salva conoscenza senza fare grep né leggere file a mano; condivide lo stesso indice (brain.db) del CLI pinky.

• Non è un daemon né ascolta su una porta: è un processo stdio che il client MCP (Claude Code o un altro) avvia e con cui parla via stdin/stdout.
• Protocollo: JSON-RPC 2.0, messaggi JSON delimitati per riga. Versione di protocollo 2024-11-05. Metodi: initialize, tools/list, tools/call, ping.
• Tutto il logging va su stderr (PINKY_LOG/RUST_LOG), mai su stdout, per non sporcare il canale JSON-RPC.

I tre tool

brain_search — cercare conoscenza

Ricerca ibrida (BM25 full-text + vettore semantico, fusione RRF) sul brain. Registra telemetria d'uso (cosa viene recuperato).

{ "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 — salvare nuova conoscenza

Scrive il .md fonte di verità (in PINKY_SAVE_DIR) e lo indicizza al volo. Usalo quando l'agente scopre qualcosa di riutilizzabile che valga la pena ricordare.

Lo scope della voce salvata deriva dall'argomento project oppure, se omesso, dalla env var PINKY_PROJECT; senza nessuno dei due, resta 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 — dimensione dell'indice

Senza argomenti. Restituisce il numero di voci e chunk indicizzati.

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

Ogni tool risponde con un content: [{ "type": "text", "text": … }]. In caso di errore (input non valido, indice assente) risponde con lo stesso shape e "isError": true — non chiude la connessione.

Configurazione (variabili d'ambiente)

pinky-mcp non accetta flag: si configura tramite l'ambiente. Vedi anche CONFIGURATION.md.

Registrarlo in Claude Code

Opzione A — pinky init (raccomandata)

Prepara il progetto e scrive .mcp.json con percorsi relativi (rilocabili tra macchine/cloni), preservando altri server già definiti:

pinky init

Lascia qualcosa del genere:

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

PINKY_DB=brain.db coincide con il default del CLI (pinky --db brain.db), così pinky reindex documentation e l'agente condividono l'indice. Riapri il progetto in Claude Code e l'MCP pinky diventa disponibile.

Opzione B — claude mcp add (registrazione globale della macchina)

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

Altri client MCP

Va bene qualsiasi client che parli MCP su stdio: puntalo al binario pinky-mcp (nel PATH) come command, con le env var qui sopra. Il core è agnostico — solo gli hook sono specifici di Claude Code.

Provarlo a mano (debug)

Dato che parla JSON-RPC per righe, si può esercitare senza un client:

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

Dovresti vedere il serverInfo ("name":"pinky-brain"), l'elenco dei tre tool e le stats dell'indice.

I tre pezzi condividono lo stesso indice: MCP pinky-mcp (questo, per l'agente), CLI pinky (CLI.md, per te/gli script) e hook pinky-hooks (Claude Code). Panoramica completa in HOW-IT-WORKS.md.