@roadmapperai/mcp 0.4.0 → 0.6.0

package/package.json

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

@@ -160,6 +160,136 @@ 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
@@ -960,7 +1090,8 @@ const TOOLS = [
       "USE WHEN: the user asks to plan features, design new work, sketch a roadmap, file a TODO that should persist beyond this conversation, or break a capability into deliverables.\n" +
       "PREREQUISITE: get_agents_md once this session (the server enforces this and returns an error with a `fix` field if missing). Call suggest_capability_for first to find the right parent capability — do not invent a new one.\n" +
       "ANTI-PATTERN: do not call to track in-progress work within a single conversation — use the harness TodoWrite tool. Do not call to log a bug discovered during implementation — file in the issue tracker, not roadmapper. Do not call when you don't know which capability the task belongs under; resolve that first.\n" +
-      "EXAMPLE: propose_task({ capabilityId: 'CAP-XXX', title: 'Drag-and-drop block reorder', acceptance: ['Block can be dragged with mouse + keyboard', 'Order persists across reloads'], idempotencyKey: 'session-1-task-3' })\n\n" +
+      "REQUIRED FIELDS: capabilityId, title, effort. Always size the task — XS (≤2h) / S (≤1d) / M (~1-3d) / L (~1-2w) / XL (>2w). Effort drives capability % roll-up weighting; do not omit.\n" +
+      "EXAMPLE: propose_task({ capabilityId: 'CAP-XXX', title: 'Drag-and-drop block reorder', effort: 'M', acceptance: ['Block can be dragged with mouse + keyboard', 'Order persists across reloads'], idempotencyKey: 'session-1-task-3' })\n\n" +
       "Requires SUPABASE_SERVICE_ROLE_KEY. Pass idempotencyKey so retries don't duplicate. Pass dryRun: true to validate without writing. Pass workspaceId to target a workspace other than the env default.",
     inputSchema: {
       type: "object",
@@ -988,7 +1119,7 @@ const TOOLS = [
         dryRun: { type: "boolean" },
         workspaceId: { type: "string" },
       },
-      required: ["capabilityId", "title"],
+      required: ["capabilityId", "title", "effort"],
       additionalProperties: false,
     },
   },
@@ -3123,7 +3254,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 ?? {});