@roadmapperai/mcp 0.9.5 → 0.9.6

package/AGENTS.md

@@ -131,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\" })"
 }
 ```
 
@@ -275,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
@@ -356,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

@@ -150,6 +150,15 @@ 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%

package/package.json

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

package/server.mjs

@@ -511,7 +511,7 @@ PER-SESSION WORKFLOW
 1. Orient first: get_roadmap_snapshot (or list_themes / list_capabilities). This also satisfies the discovery gates below.
 2. Writing requires the rubric: every workspace-mutating tool (propose_*/update_*/archive_*/unarchive_*/move_*/record_outcome_reading/link_pr/submit_acceptance_grades) refuses until you call get_agents_md once this session (reading roadmapper://rubric also counts).
 3. Reuse before creating: suggest_capability_for({description}) to find an existing home; only propose a new capability if nothing fits. suggest_theme_for / list_themes before proposing a theme.
-4. Before your first write, call get_active_workspace and proceed only if its status is "resolved"; for any other status follow the \`next\` action it returns (e.g. link_repo) so writes don't land in the wrong workspace.
+4. Before your first write, call get_active_workspace. Proceed if status is "resolved", or if it's "env_default" and the named workspace is the one you intend (the common, correct case for an env-configured install — its \`next.detail\` says how to confirm). Stop and follow the \`next\` action only for "ambiguous" or "unresolved" (e.g. link_repo), so writes don't land in the wrong workspace.
 5. dryRun:true validates any write without committing. Reference everything by stable ID, never by name.
 
 MODEL (don't conflate the layers)
@@ -3800,7 +3800,9 @@ async function proposeTheme(args, projected, wsId) {
       nearest = t;
     }
   }
-  if (nearest && nearestScore >= THEME_SPRAWL_BLOCK && args.force !== true) {
+  // dryRun is exempt (like the autonomy gate below) so a validate-only call
+  // always returns a preview; the overlap is surfaced as a warning instead.
+  if (nearest && nearestScore >= THEME_SPRAWL_BLOCK && args.force !== true && !args.dryRun) {
     return textResult(
       JSON.stringify(
         {
@@ -3860,13 +3862,19 @@ async function proposeTheme(args, projected, wsId) {
   };
 
   if (args.dryRun) {
+    const warnings =
+      nearest && nearestScore >= THEME_SPRAWL_BLOCK && args.force !== true
+        ? [
+            `Overlaps existing theme ${nearest.id} (${nearest.name}) at ${nearestScore.toFixed(2)} (block bar ${THEME_SPRAWL_BLOCK}). A real call would be refused as too_similar unless force:true — prefer filing under it via ${opCall("propose_capability", `{ pillarId: "${nearest.id}", ... }`)}.`,
+          ]
+        : [];
     return textResult(
       JSON.stringify(
         {
           ok: true,
           dryRun: true,
           wouldCreate: theme,
-          warnings: [],
+          warnings,
           message: `Would create theme ${id} (${name}). No record written.`,
         },
         null,
@@ -4643,6 +4651,28 @@ async function updateEntity(kind, args, wsId, projected) {
     );
   }
 
+  // Acceptance gate (MCP-path stopgap). The SQL gate added in migration 0096
+  // ("a task can't transition to in_progress without >=1 acceptance criterion")
+  // landed on a different update_entity overload than the one this JS path
+  // calls (an overload collision — the durable fix is a SQL migration that
+  // reconciles them). Enforce it here too so the rule holds on the MCP path:
+  // we have the merged `current` and the patch, so we know the post-update
+  // acceptance and the real status transition.
+  if (
+    kind === "task" &&
+    effectivePatch.status === "in_progress" &&
+    current.status !== "in_progress"
+  ) {
+    const accAfter = Array.isArray(cleanedPatch.acceptance)
+      ? cleanedPatch.acceptance
+      : current.acceptance;
+    if (!Array.isArray(accAfter) || accAfter.length === 0) {
+      return errorResult(
+        "Cannot move a task to in_progress without at least one acceptance criterion — add acceptance in the same patch (an empty acceptance list is a stop signal)."
+      );
+    }
+  }
+
   try {
     const result = await rpcCall("update_entity", {
       p_workspace_id: wsId,
@@ -5010,10 +5040,27 @@ async function submitAcceptanceGrades(args, projected, wsId) {
     return errorResult(
       `Task ${task.id} has no acceptance criteria to grade. Add some first.`
     );
+  // Validate every grade BEFORE the RPC. The per-op inputSchema
+  // (index integer >= 0, status enum) is advisory only — nothing enforces it
+  // server-side, and since the tool-surface collapse the schema isn't even on
+  // the wire for a client to check. So guard here: a non-array drops to an
+  // opaque -32603 from the for-of, and a negative/float index reaches the SQL
+  // jsonb_set with Postgres negative-index-from-end semantics, silently
+  // overwriting an UNRELATED criterion's grade.
+  if (!Array.isArray(args.grades) || args.grades.length === 0)
+    return errorResult(
+      "grades must be a non-empty array of { index, status, note? } objects."
+    );
   for (const g of args.grades) {
-    if (g.index >= max)
+    if (!g || typeof g !== "object" || Array.isArray(g))
+      return errorResult("each grade must be an object { index, status, note? }.");
+    if (!Number.isInteger(g.index) || g.index < 0 || g.index >= max)
       return errorResult(
-        `Grade index ${g.index} is out of range (task has ${max} criteria).`
+        `Grade index ${JSON.stringify(g.index)} is invalid — must be an integer in 0..${max - 1} (task has ${max} criteria).`
+      );
+    if (g.status !== "pass" && g.status !== "fail")
+      return errorResult(
+        `Grade status for index ${g.index} must be "pass" or "fail" (got ${JSON.stringify(g.status)}).`
       );
   }
 
@@ -7193,6 +7240,88 @@ async function runSelftest() {
         }),
       pass: (r) => r?.result?.isError === true,
     },
+    {
+      // submit_acceptance_grades: a negative index must be rejected up front —
+      // otherwise it reaches the SQL jsonb_set and (negative-index-from-end)
+      // overwrites an UNRELATED criterion's grade. Direct call so the test
+      // targets the validator, not the rubric/seed gates.
+      name: "submit_acceptance_grades rejects a negative index",
+      fn: () =>
+        submitAcceptanceGrades(
+          { taskId: "TK-G", grades: [{ index: -1, status: "pass" }] },
+          { tasks: [{ id: "TK-G", acceptance: ["a", "b"] }], capabilities: [], themes: [] },
+          "ws-test"
+        ),
+      pass: (r) =>
+        r?.isError === true && (r?.content?.[0]?.text ?? "").includes("invalid"),
+    },
+    {
+      name: "submit_acceptance_grades rejects a non-array grades arg",
+      fn: () =>
+        submitAcceptanceGrades(
+          { taskId: "TK-G", grades: "not-an-array" },
+          { tasks: [{ id: "TK-G", acceptance: ["a", "b"] }], capabilities: [], themes: [] },
+          "ws-test"
+        ),
+      pass: (r) =>
+        r?.isError === true &&
+        (r?.content?.[0]?.text ?? "").includes("non-empty array"),
+    },
+    {
+      name: "submit_acceptance_grades rejects a status that isn't pass/fail",
+      fn: () =>
+        submitAcceptanceGrades(
+          { taskId: "TK-G", grades: [{ index: 0, status: "maybe" }] },
+          { tasks: [{ id: "TK-G", acceptance: ["a", "b"] }], capabilities: [], themes: [] },
+          "ws-test"
+        ),
+      pass: (r) =>
+        r?.isError === true && (r?.content?.[0]?.text ?? "").includes("pass"),
+    },
+    {
+      // MCP-path stopgap for the 0096 SQL-overload gate: a task can't move to
+      // in_progress with an empty acceptance list. Direct call with a synthetic
+      // empty-acceptance task (the gate fires before any RPC).
+      name: "update_task in_progress gate blocks a task with no acceptance",
+      fn: () =>
+        updateEntity(
+          "task",
+          { taskId: "TK-EMPTYACC", patch: { status: "in_progress" }, reason: "starting" },
+          "ws-test",
+          {
+            tasks: [{ id: "TK-EMPTYACC", status: "planned", acceptance: [] }],
+            capabilities: [],
+            themes: [],
+          }
+        ),
+      pass: (r) =>
+        r?.isError === true && (r?.content?.[0]?.text ?? "").includes("acceptance"),
+    },
+    {
+      // propose_theme dryRun must PREVIEW a near-duplicate (with a warning),
+      // not hard-block — identical tokens force jaccard >= block bar.
+      name: "propose_theme dryRun previews a near-duplicate with a warning",
+      fn: () =>
+        proposeTheme(
+          { name: "Duplicate Pillar Name", description: "identical tokens here", dryRun: true },
+          {
+            themes: [{ id: "TH-DUP", name: "Duplicate Pillar Name", description: "identical tokens here" }],
+            capabilities: [],
+            tasks: [],
+            settings: {},
+          },
+          "ws-test"
+        ),
+      pass: (r) => {
+        if (r?.isError) return false;
+        try {
+          const b = JSON.parse(r?.content?.[0]?.text ?? "{}");
+          return b.dryRun === true && Array.isArray(b.warnings) && b.warnings.length > 0;
+        } catch {
+          return false;
+        }
+      },
+    },
     {
       // The three update ops are reachable + describable via the dispatch
       // surface (not advertised by name in tools/list anymore).