athena-mcp

헤르메스가 막혔을 때, 아테나에게 묻습니다.

도구 사용 에이전트에게 추론 보조 도구를 제공하는 MCP 서버입니다. 단 하나의 도구: think. 부작용 없음 — 아테나는 자체적인 도구가 없습니다. 그저 추론할 뿐입니다.

메인 에이전트(헤르메스, Claude Code, Cursor, MCP를 지원하는 모든 클라이언트)가 어려운 문제(미묘한 버그, 아키텍처 결정, 비판이 필요한 계획 등)에 직면했을 때, think를 호출하여 간결하고 논리적인 답변을 얻을 수 있습니다. 에이전트는 여전히 주도권을 유지하며, 아테나는 에이전트가 기본 모델로 해결하기 어려운 까다로운 문제에 직면했을 때 찾는 조용한 컨설턴트 역할을 합니다.

Codebuff의 thinker 에이전트에서 영감을 받았으며, 해당 에이전트는 내부적으로 정확히 이 방식을 사용합니다. Codebuff의 오케스트레이터는 컨텍스트를 수집한 후 도구가 없는 thinker-gpt를 생성하며, thinker의 유일한 임무는 깊이 생각하고 간결한 답변을 반환하는 것입니다.

왜 분리하나요?

대부분의 에이전트는 모든 작업에 하나의 모델을 사용합니다. 그 모델은 타협점입니다. 수백 번의 도구 호출을 처리할 만큼 빠르고 저렴하며, 대부분의 작업에 충분히 똑똑합니다. 하지만 정말로 막혔을 때는 다른 모델, 즉 추론 중심의 모델(Claude Opus, GPT-5, Gemini Pro, DeepSeek R1)이 필요합니다. 나머지 작업에 대한 제어권을 넘겨주지 않으면서 말이죠. 그것이 바로 아테나의 존재 이유입니다.

• 비용 — 추론 모델을 매번 실행하는 것은 비용이 많이 듭니다. 필요할 때만 호출하세요.

• 지연 시간 — 추론 모델은 느리게 생각합니다. 어려운 문제에만 사용하세요.

• 도구 직교성 — 아테나는 의도적으로 도구가 없습니다. 호출자가 부작용에 대한 제어권을 유지합니다.

• 모델 이식성 — 에이전트 전체를 재구성할 필요 없이 호출마다 추론 모델을 교체할 수 있습니다.

두 가지 백엔드

claude-code (claude CLI가 PATH에 있을 때 기본값) — 호출마다 claude -p를 생성하고 Anthropic Pro/Max 구독 OAuth를 사용합니다. API 키도, 토큰당 과금도 없습니다. 구독 할당량에서 차감될 뿐입니다. opus, sonnet, haiku 또는 전체 Claude 모델 이름을 지원합니다.

openrouter — OpenRouter에 대한 HTTPS 호출입니다. 토큰당 과금을 통해 모든 모델(Claude, GPT, Gemini, DeepSeek, Qwen 등)을 사용할 수 있습니다. OPENROUTER_API_KEY가 필요합니다.

ATHENA_BACKEND=claude-code 또는 ATHENA_BACKEND=openrouter로 명시적으로 선택하세요.

설치

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

환경 변수

헤르메스에 연결하기

헤르메스는 stdio를 통해 기본적으로 MCP를 지원합니다 (Nous Research Hermes Agent).

Claude 구독 사용 시 (권장):

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

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

확인:

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

새 헤르메스 세션을 시작하면 에이전트가 think 도구를 보게 됩니다.

Claude Code에 연결하기

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

다른 MCP 클라이언트에 연결하기

표준 stdio MCP 서버입니다. 클라이언트를 node /path/to/athena-mcp/dist/index.js로 지정하세요.

think 도구

호출 예시 (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"
    }
  }
}

응답은 하단에 backend: ... · model: ... · effort: ... · duration · tokens와 같은 푸터 라인이 포함된 텍스트로 돌아옵니다.

설계 노트

• 상태 비저장(Stateless). 각 호출은 독립적입니다. 대화의 연속성을 위해 context를 통해 관련 기록을 전달하세요.

• <think>...</think> 블록은 반환되기 전에 아테나의 응답에서 제거됩니다. 아테나는 출력물을 오염시키지 않고 이 블록을 스크래치 패드로 사용할 수 있습니다. Codebuff의 관례와 일치합니다.

• 중립적인 cwd. claude-code 백엔드는 os.tmpdir()에서 생성되므로 프로젝트의 CLAUDE.md 파일이 아테나의 컨텍스트로 유출되지 않습니다.

• 모든 claude-code 호출에 --tools "" + --disable-slash-commands + --no-session-persistence를 사용하여 아테나가 진정으로 도구 없이 상태를 유지하도록 합니다.

• 재시도 로직 없음. 백엔드에서 오류가 발생하면 오류가 그대로 노출되므로 호출자가 재시도 여부를 결정합니다.

개발

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

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

라이선스

MIT

크레딧

패턴은 CodebuffAI 팀의 Codebuff에서 감사히 빌려왔습니다. 그들의 thinker 에이전트는 이 설계의 표준 참조 모델입니다.