athena-mcp

Cuando Hermes está atascado, le pregunta a Athena.

Un servidor MCP que le da a tu agente que utiliza herramientas un asistente de razonamiento. Una herramienta: think. Sin efectos secundarios: Athena no tiene herramientas propias. Ella solo razona.

Cuando tu agente principal (Hermes, Claude Code, Cursor, cualquier cliente que hable MCP) se encuentra con un problema difícil —un error sutil, una decisión de arquitectura, un plan que necesita crítica— llama a think y recibe una respuesta concisa y bien razonada. Tu agente sigue al mando; Athena es la consultora silenciosa a la que recurre cuando el problema es más espinoso de lo que su modelo predeterminado puede manejar bien.

Inspirado en el agente pensador de Codebuff, que hace exactamente esto internamente: el orquestador de Codebuff genera thinker-gpt sin herramientas después de recopilar contexto, y el único trabajo del pensador es pensar profundamente y devolver una respuesta breve.

¿Por qué la separación?

La mayoría de los agentes ejecutan un solo modelo para todo. Ese modelo es un compromiso: lo suficientemente rápido y barato para cientos de llamadas a herramientas, lo suficientemente inteligente para la mayoría de ellas. Pero cuando realmente está atascado, quieres un modelo diferente —uno con gran capacidad de razonamiento (Claude Opus, GPT-5, Gemini Pro, DeepSeek R1)— sin ceder el control del resto de la tarea. Para eso es Athena.

• Coste — los modelos de razonamiento son caros de ejecutar en cada turno. Llámalos solo cuando sea necesario.

• Latencia — los modelos de razonamiento piensan lentamente. Guárdalos para problemas difíciles.

• Ortogonalidad de herramientas — Athena no tiene herramientas a propósito. El llamador mantiene el control de los efectos secundarios.

• Portabilidad del modelo — cambia los modelos de razonamiento por llamada sin reconfigurar todo tu agente.

Dos backends

claude-code (predeterminado cuando la CLI claude está en el PATH) — genera claude -p para cada llamada y utiliza tu OAuth de suscripción Pro/Max de Anthropic. Sin clave API, sin facturación por token. Solo cuenta contra la cuota de tu suscripción. Admite opus, sonnet, haiku o nombres completos de modelos de Claude.

openrouter — llamada HTTPS a OpenRouter. Cualquier modelo (Claude, GPT, Gemini, DeepSeek, Qwen, lo que sea) mediante facturación por token. Requiere OPENROUTER_API_KEY.

Elige explícitamente con ATHENA_BACKEND=claude-code o ATHENA_BACKEND=openrouter.

Instalación

git clone https://github.com/DevvGwardo/athena-mcp.git ~/projects/athena-mcp
cd ~/projects/athena-mcp
npm install
npm run build

Entorno

Conectar a Hermes

Hermes habla MCP sobre stdio de forma nativa (Nous Research Hermes Agent).

Con una suscripción a Claude (recomendado):

hermes mcp add athena \
  --command /path/to/node \
  --args /path/to/athena-mcp/dist/index.js \
  --env ATHENA_CLAUDE_CLI=/opt/homebrew/bin/claude

Con OpenRouter:

hermes mcp add athena \
  --command /path/to/node \
  --args /path/to/athena-mcp/dist/index.js \
  --env ATHENA_BACKEND=openrouter OPENROUTER_API_KEY=sk-or-v1-... ATHENA_MODEL=anthropic/claude-opus-4.6

Verificar:

hermes mcp list          # should show `athena`
hermes mcp test athena   # should report "Connected" and 1 tool

Inicia una nueva sesión de Hermes y el agente verá una herramienta think.

Conectar a Claude Code

claude mcp add athena --command node --args /path/to/athena-mcp/dist/index.js

Conectar a cualquier otro cliente MCP

Es un servidor MCP stdio estándar. Apunta tu cliente a node /path/to/athena-mcp/dist/index.js.

La herramienta think

Ejemplo de llamada (JSON-RPC):

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "think",
    "arguments": {
      "prompt": "Is there a race condition in the claim() function? If so, minimal fix?",
      "context": "def claim(self, rid):\n    if self.claims.get(rid):\n        return False\n    self.claims[rid] = self.agent_id\n    return True",
      "effort": "high"
    }
  }
}

La respuesta vuelve como texto con una línea de pie de página: backend: ... · model: ... · effort: ... · duration · tokens.

Notas de diseño

• Sin estado. Cada llamada es independiente. Para la continuidad de la conversación, pasa el historial relevante a través de context.

• Los bloques <think>...</think> en la respuesta de Athena se eliminan antes de devolverla; ella puede usarlos como espacio de trabajo sin contaminar la salida. Coincide con la convención de Codebuff.

• cwd neutral. El backend claude-code se genera desde os.tmpdir() para que los archivos CLAUDE.md del proyecto no se filtren en el contexto de Athena.

• --tools "" + --disable-slash-commands + --no-session-persistence en cada llamada de claude-code la mantienen verdaderamente sin herramientas y sin estado.

• Sin lógica de reintento. Si el backend falla, el error aparece claramente para que el llamador decida si reintentar.

Desarrollo

npm run dev     # tsc --watch
npm run build
npm start       # runs dist/index.js (needs an MCP stdio peer)

Prueba de humo sin tocar ninguna API:

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"t","version":"0"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  | node dist/index.js

Licencia

MIT

Créditos

Patrón tomado prestado, con agradecimiento, de Codebuff por el equipo de CodebuffAI. Su agente pensador es la referencia canónica para este diseño.