Repository navigation
external api: a token-authenticated MCP surface for outside agents (#150) - #151
Merged
Merged
Conversation
) An agent outside CCS (another Claude Code session, MCPHub, a monitoring script) could only reach the internal /api/internal/task-manager door, with a per-process secret that changes on every restart, no projects and no contract. This is stage 1 of #150 — projects and tasks. Chats stay stage 2: send_message and stop_turn need a documented server contract before a wrapper can expose them. What is added: - mcp-ccs.js: a self-contained stdio MCP server (zero dependencies, http or https, CCS_URL + CCS_TOKEN) exposing list_projects, list_tasks, get_task, get_task_result, create_task and cancel_task. - api-token.js: scoped, revocable tokens. The plaintext is shown once, only its SHA-256 is stored in data/api-tokens.json (0600); scopes read|full; at most 20. - /api/external/v1/*: the whole external contract, registered in front of the session wall so an external token cannot reach chats, files, settings or terminals. A request carrying an Origin header is refused. - create_task requires an explicit project and defaults to status "backlog": an outside caller never inherits a workdir and never starts a run by accident. - scripts/api-token.js: create/list/revoke from a shell, which is the Docker path. Tests: test/api-token.test.js (store: hashed at rest, revocation immediate, a malformed file fails closed) and test/external-api.test.js, which drives the REST surface and then runs mcp-ccs.js as a real stdio MCP client — initialize, tools/list, tools/call — against a booted server. Docs: docs/EXTERNAL-API.md.
Codex Review Summary: ❌ FailedThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #150 (stage 1 — projects and tasks; chats stay stage 2 as agreed in the issue).
Why
CCS was an MCP client only. An outside agent could drive the Kanban board solely through
/api/internal/task-manager, with a per-process secret that changes on every restart, no notion of projects, and no contract that survives a release. The issue asked for a supported entry point; this is it.What is added
mcp-ccs.js— a self-contained stdio MCP server: zero dependencies, no sibling files,httporhttps, configured byCCS_URL(path prefixes supported) andCCS_TOKEN. Tools:list_projects,list_tasks,get_task,get_task_result,create_task,cancel_task.Tokens (
api-token.js) — dedicated, not the internal secret:data/api-tokens.json(mode 0600);read(list/read) andfull(also create/cancel) — creating a task runsclaude, so a monitoring client can stay read-only;node scripts/api-token.js create|list|revoke, the Docker path) or from a logged-in session (/api/api-tokens)./api/external/v1/*—me,projects,tasks,tasks/:id,tasks/:id/result,tasks/:id/cancel. Registered in front ofauth.authMiddlewareso an external token reaches nothing else: no chats, files, settings or terminals. Any request carrying anOriginheader is refused (browsers attach one; stdio clients never do).create_tasksemantics —projectis required (id or exact name, ambiguous names refused with the candidate ids) and nothing is inherited: an outside caller has no parent task whose workdir could be borrowed.statusdefaults tobacklog, so a card lands on the board and nothing runs until the caller asks fortodo; the task gets its own git worktree, like a UI card.Verification
test/external-api.test.js— boots the server and drives the REST surface end to end: 401 without a token, Origin refused, read token cannot create/cancel, missing/unknown project refused, backlog stays backlog, todo accepted with a far-future schedule, cancel + idempotence + the done guard, revocation kills the token on the next call. Then it runsmcp-ccs.jsas a real stdio client (initialize→tools/list→tools/call) against that server, including the read-only and missing-token paths.test/api-token.test.js— plaintext never on disk,0600, sha256 on disk, scope validated (never coerced), revocation immediate, malformed file fails closed, the 20-token cap.test/asar-helpers.test.js—mcp-ccs.jsis deliberately the onemcp-*.jswith nohelperPath()spawn site (it is a client for an external host, not a helper the server starts); the check now says so instead of tripping on it.test/task-text-limit.test.js— the new external write path is counted among the shared-limit writes, andmcp-ccs.js's inlined literal is pinned totask-text-limit.js.Local full suite: every test file run individually against this branch and against
main(32fa765) — failures are identical between the two and are environment-only (notmuxhere, andtask-backlog.test.js's second server onlocalhost:4553does not come up in this container); the list is in a review comment.Docs:
docs/EXTERNAL-API.md(token setup, client config for Claude Code and MCPHub, tool table, REST table, boundaries).Not in this PR
Chats:
create_chatcan reusePOST /api/sessions, butsend_message/get_messages/stop_turnhave no documented contract — the web UI drives turns over the app WebSocket. That design is stage 2.