El servidor MCP pinky-mcp

pinky-mcp es cómo un agente usa el brain: expone la memoria como tools de MCP sobre stdio. El agente busca y guarda conocimiento sin grepear ni leer archivos a mano; comparte el mismo índice (brain.db) que el CLI pinky.

• No es un daemon ni escucha en un puerto: es un proceso stdio que el cliente MCP (Claude Code u otro) lanza y habla por stdin/stdout.
• Protocolo: JSON-RPC 2.0, mensajes JSON delimitados por línea. Versión de protocolo 2024-11-05. Métodos: initialize, tools/list, tools/call, ping.
• Todo el logging va a stderr (PINKY_LOG/RUST_LOG), nunca a stdout, para no ensuciar el canal JSON-RPC.

Las tres tools

brain_search — buscar conocimiento

Búsqueda híbrida (BM25 full-text + vector semántico, fusión RRF) sobre el brain. Registra telemetría de uso (qué se recupera).

{ "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 — guardar conocimiento nuevo

Escribe el .md fuente de verdad (en PINKY_SAVE_DIR) y lo indexa al vuelo. Usalo cuando el agente descubre algo reutilizable que valga la pena recordar.

El scope de la entrada guardada sale del argumento project o, si se omite, de la env var PINKY_PROJECT; sin ninguno, queda en 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 — tamaño del índice

Sin argumentos. Devuelve la cantidad de entradas y chunks indexados.

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

Cada tool responde un content: [{ "type": "text", "text": … }]. Ante un error (input inválido, índice ausente) responde el mismo shape con "isError": true — no tira la conexión.

Configuración (variables de entorno)

pinky-mcp no toma flags: se configura por entorno. Ver también CONFIGURATION.md.

Registrarlo en Claude Code

Opción A — pinky init (recomendada)

Prepara el proyecto y escribe .mcp.json con rutas relativas (relocatable entre máquinas/clones), preservando otros servers ya definidos:

pinky init

Deja algo así:

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

PINKY_DB=brain.db coincide con el default del CLI (pinky --db brain.db), así pinky reindex documentation y el agente comparten índice. Reabrí el proyecto en Claude Code y el MCP pinky queda disponible.

Opción B — claude mcp add (registro global de la máquina)

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

Otros clientes MCP

Cualquier cliente que hable MCP sobre stdio sirve: apuntalo al binario pinky-mcp (en el PATH) como command, con las env vars de arriba. El core es agnóstico — solo los hooks son específicos de Claude Code.

Probarlo a mano (debug)

Como habla JSON-RPC por líneas, se puede ejercitar sin un 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

Deberías ver el serverInfo ("name":"pinky-brain"), el listado de las tres tools y las stats del índice.

Las tres piezas comparten el mismo índice: MCP pinky-mcp (esto, para el agente), CLI pinky (CLI.md, para vos/scripts) y hooks pinky-hooks (Claude Code). Panorama completo en HOW-IT-WORKS.md.