docs(plans): draft agent-transports (MCP server v1 + HTTP API v1.x)#34
docs(plans): draft agent-transports (MCP server v1 + HTTP API v1.x)#34SutuSebastian merged 3 commits intomainfrom
Conversation
Per docs/README.md Rule 3, drafts the design pass for both MCP server and HTTP API in one plan doc — they wrap the same logical operations (query / audit / recipe / context / validate / baseline ops), so the "what to expose / output shape / how audit composes" decisions settle once and each transport inherits. v1 ships MCP only: - Real demand today (we use it ourselves through Cursor / Claude Code). - Settled protocol (MCP spec; @modelcontextprotocol/sdk handles JSON-RPC). - Stays one-shot-per-session — no daemon (avoids the persistent-daemon non-goal). - Lower auth / security surface (trusted parent process). v1.x ships HTTP API: - Speculative today; defer until a concrete consumer asks. - Tangles with the persistent-daemon non-goal (codemap serve wants a long-lived process); plan reserves the design points so HTTP can inherit the v1 tool taxonomy + output shape when its turn comes. Decisions settled in the plan: - Tool taxonomy: one MCP tool per CLI top-level operation (`query`, `query_recipe`, `audit`, `save_baseline`, `baseline`, `list_baselines`, `drop_baseline`, `context`, `validate`). Rejected: mega-`cli` tool, category-grouped tools. - Output shape: every tool returns its CLI counterpart's `--json` output verbatim. No re-mapping. Future CLI envelope additions propagate to MCP automatically. - Audit composition: the existing `AuditBaselineMap` shape (per-delta baseline mapping shipped in PR #33) becomes the MCP `baselines` arg directly; resolveAuditBaselines is reused. - Resources: codemap://recipes (list + per-id), codemap://schema (DDL), codemap://skill (bundled SKILL.md text). All read-only, cached at server boot. - Naming: snake_case (matches MCP spec examples; reconsider in grill round if needed). - File layout: src/cli/cmd-mcp.ts (CLI dispatch) + src/application/ mcp-server.ts (engine — tool registry, resource handlers). Mirrors the cmd-audit.ts ↔ audit-engine.ts seam established in PR #33. - Single new dep: @modelcontextprotocol/sdk (TypeScript). Open for grilling before code: - context / validate as MCP tools (both? just context?). - Multi-statement SQL over MCP (semantic shift). - Resource caching strategy (boot-once vs per-call). - save_baseline arg shape (one tool with optional sql/recipe vs two tools). Tracer-bullet sequence (~1 day, ~7 commits) and v1 non-goals listed. Roadmap entry replaced with a single line pointing at the plan.
|
|
Warning Rate limit exceeded
To keep reviews running without waiting, you can enable usage-based add-on for your organization. This allows additional reviews beyond the hourly cap. Account admins can enable it under billing. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (2)
📝 WalkthroughWalkthroughThis pull request introduces a comprehensive plan document for agent transports, defining a v1 MCP-first design with tools mirroring existing CLI operations (query, audit, validate, etc.). The roadmap is updated to consolidate previously separate MCP and HTTP API backlog items into a unified agent transports entry. Changes
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~3 minutes Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Review rate limit: 0/1 reviews remaining, refill in 38 minutes and 26 seconds.Comment |
…sports # Conflicts: # docs/roadmap.md
|
@coderabbitai review |
✅ Actions performedReview triggered.
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/plans/agent-transports.md`:
- Line 214: The documentation line describing the `query_recipe` tool contains a
typo: replace the word "surfaceing" with the correct "surfacing" in the sentence
that reads "separate tool surfaceing the recipe catalog" (referenced by the
`query_recipe` entry) so it reads "separate tool surfacing the recipe catalog";
keep the rest of the phrasing intact for clarity.
- Around line 16-18: The fenced bash example in docs/plans/agent-transports.md
contains a shell prompt marker ("$") which triggers markdownlint MD014; update
the fenced code block for the codemap query example (the line showing codemap
query --json "SELECT name, file_path FROM symbols WHERE name = 'X'") by removing
the leading "$ " so the block begins with the raw command and ensure the fence
is ```bash (no prompt) to make the snippet lint-safe.
- Around line 172-186: The Markdown table header separator row and the
`--save-baseline[=<name>]` row are malformed (an extra third column and stray
"--------------" text) which breaks rendering; edit the table so every row has
exactly two pipe-separated columns, fix the header separator to match two
columns (e.g., `| --- | --- |` with appropriate dashes), and collapse the broken
`--save-baseline[=<name>]` row into a single two-column row mapping it to
`save_baseline` tool with `name` + (`recipe` | `sql`) inputs; also remove any
stray third-column content so other rows like `--json`, `--summary`, `--recipe
<id>`, and `--print-sql <id>` remain correctly aligned.
In `@docs/roadmap.md`:
- Line 41: Replace the non‑canonical term "recipe" with the canonical tool name
"query_recipe" in the listed surface (the line that currently reads `query` /
`audit` / `recipe` / `context` / `validate` / baseline ops) so documentation
uses the exact symbol `query_recipe`; ensure any adjacent mentions (CLI verbs or
plan references) remain consistent with `query_recipe` to avoid cross‑doc
ambiguity.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 78ae2975-f45f-401f-8ec8-ab4c7ae0f361
📒 Files selected for processing (2)
docs/plans/agent-transports.mddocs/roadmap.md
All 4 verified correct against the actual files; all applied. - agent-transports.md L17: drop `$` shell-prompt prefix in fenced bash block. markdownlint isn't enforced in CI here, but every other code block in docs/ uses bare commands — this was the only outlier. - agent-transports.md L173+L185: real markdown-rendering bug. The separator row had an unintended third column, and the `--save-baseline` row had an unescaped `|` inside `(recipe | sql)` that markdown parsed as a third cell — collapsing the row layout. Trimmed the separator to two columns and escaped the pipe. - agent-transports.md L214: typo `surfaceing` → `surfacing` in the Tracer 3 bullet. - roadmap.md L41: align the agent-transports entry's listed surface to use `query_recipe` (the canonical MCP tool name the plan settles on) instead of `recipe`. Plan body uses `query_recipe` consistently — roadmap should match.
1 participant
Summary
Per
docs/README.mdRule 3, drafts the design for MCP server (v1) and HTTP API (v1.x) in one plan doc. They wrap the same logical operations (query/audit/recipe/context/validate/ baseline ops) — settling the surface once means each transport inherits the same shape.What the plan settles
query,query_recipe,audit,save_baseline,baseline,list_baselines,drop_baseline,context,validate. Rejected: mega-clitool, category-grouped tools.--jsonenvelope. No re-mapping. Future CLI envelope additions propagate to MCP automatically.AuditBaselineMapshape from PR #33 becomes the MCPbaselines: {<deltaKey>: <name>}arg directly.resolveAuditBaselinesis reused.codemap://recipes(list + per-id),codemap://schema(DDL),codemap://skill(bundled SKILL.md text). Cached at server boot.src/cli/cmd-mcp.ts(CLI dispatch) +src/application/mcp-server.ts(engine — tool registry, resource handlers). Mirrors thecmd-audit.ts↔audit-engine.tsseam from PR #33.@modelcontextprotocol/sdk.Open questions (grill-me round before code)
contextandvalidateas MCP tools (both? justcontext?)save_baselinearg shape (one tool with optionalsql/recipevs two tools)What's NOT in v1
indextool deferred until concrete demand.Composition with the recently shipped surface
This plan reuses every CLI primitive shipped in PRs #26 / #28 / #30 / #33:
--summary/--changed-since/--group-by/ per-rowactions) → tool-arg properties of the same name (snake_cased)--save-baseline/--baseline/--baselines/--drop-baseline) → 4 dedicated MCP toolssymbols.visibilitycolumn → no MCP-specific change; reachable viaquery+ SQL--baseline <prefix>/--<delta>-baseline <name>) →baseline_prefix+baselines: {…}args on theaudittoolTest plan
bun run checkgreen (no behavior changed; pure docs).docs/README.md § Document Lifecycle— delete on ship, lift toarchitecture.md.Summary by CodeRabbit