@roadmapperai/mcp 0.9.4 → 0.9.6

package/AGENTS.md

@@ -7,6 +7,23 @@ The roadmap data model is the source of truth — TypeScript types in
 [`src/types.ts`](https://github.com/vsgro/roadmapper/blob/main/src/types.ts) are the canonical schema. Everything
 in this doc is downstream of that file.
 
+## How to call operations (dispatch surface)
+
+The `roadmapper` MCP server advertises **one** action tool: `roadmap({ op, args })`.
+Every operation named in this document — `get_roadmap_snapshot`, `suggest_capability_for`,
+`propose_task`, `propose_tasks`, `propose_capability`, `get_agents_md`, `link_repo`, etc. — is
+an `op` **value**, not a separately-advertised tool. Invoke it as
+`roadmap({ op: "<name>", args: { ... } })`. Two helpers round out the surface:
+
+- `roadmap_search({ intent })` — list/rank the available operations by what you're trying to do.
+- `roadmap_describe({ op })` — return one operation's exact input schema (its arguments).
+- `roadmap({ op, args })` — execute the operation. `args` may also be passed flat (top-level), but the documented shape is nested under `args`.
+
+So when a section below says "call `propose_tasks`" or shows `suggest_theme_for({ description })`,
+read it as `roadmap({ op: "propose_tasks", args: {...} })` /
+`roadmap({ op: "suggest_theme_for", args: { description } })`. The server enforces the
+rubric/discovery gates and per-op validation identically however you call.
+
 ## TL;DR — what an agent must do
 
 - Reference Themes / Capabilities / Tasks / Sprints by **stable ID**,
@@ -114,8 +131,8 @@ you do, every write tool below returns a structured error:
 ```json
 {
   "error": "prerequisite_missing",
-  "message": "Call get_agents_md first this session, then retry ...",
-  "fix": "get_agents_md()"
+  "message": "Call roadmap({ op: \"get_agents_md\" }) first this session, then retry ...",
+  "fix": "roadmap({ op: \"get_agents_md\" })"
 }
 ```
 
@@ -258,15 +275,15 @@ the first such write is **refused** with a structured error:
 {
   "error": "repo_unmapped",
   "message": "\"owner/name\" isn't mapped to a workspace ...",
-  "fix": "link_repo()",
-  "alt": "<tool>({ workspaceId: \"<target>\", ... })"
+  "fix": "roadmap({ op: \"link_repo\" })",
+  "alt": "roadmap({ op: \"<op>\", args: { workspaceId: \"<target>\", ... } })"
 }
 ```
 
 Resolve it one of two ways, then retry:
-- **`link_repo()`** — maps the repo you're in to your key's
-  workspace, so every future session resolves silently. This is
-  the right move when the repo *should* feed this workspace.
+- **`roadmap({ op: "link_repo" })`** — maps the repo you're in to
+  your key's workspace, so every future session resolves silently.
+  This is the right move when the repo *should* feed this workspace.
 - **Pass `workspaceId` explicitly** on the call — proceeds without
   mapping the repo. This is the escape hatch when you're working
   across **several repos in one session** and just want this write
@@ -339,52 +356,69 @@ PRs without submitted acceptance grades; call submit_acceptance_grades
 for TK-X, TK-Y, TK-Z." Surface these to the user; they're the
 roadmap's way of asking for the next action.
 
-Three capability tiers, driven by which env vars the operator set:
+Two install shapes:
+
+- **Customer (recommended):** `npx -y @roadmapperai/mcp` with
+  `ROADMAPPER_BACKEND_URL` + `ROADMAPPER_PUBLISHABLE_KEY` +
+  `ROADMAPPER_WORKSPACE_ID`, plus `ROADMAPPER_API_KEY` (an `rmpr_…` key)
+  to enable writes. Writes route through the mcp-broker, so no
+  service-role key ever lives on the machine. The dashboard's
+  Settings → Connect page generates this block pre-filled.
+- **Self-host / operator:** run `node mcp/server.mjs` from a local
+  checkout with the `SUPABASE_*` env vars (legacy aliases the server
+  still accepts) and the Postgres migrations applied for writes.
+
+Capability tiers, by which env vars are set (either shape):
 
 | Tier              | Required env                                                                                              | What you get                                                                  |
 |-------------------|-----------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------|
 | Seed-only         | none                                                                                                      | Read tools against the static `roadmap.json`.                                 |
-| Live read         | `SUPABASE_URL` + (`SUPABASE_PUBLISHABLE_KEY` or `SUPABASE_ANON_KEY`) + `SUPABASE_WORKSPACE_ID`             | Read tools merged with the workspace's edits.                                 |
-| Live read + write | All of the above plus `SUPABASE_SERVICE_ROLE_KEY` (and migrations 0005–0045 applied)                      | Read tools + propose_* / grade / archive_* / unarchive_* / move_* / update_* tools. |
-
-If a write tool returns an error result mentioning `SUPABASE_SERVICE_ROLE_KEY`,
-the operator is on the live-read tier; don't keep retrying — fall
-back to telling the human what you'd do and let them apply it.
-
-Sanity check the install with `node mcp/server.mjs --selftest` — runs
-every tool against the local seed and prints a pass/fail summary.
-
-If the operator chose project-scoped install (`.mcp.json` in the
-roadmapper repo root, which is the default `npm run mcp:setup` path),
-the MCP only loads when their client is launched from that repo. If
-you're an agent running in another codebase and the `roadmapper`
-tools aren't visible, ask the operator to either (a) merge the
-`mcpServers.roadmapper` block from `roadmap/.mcp.json` into their
-user-level client config or (b) point you at the roadmapper repo so
-you can run there instead.
-
-Wire-up (Claude Code, Claude Desktop, or any MCP client):
+| Live read         | `ROADMAPPER_BACKEND_URL` + `ROADMAPPER_PUBLISHABLE_KEY` + `ROADMAPPER_WORKSPACE_ID` (or the `SUPABASE_*` equivalents) | Read merged with the workspace's edits.                                       |
+| Live read + write | the above plus `ROADMAPPER_API_KEY` (`rmpr_…`, broker path) — or, self-hosting, `SUPABASE_SERVICE_ROLE_KEY` with migrations applied | Read + propose_* / grade / archive_* / unarchive_* / move_* / update_* ops. |
+
+If a write returns an error about a missing key, you're on the read
+tier; don't keep retrying — tell the human what you'd do and let them
+apply it.
+
+Sanity check (repo checkout only): `node mcp/server.mjs --selftest`
+runs every check against the bundled seed and prints a pass/fail
+summary. Run it from the **repo root** — an npm/npx install ships no
+seed file, so ~13 seed-dependent checks fail with `ENOENT` there and
+that is EXPECTED, not a broken install; the server still works over
+the wire (reads fall back to a demo seed; live edits come from the
+backend).
+
+If the operator chose project-scoped install (`.mcp.json` in the repo,
+the default `npm run mcp:setup` path), the MCP only loads when their
+client is launched from that repo. If you're an agent in another
+codebase and the `roadmapper` tools aren't visible, ask the operator
+to either (a) merge the `mcpServers.roadmapper` block into their
+user-level client config or (b) point you at the roadmapper repo.
+
+Wire-up (Claude Code, Claude Desktop, or any MCP client) — customer path:
 
 ```jsonc
 {
   "mcpServers": {
     "roadmapper": {
-      "command": "node",
-      "args": ["/absolute/path/to/roadmap/mcp/server.mjs"],
+      "command": "npx",
+      "args": ["-y", "@roadmapperai/mcp"],
       "env": {
-        "SUPABASE_URL": "https://<id>.supabase.co",
-        "SUPABASE_PUBLISHABLE_KEY": "sb_publishable_...",
-        "SUPABASE_WORKSPACE_ID": "<workspace id>",
-        "SUPABASE_SERVICE_ROLE_KEY": "<only if write tools wanted>"
+        "ROADMAPPER_BACKEND_URL": "https://<id>.supabase.co",
+        "ROADMAPPER_PUBLISHABLE_KEY": "sb_publishable_...",
+        "ROADMAPPER_WORKSPACE_ID": "<workspace id>",
+        "ROADMAPPER_API_KEY": "<rmpr_… — only if write ops wanted>"
       }
     }
   }
 }
 ```
 
-The `env` block is optional — drop it to serve the seed only. See
-[README.md](/README.md#mcp-server) for the config-file path per
-client and the full env-var matrix.
+Self-hosting from a checkout instead? Use `"command": "node"` with the
+absolute path to `mcp/server.mjs`; the `SUPABASE_*` env names are
+accepted as aliases. The `env` block is optional — drop it to serve the
+seed only. See [README.md](/README.md#mcp-server) for the config-file
+path per client and the full env-var matrix.
 
 ## The snapshot file in connected repos
 

package/README.md

@@ -57,7 +57,22 @@ JSON config works, dropped into Cursor's `mcp` field.
 
 ## What this server exposes
 
-Read tools (always available):
+**The wire surface is three dispatch tools.** As of 0.9.5 the server advertises
+only:
+
+- `roadmap_search({ intent })` — list/rank the available operations by intent
+- `roadmap_describe({ op })` — return one operation's exact input schema
+- `roadmap({ op, args })` — execute an operation
+
+Everything below is an **`op` value** passed to `roadmap`, e.g.
+`roadmap({ op: "get_roadmap_snapshot" })` or
+`roadmap({ op: "propose_tasks", args: { capabilityId, tasks: [...] } })`. This
+keeps `tools/list` tiny (one schema instead of ~34) while the per-op schemas
+load on demand via `roadmap_describe`. The full planning contract ships in the
+server's `instructions` (sent at connect) and the `get_agents_md` op /
+`roadmapper://rubric` resource.
+
+### Read operations (always available)
 
 - `list_themes` — top-level strategic themes
 - `list_capabilities` — capabilities (optionally filtered by theme)
@@ -86,7 +101,7 @@ Read tools (always available):
 > for full rows and `limit` (max 200) to raise the cap. This keeps a
 > cold-start read from blowing the token budget on a large workspace.
 
-Write tools (require workspace-scoped write auth — set `ROADMAPPER_API_KEY`
+### Write operations (require workspace-scoped write auth — set `ROADMAPPER_API_KEY`
 to an `rmpr_…` key from the dashboard; writes then route through the
 mcp-broker so the service-role key never lives on your machine):
 
@@ -100,25 +115,26 @@ mcp-broker so the service-role key never lives on your machine):
 
 ## How agents are meant to use this
 
-The intended loop:
+The intended loop (every step is `roadmap({ op, args })`):
 
-1. Agent calls `get_agents_md` to load the rubric.
-2. Agent reads the current roadmap state via `list_themes` /
-   `list_capabilities` / `list_tasks`.
-3. Before proposing anything new, agent calls `suggest_capability_for`
+1. `roadmap({ op: "get_agents_md" })` to load the rubric.
+2. Read the current roadmap state: `roadmap({ op: "get_roadmap_snapshot" })`
+   (or `list_themes` / `list_capabilities` / `list_tasks` ops).
+3. Before proposing anything new, `roadmap({ op: "suggest_capability_for", args: { description } })`
    (or `suggest_theme_for`) to check if a matching parent already exists.
-   Skipping this is allowed for `propose_task` but the response will carry
-   a warn-on-skip nudge; `propose_capability` hard-requires it.
-4. Agent proposes new rows through the `propose_*` tools, including all
-   the rubric-required fields (RICE, acceptance criteria, etc.).
-5. Once a PR is merged, the agent calls `link_pr` to attach it; the
+   Skipping is allowed for `propose_task` but the response carries a
+   warn-on-skip nudge; `propose_capability` hard-requires it.
+4. Propose new rows via `roadmap({ op: "propose_tasks", args })` /
+   `roadmap({ op: "propose_capability", args })`, including all the
+   rubric-required fields (RICE, acceptance criteria, etc.).
+5. Once a PR is merged, `roadmap({ op: "link_pr", args })` to attach it; the
    roadmap delivery stats update automatically.
-6. After delivery, the agent self-grades against the acceptance criteria
-   with `submit_acceptance_grades`.
+6. After delivery, self-grade against the acceptance criteria with
+   `roadmap({ op: "submit_acceptance_grades", args })`.
 
 The server enforces the rubric: proposals filed without first fetching
-`get_agents_md` are rejected with a remediation hint pointing the agent
-back to the rubric.
+`get_agents_md` are rejected with a structured remediation hint whose `fix`
+field names the exact dispatch call to make next.
 
 ## Versioning
 
@@ -134,6 +150,25 @@ the check with `ROADMAPPER_DISABLE_UPDATE_CHECK=1`.
 
 ### Recent changes
 
+- **0.9.6** — hardening pass on top of the 0.9.5 collapse. `submit_acceptance_grades`
+  now rejects a negative/non-integer/out-of-range `index`, a non-array `grades`,
+  and a status that isn't `pass`/`fail` (the per-op schema is no longer on the
+  wire for clients to enforce, so the handler validates). A task can no longer be
+  moved to `in_progress` with an empty acceptance list on the MCP write path.
+  `propose_theme` with `dryRun` now previews a near-duplicate (with a warning)
+  instead of hard-blocking. Server instructions no longer tell agents to proceed
+  only on `status:"resolved"` (the normal env install resolves to `env_default`).
+  Docs reconciled to the dispatch surface + customer (npx) install path.
+- **0.9.5** — **tool-surface collapse for token efficiency.** `tools/list` now
+  advertises three dispatch tools (`roadmap_search` / `roadmap_describe` /
+  `roadmap`) instead of ~34, cutting the always-loaded tool definitions ~97%
+  (~15k → ~0.5k tokens) and the per-session planning footprint ~95%. The ~34
+  operations are unchanged — they're reached as `roadmap({ op, args })`, with
+  schemas served on demand via `roadmap_describe`. Per-tool methodology moved
+  into the server `instructions` (now correctly top-level) plus the
+  `roadmapper://rubric` resource. Already-linked repos should re-run
+  `npm run mcp:setup -- --link <path>` to refresh the permission allow-list and
+  the CLAUDE.md block for the dispatch surface.
 - **0.9.3** — new `link_repo` tool: when `get_active_workspace` reports
   `env_default`/`unresolved` and you're in a git repo, one call persists
   the repo → workspace mapping so future sessions resolve silently (the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@roadmapperai/mcp",
-  "version": "0.9.4",
+  "version": "0.9.6",
   "description": "Roadmapper AI MCP server — exposes a planning surface (themes, capabilities, tasks, sprints, PRs) to coding agents via stdio JSON-RPC. Pairs with the Roadmapper AI workspace at dashboard.roadmapperai.com.",
   "keywords": [
     "mcp",