@roadmapperai/mcp 0.9.3 → 0.9.5

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**,
@@ -85,6 +102,13 @@ that's almost always what you actually want.
   CANDIDATE for `propose_capability` (human-confirmed) followed by
   `move_tasks`. Tune `minClusterSize` (default 3) / `fitThreshold`
   (default 0.2) to control sensitivity.
+- `detect_theme_sprawl` — the theme-level companion. Scores every
+  active theme against every other and flags pairs that overlap enough
+  to be consolidation candidates, each with a suggested merge
+  (`move_capabilities` the lighter theme's bets into the heavier, then
+  `archive_theme`). This is how you keep theme count in check now that
+  agents create themes autonomously (see `propose_theme`). Run it at
+  quarterly review. Tune `threshold` (default 0.34).
 - `get_agents_md` — re-read this contract on demand.
 
 **Multi-workspace addressing.** A single MCP install can talk to any
@@ -137,18 +161,37 @@ to "tell the human what I'd do"):
   succeeds (this is a nudge, not a gate — unlike `propose_capability`,
   which hard-blocks until you've done discovery). Surface the warning
   to the user.
+- `propose_tasks` — **bulk** create many tasks under ONE capability in
+  a single call. **This is the token-efficient path: prefer it over N
+  separate `propose_task` calls when filing a plan** — one request, one
+  compact `{id,title}` array back. Each task spec needs `title` +
+  `effort`; intra-batch dependencies work by giving a task a `ref` and
+  listing that ref in a sibling's `dependsOn` (refs are rewritten to
+  real ids after minting). A validation error fails the whole batch
+  before writing; once valid, per-row RPC failures are reported in
+  `tasks[].error` without sinking the rest.
 - `propose_capability` — create a new capability under an **existing**
   theme. Required: `name`, `pillarId`. Sensible defaults are applied
   (`reach: 100`, `impact: 1`, `confidence: 70`). Pass `outcome` and
   `specRef` whenever you have them — capabilities without an outcome
   rarely survive review. Pass `idempotencyKey`.
-- `propose_theme` — create a new theme. **Use sparingly.** Themes are
-  years-stable strategic categories; almost every plan fits under an
-  existing one. Only call this when the human explicitly asks for a
-  new theme or when the work genuinely doesn't fit any of the existing
-  ones from `list_themes`. Default rule: if you're tempted to create
-  a theme, file a capability under the closest existing theme instead
-  and let the human reorganize later.
+- `propose_theme` — create a new theme. **Theme-autonomy is ON by
+  default**, so you MAY create a theme without human confirmation when
+  the work genuinely needs a new years-stable pillar. You don't police
+  sprawl by asking a human every time — the server does it for you:
+  `propose_theme` returns `error: "too_similar"` (naming the match) if
+  your theme overlaps an existing one above the block bar, so you reuse
+  or `update_theme` that one instead. Still prefer the deepest existing
+  parent (new task > new capability > new theme); a theme is the rare
+  case. If a workspace turned autonomy OFF (Settings → Agent
+  automation), `propose_theme` returns `error: "confirmation_required"`
+  until you surface the new theme to the user and retry with
+  `confirm: true`. Use `force: true` only to override a `too_similar`
+  block that's a genuine false positive. Run `detect_theme_sprawl`
+  periodically to catch themes that have drifted into overlap.
+- `submit_acceptance_grades` — stamp `{ status: pass | fail, note? }`
+  per criterion index, after you've actually verified the work. The
+  server stamps `gradedAt` and `gradedBy: "mcp:agent"`.
 - `submit_acceptance_grades` — stamp `{ status: pass | fail, note? }`
   per criterion index, after you've actually verified the work. The
   server stamps `gradedAt` and `gradedBy: "mcp:agent"`.
@@ -223,6 +266,45 @@ disagrees with the cwd snapshot are refused — set
 `ROADMAPPER_ALLOW_CROSS_WORKSPACE=1` in the env to override.
 Reads can target any workspace freely.
 
+**Repo-link gate (write path).** If you're in a git repo that
+isn't mapped to a workspace, a mutator would silently land on the
+install's env-default workspace — almost never what you want. So
+the first such write is **refused** with a structured error:
+
+```json
+{
+  "error": "repo_unmapped",
+  "message": "\"owner/name\" isn't mapped to a workspace ...",
+  "fix": "link_repo()",
+  "alt": "<tool>({ 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.
+- **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
+  to land on a specific existing workspace.
+
+The gate is repo-aware and only fires for a genuinely unmapped
+repo: an explicit `workspaceId`, an already-mapped repo (resolves
+via `repo_workspace_map`), or not being in a git repo at all
+pass straight through — a multi-repo chat is never bricked.
+Operators can disable the gate entirely with
+`ROADMAPPER_ALLOW_UNMAPPED_REPO=1`.
+
+This gate and the **seed-workspace guard** below are complementary,
+not redundant: the repo-link gate covers the *in a git repo but
+unmapped* case (and gives the more actionable `link_repo` fix),
+while the seed-workspace guard still catches a write that fell
+through to the bundled `"default"` workspace when you're **not** in
+any repo (nothing to link). A write can be refused by at most one of
+them; both protect the same env-default footgun from different
+angles.
+
 Authoring discipline:
 - Read first (`list_themes`, `list_capabilities`, `list_tasks`) before
   proposing anything, so you don't invent a new theme/capability that
@@ -402,12 +484,17 @@ Before writing anything:
    - **Top score 0.2–0.4**: weak overlap. The top match is still
      usually the right home; re-using a "close-enough" theme is
      almost always better than creating a duplicate.
-   - **Empty matches or top < 0.2**: no existing theme fits. Stop
-     and ask the user explicitly whether this represents a new
-     strategic direction worth a years-stable theme. Only call
-     `propose_theme` after the user confirms — themes are
-     years-stable, not per-feature.
-   The propose_theme tool enforces this discovery: skipping
+   - **Empty matches or top < 0.2**: no existing theme fits. With
+     theme-autonomy ON (the default), you may call `propose_theme`
+     directly when this is a genuinely new years-stable pillar — you
+     don't need to stop and ask. The server is the sprawl guard: it
+     refuses a near-duplicate (`error: "too_similar"`), so a theme that
+     gets created is one that doesn't already exist. With autonomy OFF,
+     `propose_theme` returns `error: "confirmation_required"` — surface
+     the theme to the user and retry with `confirm: true`. Either way,
+     prefer a capability under the closest theme when one is even
+     plausibly a fit; a new theme is the rare case.
+   The propose_theme tool enforces discovery: skipping
    `suggest_theme_for` (or `list_themes` / `get_roadmap_snapshot`)
    returns a `discovery_missing` error.
 2. **Decompose into Capabilities.** A Capability is "a quarterly
@@ -427,9 +514,18 @@ Before writing anything:
 
 ### What to emit (template)
 
-Return a single JSON block. The user will paste it into Roadmapper's
-import or read it manually; either way the field names must match
-exactly. IDs use the `__NEW__` placeholder prefix when you're
+**If the write tools are live (you can call `propose_capability` /
+`propose_tasks`), FILE DIRECTLY — do not also emit this JSON block.**
+Dumping the full plan as JSON *and* filing it via tools pays for the
+plan twice in tokens, and the tools are the canonical path anyway. Use
+`propose_capability` for the bet, then ONE `propose_tasks` call for all
+its tasks (not N `propose_task` calls), and report back a short summary
+with the returned ids — not the whole record set. The JSON block below
+is only for the **no-write-tools** case (seed/live-read tier), where
+the user pastes it into Roadmapper's import manually.
+
+When you do emit it: return a single JSON block. The field names must
+match exactly. IDs use the `__NEW__` placeholder prefix when you're
 proposing a new record — Roadmapper assigns the real `TH-NNNNNN` /
 `CAP-NNN` / `TK-NNNNNN` ID at import time.
 

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,16 @@ the check with `ROADMAPPER_DISABLE_UPDATE_CHECK=1`.
 
 ### Recent changes
 
+- **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.3",
+  "version": "0.9.5",
   "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",