@roadmapperai/mcp 0.3.0 → 0.5.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.3.0",
+  "version": "0.5.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.
@@ -152,36 +160,190 @@ async function readAgentsMdForWorkspace() {
   return readAgentsMd();
 }
 
+/**
+ * Per-workspace label cache for tool descriptions.
+ *
+ * When a workspace renames "Theme" → "Initiative" (Settings →
+ * Customize → Labels), the dashboard already shows the new label
+ * everywhere. The MCP server also surfaces level names — inside
+ * tool descriptions the agent reads. This cache holds the
+ * resolved labels for the session so the descriptions reflect
+ * the customer's vocabulary the moment the agent connects.
+ *
+ * Loaded lazily: first tools/list call kicks off the fetch
+ * (async, doesn't block the response — first agent sees defaults,
+ * subsequent calls see the customized labels). Cache is per
+ * process lifetime; restart the MCP server to pick up label
+ * changes. (Customers rarely change labels; a restart is fine.)
+ */
+const DEFAULT_TOOL_LABELS = Object.freeze({
+  theme: "theme",
+  themes: "themes",
+  capability: "capability",
+  capabilities: "capabilities",
+  sprint: "sprint",
+  sprints: "sprints",
+  task: "task",
+  tasks: "tasks",
+});
+let labelsCache = null;
+let labelsLoadStarted = false;
+
+function pluralizeForTools(s) {
+  if (!s) return s;
+  if (s.length > 1 && s.endsWith("s")) return s;
+  const m = s.match(/([^aeiouAEIOU])y$/);
+  if (m) return s.slice(0, -1) + "ies";
+  if (/(ch|sh|x|z)$/i.test(s)) return s + "es";
+  return s + "s";
+}
+
+function normalizeFetchedLabels(raw) {
+  if (!raw || typeof raw !== "object") return DEFAULT_TOOL_LABELS;
+  const pick = (v, def) => {
+    const t = (v ?? "").trim();
+    return t.length === 0 ? def : t.toLowerCase();
+  };
+  const themeS = pick(raw.theme, "theme");
+  const capS = pick(raw.capability, "capability");
+  const sprintS = pick(raw.sprint, "sprint");
+  const taskS = pick(raw.task, "task");
+  return {
+    theme: themeS,
+    themes: pluralizeForTools(themeS),
+    capability: capS,
+    capabilities: pluralizeForTools(capS),
+    sprint: sprintS,
+    sprints: pluralizeForTools(sprintS),
+    task: taskS,
+    tasks: pluralizeForTools(taskS),
+  };
+}
+
+async function fetchWorkspaceLabels() {
+  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_labels", body: {} }),
+    });
+    if (!res.ok) return null;
+    const parsed = await res.json();
+    return normalizeFetchedLabels(parsed);
+  } catch {
+    return null;
+  }
+}
+
+/** Trigger label load once; safe to call repeatedly. */
+function startLabelLoad() {
+  if (labelsLoadStarted) return;
+  labelsLoadStarted = true;
+  fetchWorkspaceLabels().then((l) => {
+    if (l) labelsCache = l;
+  });
+}
+
+/** Resolve labels currently in effect; defaults during load. */
+function currentLabels() {
+  return labelsCache ?? DEFAULT_TOOL_LABELS;
+}
+
+/**
+ * Substitute level-name labels into a tool description.
+ *
+ * Two layers:
+ *   1. Explicit tokens — {theme}, {themes}, {capability}, etc. —
+ *      always get replaced with the customer's label (or the
+ *      default when nothing is customized).
+ *   2. Bare-word substitution — when a label differs from its
+ *      default, every word-bounded occurrence of the default in
+ *      the description is rewritten to the customized label.
+ *      Preserves leading-cap for sentence starts ("Theme" →
+ *      "Initiative", "theme" → "initiative"). Word boundaries
+ *      keep compound identifiers (themeId, capabilityId) intact.
+ *
+ * Net: a customer who renames Theme → Initiative sees every tool
+ * description talk about "initiatives" instead of "themes", with
+ * zero manual changes to this file. A workspace that doesn't
+ * customize anything reads unchanged descriptions.
+ */
+function tplDescription(text, labels) {
+  let out = text.replace(
+    /\{(theme|themes|capability|capabilities|sprint|sprints|task|tasks)\}/g,
+    (_, k) => labels[k] ?? k
+  );
+  for (const [k, v] of Object.entries(labels)) {
+    const def = DEFAULT_TOOL_LABELS[k];
+    if (!def || v === def) continue;
+    out = out.replace(new RegExp(`\\b${def}\\b`, "g"), v);
+    const DefCap = def[0].toUpperCase() + def.slice(1);
+    const VCap = v[0].toUpperCase() + v.slice(1);
+    out = out.replace(new RegExp(`\\b${DefCap}\\b`, "g"), VCap);
+  }
+  return out;
+}
+
+/**
+ * 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),
   };
 }
 
@@ -408,7 +570,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)."
     );
   }
 
@@ -442,7 +604,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}`, {
@@ -3091,7 +3253,19 @@ async function handle(request) {
       };
     }
     if (method === "tools/list") {
-      return { jsonrpc: "2.0", id, result: { tools: TOOLS } };
+      // Kick off the per-workspace label fetch (idempotent). The
+      // first call serves descriptions with defaults; subsequent
+      // calls in the same session see the customized labels once
+      // the broker responds (typically <300ms). Most MCP clients
+      // call tools/list once at connect and once after a reconnect,
+      // so the timing usually works out.
+      startLabelLoad();
+      const labels = currentLabels();
+      const tools = TOOLS.map((t) => ({
+        ...t,
+        description: tplDescription(t.description, labels),
+      }));
+      return { jsonrpc: "2.0", id, result: { tools } };
     }
     if (method === "tools/call") {
       const result = await callTool(params?.name, params?.arguments ?? {});