@roadmapperai/mcp 0.7.1 → 0.9.0

package/AGENTS.md

@@ -32,12 +32,29 @@ Roadmapper ships with `mcp/server.mjs`, a stdio MCP server. Read tools
 let you plan against real IDs; write tools let you act through the
 same surface when the operator has wired in a service-role key.
 
+**Output is light by default.** All collection reads
+(`get_roadmap_snapshot`, `list_tasks`, `list_capabilities`,
+`list_uncategorized_tasks`) return **light rows** — identity + the few
+fields you triage on — and are **capped** (50 rows for the list tools,
+50 tasks for the snapshot), wrapped in a `{ total, returned, truncated,
+items }` envelope (the snapshot uses `counts` + `tasksTruncated`).
+Heavy fields (`prs[]`, `acceptance[]`, `acceptanceGrades[]`,
+`outcomeReadings[]`, `dependsOn[]`, long `summary`/`description`) are
+omitted. This keeps a cold-start read from blowing the token budget on
+a large workspace. To get full rows, pass `detail: true`; to raise the
+cap, pass `limit` (max 200). **If `truncated` is true, narrow your
+filter** (`capabilityId` / `status`) rather than cranking `limit` —
+that's almost always what you actually want.
+
 **Read tools** (always available):
 - `get_roadmap_snapshot` — **start here**. One-call orient: returns
   themes, active capabilities, and in-flight tasks for the workspace
   in a single response. Saves you three round trips when you're just
-  trying to orient. Always live, never cached. Response includes the
-  resolved `workspaceId` you should pass back on any write call.
+  trying to orient. Always live, never cached. Light + capped by
+  default (see above); pass `detail: true` for full rows. Response
+  includes the resolved `workspaceId` you should pass back on any
+  write call, plus `mode` and `counts` (true totals regardless of the
+  task cap).
 - `list_themes` — get the theme catalogue.
 - `list_capabilities` — filter by `themeId` to scope your plan.
   **Excludes delivered capabilities by default** — agents should
@@ -47,8 +64,27 @@ same surface when the operator has wired in a service-role key.
   reopened, which is rare and should be a human call).
 - `list_tasks` — filter by `capabilityId` and/or `status` to see what
   already exists before proposing duplicates.
+- `list_uncategorized_tasks` — the orphaned backlog: tasks with no
+  parent capability (`capabilityId` null), typically auto-created by
+  the GitHub webhook from PRs that carried no `Roadmapper-Capability:`
+  trailer and matched no capability. Use for triage — pair with
+  `suggest_capability_for({ taskId })` then `move_task` to file each
+  one. A long result is a signal that PRs aren't carrying trailers.
 - `get_task` — full task detail, including `acceptance`, `dependsOn`,
   and attached PRs.
+- `suggest_capability_for` — rank existing capabilities by token
+  overlap against either a free-text `description` OR an existing
+  `taskId` (the server synthesizes the query from the task's title +
+  summary). The `taskId` form is the triage companion to
+  `list_uncategorized_tasks`. Pass exactly one of the two.
+- `detect_capability_gaps` — the "a bet is **missing**" signal.
+  Clusters uncategorized tasks that fit *no* existing capability and
+  reports each cluster with shared keywords + a suggested capability
+  name. Distinct from `suggest_capability_for`, which finds an
+  *existing* home; this finds work with *no* home. Each gap is a
+  CANDIDATE for `propose_capability` (human-confirmed) followed by
+  `move_tasks`. Tune `minClusterSize` (default 3) / `fitThreshold`
+  (default 0.2) to control sensitivity.
 - `get_agents_md` — re-read this contract on demand.
 
 **Multi-workspace addressing.** A single MCP install can talk to any
@@ -92,6 +128,15 @@ to "tell the human what I'd do"):
   session id + a per-task counter) so a retry after a crash or
   transient error reuses the existing task instead of creating a
   duplicate. Response includes `idempotent: true` when that happens.
+  **Warn-on-skip:** if you call `propose_task` without having surveyed
+  capabilities this session (no `suggest_capability_for` /
+  `list_capabilities` / `get_roadmap_snapshot`), the response carries a
+  `warnings[]` entry + `_meta` nudge — and if the task text fits a
+  *different* capability noticeably better than the one you chose, it
+  names that capability so you can `move_task` it. The write still
+  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_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

package/README.md

@@ -62,15 +62,33 @@ Read tools (always available):
 - `list_themes` — top-level strategic themes
 - `list_capabilities` — capabilities (optionally filtered by theme)
 - `list_tasks` — tasks (optionally filtered by capability or status)
+- `list_uncategorized_tasks` — tasks with no parent capability (orphans the
+  webhook created from PRs with no `Roadmapper-Capability:` trailer); triage
+  entry point
 - `get_task` — full task detail including acceptance criteria + deps
 - `get_agents_md` — the planning rubric (the contract for proposals)
 - `get_roadmap_snapshot` — current state of the whole roadmap
-- `suggest_capability_for` — find existing capability that matches a description
+- `get_active_workspace` — which workspace this server is pointed at and how
+  it resolved (arg / snapshot / env); confirm before writing
+- `suggest_capability_for` — find the existing capability matching a
+  free-text description **or** an existing `taskId` (synthesizes the query
+  from the task's title + summary)
 - `suggest_theme_for` — find existing theme that matches a description
+- `detect_capability_gaps` — cluster orphaned tasks that fit no existing
+  capability and flag where a new bet is likely missing
 - `list_stale_outcomes` — capabilities whose outcome metric hasn't been
   re-read recently
 
-Write tools (require workspace-scoped write auth — coming in v0.2):
+> **Output is light by default.** The collection reads
+> (`get_roadmap_snapshot`, `list_tasks`, `list_capabilities`,
+> `list_uncategorized_tasks`) return light rows and are capped (50), wrapped
+> in a `{ total, returned, truncated, items }` envelope. Pass `detail: true`
+> 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`
+to an `rmpr_…` key from the dashboard; writes then route through the
+mcp-broker so the service-role key never lives on your machine):
 
 - `propose_theme`, `propose_capability`, `propose_task` — file new work
 - `update_theme`, `update_capability`, `update_task` — patch existing rows
@@ -89,6 +107,8 @@ The intended loop:
    `list_capabilities` / `list_tasks`.
 3. Before proposing anything new, agent calls `suggest_capability_for`
    (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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@roadmapperai/mcp",
-  "version": "0.7.1",
+  "version": "0.9.0",
   "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",