docs(adr-010): Commonly MCP Server — kernel surface as standard MCP - #242
Closed
lilyshen0722 wants to merge 1 commit into
Closed
docs(adr-010): Commonly MCP Server — kernel surface as standard MCP#242lilyshen0722 wants to merge 1 commit into
lilyshen0722 wants to merge 1 commit into
Conversation
The CAP HTTP surface (ADR-004) is the kernel; today every driver re-derives its own in-process tool surface on top. OpenClaw agents go through a hand-rolled extension at `_external/clawdbot/extensions/commonly/`; the local-CLI wrapper has MCP plumbing but no Commonly MCP server to point at. Adding a cross-driver tool (e.g. `commonly_dm_agent` for the Task #5 nova→sam-local-codex DM cutover) requires a fork PR + submodule bump on the OpenClaw side and gives the CLI-wrapper side nothing. ADR-010 closes that gap by shipping `@commonly/mcp` — a stdio MCP server that wraps the kernel as standard MCP tools. Any MCP-capable runtime (codex, Claude Code, OpenClaw if it speaks MCP) loads one config entry and gets the standard `commonly_*` surface. Phase 1: ship the server, refactor the existing `POST /room` to dual-auth (the established `tasksApi.ts:34-36` pattern), wire sam-local-codex. Phase 2: OpenClaw migration, gated on openclaw-MCP support investigation. Phase 3: Task #5 cutover, mechanical once Phase 1 lands. Cross-references ADR-008 (per-agent MCP declarations point at this server) and adds ADR-008 + ADR-010 to the CLAUDE.md doc index. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
3 tasks
lilyshen0722
added a commit
that referenced
this pull request
Apr 27, 2026
…242) The CAP HTTP surface (ADR-004) is the kernel; today every driver re-derives its own in-process tool surface on top. OpenClaw agents go through a hand-rolled extension at `_external/clawdbot/extensions/commonly/`; the local-CLI wrapper has MCP plumbing but no Commonly MCP server to point at. Adding a cross-driver tool (e.g. `commonly_dm_agent` for the Task #5 nova→sam-local-codex DM cutover) requires a fork PR + submodule bump on the OpenClaw side and gives the CLI-wrapper side nothing. ADR-010 ships `@commonly/mcp` — a stdio MCP server that wraps the kernel as standard MCP tools. Any MCP-capable runtime (codex, Claude Code, OpenClaw if it speaks MCP) loads one config entry and gets the standard `commonly_*` surface. Phase 1: ship the server, refactor the existing `POST /room` to dual-auth (the established `tasksApi.ts:34-36` pattern), wire sam-local-codex. Phase 2: OpenClaw migration, gated on openclaw-MCP support investigation. Phase 3: Task #5 cutover, mechanical once Phase 1 lands. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Contributor
Author
|
Squashed and merged manually as 7e54c54 (per local-squash convention to preserve authorship). |
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
1 participant
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.
Summary
@commonly/mcpas a stdio MCP server that exposes CAP (/api/agents/runtime/*per ADR-004) plus dual-auth kernel-adjacent routes (/api/v1/tasks/*) as standard MCP tools. Any MCP-capable runtime loads one config entry and gets the standardcommonly_*surface — replacing today's hand-rolled extension at_external/clawdbot/extensions/commonly/.sam-local-codex) needs a newcommonly_dm_agentverb. Before this ADR, the only path was a fork PR + submodule bump on OpenClaw + nothing for the CLI-wrapper side. This ADR makes future cross-driver verbs land in one place and reach every driver.mcp[]declarations point at this server). CLAUDE.md doc index gains ADR-008 + ADR-010 entries.What's in the ADR (251 lines)
/api/v1/tasks/:podIdcorrectly), pod context, memory,commonly_dm_agent. Poll/ack deliberately omitted (turn-time tools only — host runtime owns the event loop).POST /room(line 531 ofagentsRuntime.ts) to dual-auth using the establishedtasksApi.ts:34-36pattern. No new endpoint; reusesDMService.getOrCreateAgentRoom. The route's own header comment already named this as a known gap.COMMONLY_AGENT_TOKEN). Token-staleness failure mode and recovery (operator restart) explicitly documented under Auth — not buried as an open question.Why it landed in this shape
Reviewer found three correctness bugs in the first draft (route-collision on
/dm; wrong URL for thread comments; invariant #2 contradicting the tool table by claiming CAP-only while listing/api/v1/tasks/*tools). Fixed by verifying every route againstagentsRuntime.tsandtasksApi.tsand reframing invariant #2 to honestly cover both CAP and dual-auth kernel-adjacent surfaces. Token-rotation and OpenClaw fork ownership also tightened from the review.Out of scope (tracked, not in this PR)
commonly-mcp/package + the dual-auth refactor + sam-local-codex env wiring.Test plan
Docs-only — no tests, no CI impact, no runtime change.
🤖 Generated with Claude Code