Athena MCP服务器

Athena MCP server

A small stdio adapter to Athena's existing HTTP API. It has no database access, workflow engine, business rules, or automatic write retries.

Install and run

Requires Node 22+ and an Athena backend containing the API contract repair in docs/api-mcp-contract.md.

npm ci
npm run build
cp .env.example .env
# Set API_URL and ATHENA_API_KEY privately in .env.
node --env-file=.env dist/server.js

For an MCP host, configure node with absolute paths to --env-file=/private/path/.env and /path/athena-mcp-server/dist/server.js. Do not use npm start as the protocol command: npm can print lifecycle output to stdout. The node entry point emits only MCP protocol messages on stdout. Diagnostics use stderr.

The transport is stdio: the host starts one process. No separate public web server, PM2 daemon, Redis, or agent framework is needed. Remote hosts can use Athena's HTTP API directly; this package does not claim remote MCP/OAuth support.

Credentials

• API_URL: backend origin, such as https://api.example.com (no /api suffix). HTTPS required outside loopback.
• ATHENA_API_KEY: a scoped key issued by Athena's existing Settings API-key management. Only a hash is stored there; existing revoke/rotate controls apply.
• AUTH_TOKEN: optional existing Athena JWT for six mobile-only compatibility tools, or JWT fallback for v1. API keys are never sent as mobile JWTs.
• REQUEST_TIMEOUT: milliseconds, default 30000, range 1..120000.
• Legacy PROD_API_URL/TEST_API_URL and PROD_AUTH_TOKEN/TEST_AUTH_TOKEN aliases are supported when NODE_ENV selects that environment. Prefer the single API_URL/ATHENA_API_KEY configuration.

Use the smallest required scopes: tasks:read, tasks:write, comments:write, projects:read, clients:read, search:read. Authentication and authorization are enforced by the API, not guessed by MCP. Keys are never printed by this adapter.

There is no automatic mock mode, including NODE_ENV=test. Tests explicitly start fixture HTTP servers or the disposable backend.

Core v1 tools

• athena_me
• athena_list_tasks, athena_get_task, athena_create_task, athena_update_task
• athena_add_comment, athena_get_comments, athena_create_deliverable
• athena_list_projects, athena_get_project, athena_list_project_stages
• athena_list_companies, athena_list_contacts, athena_search

Tool discovery publishes the exact validated JSON schemas. Unknown fields are rejected instead of silently discarded.

Writes and retries

Every core write requires idempotency_key: a caller-generated stable ID for one intended action. Reuse the same key and payload after a timeout. Do not generate a new key merely because the response was lost. Reusing a key with a changed payload returns 409.

athena_update_task also requires expected_updated_at copied exactly from athena_get_task. A stale version returns stale_revision (409). Read and reconcile the latest record before issuing a new intended update. MCP does not auto-fetch a newer version and overwrite it.

Task fields use the v1 contract: title, project_id, client_id, stage_id, assignees (UUID array), timezone-aware due_date, and priority Low|Normal|High|Critical. Status names remain backend/project-defined strings. Read project stages before setting stage_id.

Comments retain the MCP content argument and translate it to API body. Deliverables require a hosted HTTP(S) url; local file paths are not uploaded. Use Athena's existing upload flow separately before attaching a hosted file.

List responses retain API data/meta.next_cursor. Continue until next_cursor is null. Offset pagination is not a snapshot while records are changing.

Existing mobile compatibility tools

The original athena_create_subtask, athena_list_subtasks, athena_search_users, athena_get_categories, athena_approve_task, and athena_reject_task remain available and explicitly labeled in discovery. They require AUTH_TOKEN because those operations do not have v1 equivalents. Subtask title is correctly translated to mobile name. Review actions use backend permissions; they do not invent status transitions.

These six calls do not acquire the new v1 retry/revision guarantees. The adapter never retries them automatically. Reconcile an uncertain write before retrying. Removing their existing capabilities or duplicating their business rules in MCP would be a larger, separate migration. Their mappings are tested; full live mobile workflows are not claimed verified by the v1 integration test.

Compatibility changes from the old prototype

Core task/comment/deliverable tools now use /api/v1 rather than /api/mobile. Replace old assignee_id with assignees, lowercase priorities with canonical priorities, flat work_for fields with project/client IDs, and task category_id with supported API fields only. include_completed/needs_review are not silently emulated on v1; use supported list filters. Reconnect/reload tool discovery after upgrading. Update calls need expected_updated_at and all core writes need idempotency_key. Fake-data runtime files and obsolete mock tests were removed.

Verification

npm test

This builds TypeScript and checks validation, configuration, request mapping, HTTP errors and a real SDK stdio handshake/tool call against a fixture HTTP server. The official MCP TypeScript SDK is pinned in the lockfile; the maintained 1.x API avoids an unrelated protocol migration.

For MCP → real Athena routes → PostgreSQL acceptance, follow Athena-Context/docs/api-mcp-contract.md. That suite runs discovery, concurrent create/retry, read-back, update/retry, stale rejection, cross-team rejection, pagination, comments and deliverables. It uses a disposable loopback PostgreSQL database and does not call providers.