@roadmapperai/mcp 0.2.0 → 0.4.0

package/README.md

@@ -31,15 +31,21 @@ Add to your `~/.config/claude-code/config.json` (or the equivalent
       "command": "npx",
       "args": ["-y", "@roadmapperai/mcp"],
       "env": {
-        "SUPABASE_URL": "https://tqfhcpoblluegsbkcaqq.supabase.co",
-        "SUPABASE_PUBLISHABLE_KEY": "sb_publishable_oT9...",
-        "SUPABASE_WORKSPACE_ID": "<your workspace id>"
+        "ROADMAPPER_BACKEND_URL": "https://api.roadmapperai.com",
+        "ROADMAPPER_PUBLISHABLE_KEY": "sb_publishable_...",
+        "ROADMAPPER_WORKSPACE_ID": "<your workspace id>",
+        "ROADMAPPER_API_KEY": "<rmpr_... — optional, enables writes>"
       }
     }
   }
 }
 ```
 
+The `ROADMAPPER_API_KEY` env var is optional. Without it, the install runs
+read-only (list/get/suggest tools). Mint a key in the dashboard at Settings →
+MCP activity → API keys and add it to the `env` block to unlock write tools
+(propose / link / grade).
+
 Get your workspace ID from the dashboard's URL bar
 (`dashboard.roadmapperai.com/settings` → workspace section) or from the
 generated config block in Settings → Connect.

package/package.json

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

package/server.mjs

@@ -3,42 +3,50 @@
  * Roadmapper MCP server — zero-dependency stdio JSON-RPC.
  *
  * Exposes a planning surface so an agent can read the roadmap and
- * (when authorized) propose tasks or stamp acceptance grades:
+ * (when authorized) propose tasks or stamp acceptance grades.
  *
- *   list_themes              read
- *   list_capabilities        read   (optionally filtered by themeId)
- *   list_tasks               read   (optionally filtered by capabilityId / status)
- *   get_task                 read   (full task detail, including acceptance + deps)
- *   get_agents_md            read   (the planning contract)
- *   propose_task             write  (requires SUPABASE_SERVICE_ROLE_KEY)
- *   submit_acceptance_grades write  (requires SUPABASE_SERVICE_ROLE_KEY)
+ * Customer-facing env vars (brand-named, no backend disclosure):
+ *   ROADMAPPER_BACKEND_URL       — backend project URL
+ *   ROADMAPPER_PUBLISHABLE_KEY   — public client key (RLS-scoped)
+ *   ROADMAPPER_WORKSPACE_ID      — target workspace
+ *   ROADMAPPER_API_KEY           — write auth (rmpr_… token from
+ *                                  Settings → MCP activity → API keys)
+ *   ROADMAPPER_BROKER_URL        — optional override for the write
+ *                                  broker; defaults to BACKEND_URL/
+ *                                  functions/v1/mcp-broker
  *
- * Data sources, in order:
- *   1. Local seed at src/data/roadmap.json (always read).
- *   2. Workspace edits via Supabase REST, when SUPABASE_URL,
- *      SUPABASE_WORKSPACE_ID, and either SUPABASE_PUBLISHABLE_KEY or
- *      the legacy SUPABASE_ANON_KEY are set. Edits override / extend
- *      the seed exactly like the app does.
- *   3. Writes require SUPABASE_SERVICE_ROLE_KEY (bypasses RLS). Without
- *      it the write tools return an error result and the read tools
- *      still work.
+ * Legacy operator-only env vars (still accepted for CI / maintainer
+ * local installs; not part of the customer-facing config):
+ *   SUPABASE_URL / SUPABASE_PUBLISHABLE_KEY / SUPABASE_ANON_KEY /
+ *   SUPABASE_WORKSPACE_ID / SUPABASE_SERVICE_ROLE_KEY  ← operator
+ *   ROADMAPPER_ADMIN_KEY — brand-named alias for SERVICE_ROLE_KEY
  *
- * Wire-up (Claude Code / Claude Desktop / any MCP client):
+ * Customer wire-up (Claude Code / Claude Desktop / Cursor):
  *   {
  *     "mcpServers": {
  *       "roadmapper": {
- *         "command": "node",
- *         "args": ["/absolute/path/to/roadmap/mcp/server.mjs"],
+ *         "command": "npx",
+ *         "args": ["-y", "@roadmapperai/mcp"],
  *         "env": {
- *           "SUPABASE_URL": "...",
- *           "SUPABASE_PUBLISHABLE_KEY": "sb_publishable_...",
- *           "SUPABASE_WORKSPACE_ID": "...",
- *           "SUPABASE_SERVICE_ROLE_KEY": "..."
+ *           "ROADMAPPER_BACKEND_URL": "...",
+ *           "ROADMAPPER_PUBLISHABLE_KEY": "sb_publishable_...",
+ *           "ROADMAPPER_WORKSPACE_ID": "...",
+ *           "ROADMAPPER_API_KEY": "rmpr_..."  ← optional, enables writes
  *         }
  *       }
  *     }
  *   }
  *
+ * Data sources, in order:
+ *   1. Local seed at src/data/roadmap.json (dev only; absent in npm
+ *      installs, where readSeed() falls back to an empty roadmap and
+ *      data loads from the backend).
+ *   2. Workspace edits via REST, when BACKEND_URL + PUBLISHABLE_KEY
+ *      + WORKSPACE_ID are set.
+ *   3. Writes route through ROADMAPPER_API_KEY (customer path,
+ *      validated server-side at the broker) or ROADMAPPER_ADMIN_KEY
+ *      (operator path, bypasses RLS).
+ *
  * Self-test: `node mcp/server.mjs --selftest` exercises every tool
  * against the local seed and exits 0 on success, 1 on failure. Useful
  * for verifying the install without an MCP client.
@@ -111,36 +119,101 @@ function readAgentsMd() {
   }
 }
 
+/**
+ * Fetch a workspace-scoped rubric override via the mcp-broker.
+ *
+ * Returns the workspace's custom rubric content if they've authored
+ * one in the dashboard's Settings → Workspace customization tab,
+ * null if the workspace is on the default, or null on any error
+ * (we fall back to the bundled AGENTS.md rather than refuse to
+ * serve get_agents_md).
+ *
+ * Only called when ROADMAPPER_API_KEY is set — i.e. the customer
+ * install path. Operator path (SUPABASE_SERVICE_ROLE_KEY) skips
+ * this and always serves the bundled rubric.
+ */
+async function fetchWorkspaceRubric() {
+  const { apiKey, brokerUrl } = supabaseConfig();
+  if (!apiKey || !brokerUrl) return null;
+  try {
+    const res = await fetch(brokerUrl, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+        "content-type": "application/json",
+        Accept: "application/json",
+      },
+      body: JSON.stringify({ rpc: "get_workspace_rubric", body: {} }),
+    });
+    if (!res.ok) return null;
+    const parsed = await res.json();
+    if (typeof parsed === "string" && parsed.length > 0) return parsed;
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+async function readAgentsMdForWorkspace() {
+  const custom = await fetchWorkspaceRubric();
+  if (custom) return custom;
+  return readAgentsMd();
+}
+
+/**
+ * Resolve a config value from a primary `ROADMAPPER_*` env var,
+ * falling back to a legacy `SUPABASE_*` alias when the primary
+ * isn't set. The brand-facing customer config block ships with
+ * the ROADMAPPER_* names so customers never see "supabase" in
+ * their MCP config; the SUPABASE_* aliases stay supported so
+ * existing operator / CI installs don't break on upgrade.
+ */
+function envEither(primary, ...fallbacks) {
+  for (const k of [primary, ...fallbacks]) {
+    const v = process.env[k];
+    if (v) return v;
+  }
+  return null;
+}
+
 /**
  * The read key used to fetch the workspace row. Accepts the new
  * publishable key (`sb_publishable_…`) or the legacy `anon`/JWT key.
  */
 function readKey() {
-  return (
-    process.env.SUPABASE_PUBLISHABLE_KEY ||
-    process.env.SUPABASE_ANON_KEY ||
-    null
+  return envEither(
+    "ROADMAPPER_PUBLISHABLE_KEY",
+    "SUPABASE_PUBLISHABLE_KEY",
+    "SUPABASE_ANON_KEY"
   );
 }
 
 function supabaseConfig() {
+  const url = envEither("ROADMAPPER_BACKEND_URL", "SUPABASE_URL");
   return {
-    url: process.env.SUPABASE_URL || null,
+    url,
     readKey: readKey(),
-    writeKey: process.env.SUPABASE_SERVICE_ROLE_KEY || null,
-    workspaceId: process.env.SUPABASE_WORKSPACE_ID || null,
+    // Operator path: a service-role-equivalent key. ROADMAPPER_ADMIN_KEY
+    // is the brand-facing name; SUPABASE_SERVICE_ROLE_KEY is the legacy
+    // alias used by CI and the maintainer's local workspace.
+    writeKey: envEither(
+      "ROADMAPPER_ADMIN_KEY",
+      "SUPABASE_SERVICE_ROLE_KEY"
+    ),
+    workspaceId: envEither(
+      "ROADMAPPER_WORKSPACE_ID",
+      "SUPABASE_WORKSPACE_ID"
+    ),
     // ROADMAPPER_API_KEY is the customer-facing path: a per-workspace
     // token (rmpr_…) minted from the dashboard. When set, write tools
     // route through the mcp-broker Edge Function instead of needing
     // a service-role key on the customer's machine. The broker URL
-    // defaults to the public Supabase project's edge endpoint but is
-    // overridable for self-hosted deployments / staging.
+    // defaults to the project's edge endpoint but is overridable for
+    // self-hosted deployments / staging.
     apiKey: process.env.ROADMAPPER_API_KEY || null,
     brokerUrl:
       process.env.ROADMAPPER_BROKER_URL ||
-      (process.env.SUPABASE_URL
-        ? `${process.env.SUPABASE_URL.replace(/\/$/, "")}/functions/v1/mcp-broker`
-        : null),
+      (url ? `${url.replace(/\/$/, "")}/functions/v1/mcp-broker` : null),
   };
 }
 
@@ -367,7 +440,7 @@ async function rpcCall(fn, body) {
   // injects it before calling rpcCall so the override path works.
   if (!url || !body?.p_workspace_id) {
     throw new Error(
-      "Write tools require SUPABASE_URL in env and a resolvable workspaceId (either SUPABASE_WORKSPACE_ID env or workspaceId arg)."
+      "Write tools require ROADMAPPER_BACKEND_URL in env and a resolvable workspaceId (either ROADMAPPER_WORKSPACE_ID env or workspaceId arg)."
     );
   }
 
@@ -401,7 +474,7 @@ async function rpcCall(fn, body) {
   // workspace; not what customers should ever configure.
   if (!writeKey) {
     throw new Error(
-      "Write tools require either ROADMAPPER_API_KEY (customer path) or SUPABASE_SERVICE_ROLE_KEY (operator path)."
+      "Write tools require either ROADMAPPER_API_KEY (customer path) or ROADMAPPER_ADMIN_KEY (operator path)."
     );
   }
   const res = await fetch(`${url}/rest/v1/rpc/${fn}`, {
@@ -1651,7 +1724,11 @@ async function callTool(name, args) {
       const fresh = session.rubricFetchedAt === null;
       session.rubricFetchedAt = Date.now();
       if (fresh) recordTelemetry("rubric_fetched", { via: "tool" }, wsId);
-      return textResult(readAgentsMd(), {
+      // Customer path (ROADMAPPER_API_KEY set): ask the broker for
+      // a workspace-scoped rubric. Falls back to the bundled
+      // AGENTS.md when the workspace hasn't customized one.
+      const rubric = await readAgentsMdForWorkspace();
+      return textResult(rubric, {
         _meta: {
           roadmapper: {
             reminder:
@@ -2865,7 +2942,14 @@ async function readResource(uri) {
     }
     return {
       contents: [
-        { uri, mimeType: "text/markdown", text: readAgentsMd() },
+        {
+          uri,
+          mimeType: "text/markdown",
+          // Resource handler is also async, so the workspace
+          // rubric override applies here too — same fallback chain
+          // as the get_agents_md tool.
+          text: await readAgentsMdForWorkspace(),
+        },
       ],
     };
   }