@ezmodo/mcp-server 0.17.1 → 0.19.0

package/config/endpoint-map.js

@@ -29,6 +29,17 @@ export const ENDPOINT_MAP = {
   'mcpSearchEpics': { route: 'mcp/v1/epics/search', method: 'POST' },
   'mcpListEpics': { route: 'mcp/v1/epics', method: 'GET' },
   'mcpGetEpic': { route: 'mcp/v1/epics/by-id', method: 'GET' },
+  // E-259: epic plan with revisions.
+  'mcpGetEpicPlan': { route: 'mcp/v1/epics/plan', method: 'GET' },
+  'mcpUpdateEpicPlan': { route: 'mcp/v1/epics/plan', method: 'PUT' },
+  'mcpListEpicComments': { route: 'mcp/v1/epics/comments', method: 'GET' },
+  // Catch me up (E-259 #2746).
+  'mcpGetEpicActivity': { route: 'mcp/v1/epics/activity', method: 'GET' },
+  // Plan proposals (E-259 #2745): suggest a change to a plan you cannot save.
+  'mcpListPlanProposals': { route: 'mcp/v1/epics/proposals', method: 'GET' },
+  'mcpProposePlanChange': { route: 'mcp/v1/epics/proposals', method: 'POST' },
+  'mcpReviewPlanProposal': { route: 'mcp/v1/epics/proposals/review', method: 'POST' },
+  'mcpAddEpicComment': { route: 'mcp/v1/epics/comments', method: 'POST' },
   // E-237 #2382: the epic is the fifth consumer of the grounding engine.
   'mcpGenerateEpicHowItWorks': { route: 'mcp/v1/epics/generate-how-it-works', method: 'POST' },
   'mcpApplyEpicHowItWorks': { route: 'mcp/v1/epics/apply-how-it-works', method: 'POST' },
@@ -209,6 +220,11 @@ export const ENDPOINT_MAP = {
   'mcpPromoteDecisionFromKnowledge': { route: 'mcp/v1/decisions/promote-from-knowledge', method: 'POST' },
   'mcpLinkDecisionArtifact': { route: 'mcp/v1/decisions/link', method: 'POST' },
   'mcpUnlinkDecisionArtifact': { route: 'mcp/v1/decisions/link', method: 'DELETE' },
+  // Decisions to make on an epic (E-259).
+  'mcpAddDecisionInput': { route: 'mcp/v1/decisions/inputs', method: 'POST' },
+  'mcpDecideDecision': { route: 'mcp/v1/decisions/decide', method: 'POST' },
+  'mcpHoldTaskForDecision': { route: 'mcp/v1/decisions/holds', method: 'POST' },
+  'mcpReleaseTaskFromDecision': { route: 'mcp/v1/decisions/holds', method: 'DELETE' },
 
   // Recurring task schedules (E-211) — "what task to create, on what cadence".
   'mcpCreateRecurringTask': { route: 'mcp/v1/recurring-tasks', method: 'POST' },
@@ -254,6 +270,10 @@ export const ENDPOINT_MAP = {
   'mcpDiscoverScreens': { route: 'mcp/v1/screens/discover', method: 'GET' },
   'mcpImportScreens': { route: 'mcp/v1/screens/import', method: 'POST' },
   'mcpSyncScreens': { route: 'mcp/v1/screens/sync', method: 'POST' },
+  'mcpListUnmappedPaths': { route: 'mcp/v1/unmapped-paths', method: 'GET' },
+  'mcpAssignUnmappedPath': { route: 'mcp/v1/unmapped-paths/assign', method: 'POST' },
+  'mcpDismissUnmappedPath': { route: 'mcp/v1/unmapped-paths/dismiss', method: 'POST' },
+  'mcpReconcileUnmappedPaths': { route: 'mcp/v1/unmapped-paths/reconcile', method: 'POST' },
   'mcpLinkCatalog': { route: 'mcp/v1/catalogs/link', method: 'POST' },
   'mcpUnlinkCatalog': { route: 'mcp/v1/catalogs/link', method: 'DELETE' },
   // Item-level links (E-218) — attach work or an external URL to one catalog entry

package/handlers/decisions.js

@@ -25,8 +25,13 @@ export async function manageDecision(args) {
   case 'unlink': return unlinkDecisionArtifact(params);
   case 'supersede': return supersedeDecision(params);
   case 'promote_from_knowledge': return promoteFromKnowledge(params);
+  case 'add_input': return addDecisionInput(params);
+  case 'decide': return decideDecision(params);
+  case 'hold_task': return holdTask(params);
+  case 'release_task': return releaseTask(params);
   default:
-    throw new Error(`Unknown action: ${action}. Expected create, update, delete, link, unlink, supersede, or promote_from_knowledge.`);
+    throw new Error(`Unknown action: ${action}. Expected create, update, delete, link, unlink, ` +
+      'supersede, promote_from_knowledge, add_input, decide, hold_task, or release_task.');
   }
 }
 
@@ -48,6 +53,13 @@ export async function getDecision(args) {
     return result;
   }
 
+  // Decisions to make on an epic (E-259).
+  if (filters.epicId) {
+    const params = { epicId: filters.epicId };
+    if (filters.status) params.status = filters.status;
+    return callZephlyAPI('mcpListDecisions', params);
+  }
+
   // List mode
   const params = {};
   if (organizationId) params.organizationId = organizationId;
@@ -66,6 +78,10 @@ export async function getDecision(args) {
 async function createDecision(args) {
   // `links` is applied by the MCP layer after the decision exists (E-225).
   const { links, ...createArgs } = args;
+  // On create the server takes option labels; accept {label} objects too.
+  if (Array.isArray(createArgs.choices)) {
+    createArgs.choices = createArgs.choices.map((c) => (typeof c === 'string' ? c : c?.label));
+  }
   const result = await callZephlyAPI('mcpCreateDecision', createArgs);
 
   // Attach create-time links (E-225) — best effort, never fails the create.
@@ -79,6 +95,11 @@ async function createDecision(args) {
 }
 
 async function updateDecision(args) {
+  // On update the server takes the full list as {id, label}; a bare string is
+  // a new option.
+  if (Array.isArray(args.choices)) {
+    args = { ...args, choices: args.choices.map((c) => (typeof c === 'string' ? { label: c } : c)) };
+  }
   return callZephlyAPI('mcpUpdateDecision', args);
 }
 
@@ -112,3 +133,24 @@ async function promoteFromKnowledge({ organizationId, taskId, knowledgeId, title
     linkToId,
   });
 }
+
+// --- Decisions to make on an epic (E-259) ---
+
+// Record a pick. It counts for the person whose key is used, and replaces
+// their earlier pick; the server records which AI made it.
+async function addDecisionInput({ decisionId, choiceId, reason }) {
+  return callZephlyAPI('mcpAddDecisionInput', { decisionId, choiceId, reason });
+}
+
+// Decide. The server refuses anyone but the epic's owner or an editor.
+async function decideDecision({ decisionId, status, choiceId, decision, rejectedReasons }) {
+  return callZephlyAPI('mcpDecideDecision', { decisionId, status, choiceId, decision, rejectedReasons });
+}
+
+async function holdTask({ decisionId, taskId }) {
+  return callZephlyAPI('mcpHoldTaskForDecision', { decisionId, taskId });
+}
+
+async function releaseTask({ decisionId, taskId }) {
+  return callZephlyAPI('mcpReleaseTaskFromDecision', { decisionId, taskId });
+}

package/handlers/epics.js

@@ -188,3 +188,123 @@ export async function getEpic(args) {
   if (webUrl && result?.epic) result.epic.webUrl = webUrl;
   return result;
 }
+
+/**
+ * Read an epic's plan with its current revision (E-259).
+ */
+export async function getEpicPlan(args) {
+  return callZephlyAPI('mcpGetEpicPlan', args);
+}
+
+/**
+ * Save an epic's plan against the revision it was read at (E-259). A conflict
+ * is returned as a result, not thrown: it is an expected outcome when several
+ * people's AIs share a plan, and the agent needs the current plan and what
+ * changed to redo its edit.
+ */
+export async function updateEpicPlan(args) {
+  try {
+    return await callZephlyAPI('mcpUpdateEpicPlan', args);
+  } catch (err) {
+    if (err?.code === 'PLAN_CONFLICT') {
+      const details = err.details || {};
+      return {
+        saved: false,
+        conflict: true,
+        message: `Someone else changed this plan since revision ${details.baseRevision}. ` +
+          'Nothing was saved. Apply your change to the current plan below and save again with ' +
+          `baseRevision ${details.currentRevision}. Do not resend your old copy.`,
+        currentRevision: details.currentRevision,
+        changesSince: details.changesSince || [],
+        currentPlan: details.current || null,
+      };
+    }
+    throw err;
+  }
+}
+
+/**
+ * Catch me up (E-259 #2746): what changed on an epic since the caller last
+ * looked. Marks it caught up unless markSeen is false.
+ */
+export async function getEpicActivity(args) {
+  const params = { epicId: args.epicId };
+  if (args.since) params.since = args.since;
+  if (args.markSeen === false) params.markSeen = 'false';
+  return callZephlyAPI('mcpGetEpicActivity', params);
+}
+
+/**
+ * An epic's discussion, oldest first (E-259).
+ */
+export async function listEpicComments(args) {
+  return callZephlyAPI('mcpListEpicComments', args);
+}
+
+/**
+ * Post to an epic's discussion, or reply in a thread (E-259).
+ */
+export async function addEpicComment(args) {
+  return callZephlyAPI('mcpAddEpicComment', args);
+}
+
+/**
+ * Suggest a change to an epic's plan, and answer suggestions (E-259 #2745).
+ *
+ * One tool with actions rather than five tool names: the tool list is read by
+ * every agent on every call, so each new name costs everyone.
+ */
+export async function managePlanProposal(args = {}) {
+  const { action } = args;
+
+  switch (action) {
+    case 'propose': {
+      if (!args.epicId) throw new Error('epicId is required to suggest a change');
+      if (!args.plan && !args.ops) {
+        throw new Error('Send the plan you want (or the individual changes) to suggest a change');
+      }
+      return callZephlyAPI('mcpProposePlanChange', {
+        epicId: args.epicId,
+        plan: args.plan,
+        ops: args.ops,
+        title: args.title,
+        rationale: args.rationale,
+      });
+    }
+
+    case 'list': {
+      if (!args.epicId) throw new Error('epicId is required to list proposals');
+      const params = { epicId: args.epicId };
+      if (args.status) params.status = args.status;
+      return callZephlyAPI('mcpListPlanProposals', params);
+    }
+
+    case 'get': {
+      if (!args.proposalId) throw new Error('proposalId is required');
+      return callZephlyAPI('mcpListPlanProposals', { proposalId: args.proposalId });
+    }
+
+    case 'review': {
+      if (!args.proposalId) throw new Error('proposalId is required to answer a proposal');
+      if (!args.accept?.length && !args.reject?.length) {
+        throw new Error('Say which changes you are taking (accept) and which you are not (reject)');
+      }
+      return callZephlyAPI('mcpReviewPlanProposal', {
+        proposalId: args.proposalId,
+        accept: args.accept || [],
+        reject: args.reject || [],
+        note: args.note,
+      });
+    }
+
+    case 'withdraw': {
+      if (!args.proposalId) throw new Error('proposalId is required to take back a proposal');
+      return callZephlyAPI('mcpReviewPlanProposal', { proposalId: args.proposalId, withdraw: true });
+    }
+
+    default:
+      throw new Error(
+        `Unknown action "${action}". Use propose, list, get, review or withdraw.`
+      );
+  }
+}

package/handlers/index.js

@@ -14,6 +14,7 @@ import * as featureHandlers from './features.js';
 import * as decisionHandlers from './decisions.js';
 import * as designHandlers from './designs.js';
 import * as catalogHandlers from './catalogs.js';
+import * as unmappedPathHandlers from './unmapped-paths.js';
 import * as featureFlagHandlers from './feature-flags.js';
 import * as taskHandlers from './tasks.js';
 import * as documentHandlers from './documents.js';
@@ -58,6 +59,12 @@ export const HANDLERS = {
   search_epics: epicHandlers.searchEpics,
   list_epics: epicHandlers.listEpics,
   get_epic: epicHandlers.getEpic,
+  get_epic_plan: epicHandlers.getEpicPlan,
+  update_epic_plan: epicHandlers.updateEpicPlan,
+  list_epic_comments: epicHandlers.listEpicComments,
+  get_epic_activity: epicHandlers.getEpicActivity,
+  manage_plan_proposal: epicHandlers.managePlanProposal,
+  add_epic_comment: epicHandlers.addEpicComment,
 
   // Milestones
   manage_milestone: milestoneHandlers.manageMilestone,
@@ -86,6 +93,8 @@ export const HANDLERS = {
   manage_catalog: catalogHandlers.manageCatalog,
   get_catalog: catalogHandlers.getCatalog,
   list_catalogs: catalogHandlers.listCatalogs,
+  list_unmapped_paths: unmappedPathHandlers.listUnmappedPaths,
+  resolve_unmapped: unmappedPathHandlers.resolveUnmapped,
   list_catalog_items: catalogHandlers.listCatalogItems,
   get_catalog_diff: catalogHandlers.getCatalogDiff,
 

package/handlers/unmapped-paths.js

@@ -0,0 +1,60 @@
+/**
+ * Unmapped code path handlers (E-258 #2756)
+ *
+ * Thin wrappers over /api/mcp/v1/unmapped-paths. Dispatch and validation live
+ * server-side in core/unmappedpaths.Service; these only shape the arguments.
+ */
+
+import { callZephlyAPI } from '../lib/http-client.js';
+
+/**
+ * List a project's unmapped paths, pending by default.
+ */
+export async function listUnmappedPaths({ projectId, status }) {
+  if (!projectId) {
+    throw new Error('projectId is required');
+  }
+  const params = { projectId };
+  if (status) params.status = status;
+  return callZephlyAPI('mcpListUnmappedPaths', params);
+}
+
+/**
+ * Dispatch resolve_unmapped actions.
+ */
+export async function resolveUnmapped(args) {
+  const { action, ...params } = args;
+  switch (action) {
+  case 'reconcile': return reconcileUnmappedPaths(params);
+  case 'assign': return assignUnmappedPath(params);
+  case 'dismiss': return dismissUnmappedPath(params);
+  default:
+    throw new Error(`Unknown action: ${action}. Expected reconcile, assign, or dismiss.`);
+  }
+}
+
+// Close every pending row an existing feature path already covers. Rows several
+// features could claim are left pending on purpose.
+async function reconcileUnmappedPaths({ projectId }) {
+  requireProject(projectId, 'reconcile');
+  return callZephlyAPI('mcpReconcileUnmappedPaths', { projectId });
+}
+
+async function assignUnmappedPath({ projectId, pathId, featureId }) {
+  requireProject(projectId, 'assign');
+  if (!pathId) throw new Error('pathId is required for assign');
+  if (!featureId) throw new Error('featureId is required for assign');
+  return callZephlyAPI('mcpAssignUnmappedPath', { projectId, pathId, featureId });
+}
+
+async function dismissUnmappedPath({ projectId, pathId }) {
+  requireProject(projectId, 'dismiss');
+  if (!pathId) throw new Error('pathId is required for dismiss');
+  return callZephlyAPI('mcpDismissUnmappedPath', { projectId, pathId });
+}
+
+function requireProject(projectId, action) {
+  if (!projectId) {
+    throw new Error(`projectId is required for ${action}`);
+  }
+}

package/http.js

@@ -7,8 +7,10 @@
  * lib/create-server.js, so the tool surface cannot differ between them.
  *
  * ── Stateless, and why ────────────────────────────────────────────────────────
- * A fresh Server and transport are built per request, with
- * `sessionIdGenerator: undefined`. The alternative — stateful sessions held in
+ * A fresh Server is built per request: SDK v2's createMcpHandler calls the
+ * factory each time, and serves 2025-era clients through the same stateless
+ * idiom v1 used (`sessionIdGenerator: undefined`, a transport per request).
+ * 2026-07-28 is stateless by design. The alternative — stateful sessions held in
  * memory — cannot survive the deployment target: Cloud Run runs several
  * instances with no session affinity, so a client's second request routinely
  * lands on an instance that has never heard of its session and is rejected with
@@ -35,7 +37,9 @@
 
 import { createServer as createHttpServer } from 'node:http';
 import { randomUUID } from 'node:crypto';
-import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { createMcpHandler } from '@modelcontextprotocol/server';
+import { toNodeHandler } from '@modelcontextprotocol/node';
 
 import { createServer } from './lib/create-server.js';
 import { withRequestContext } from './lib/request-context.js';
@@ -43,12 +47,15 @@ import { initLogger, getLogger } from './lib/logger.js';
 import { MCP_VERSION } from './lib/version.js';
 import { CONFIG } from './config/index.js';
 import { getApiUrl } from './lib/env.js';
+import { healthPaths, describeRejectedRequest } from './lib/http-diagnostics.js';
 
-initLogger();
+// Structured: this process's stderr is read by Cloud Logging, not a person.
+initLogger(false, undefined, { structured: true });
 const log = getLogger();
 
 const PORT = Number(process.env.PORT || 8080);
 const MCP_PATH = process.env.MCP_HTTP_PATH || '/mcp';
+const HEALTH_PATHS = healthPaths(MCP_PATH);
 
 // OAuth discovery (#2601). MCP_PUBLIC_URL is this server's public identity —
 // the "resource" in RFC 9728 terms — and must be the URL a client actually
@@ -120,6 +127,43 @@ export function bearerToken(headerValue) {
   return token ? token : null;
 }
 
+// The request being served, for the handler-level onerror below. The SDK
+// reports why it refused a request only through that callback, which is set
+// once for the whole process; this is how a report finds its way back to the
+// request it is about. Same mechanism as the credential in request-context.js.
+const inFlight = new AsyncLocalStorage();
+
+// One handler for the process; the factory builds a fresh server for each
+// request. It serves protocol revision 2026-07-28 (the `server/discover`
+// Claude opens every connection with, which SDK v1 answered with a 400) and,
+// by default (legacy: 'stateless'), 2025-era clients the same stateless way
+// the v1 transport did. See the stateless note at the top.
+//
+// 'remote': excludes tools that operate on a local checkout, which do not
+// exist here and whose git helpers shell out with caller-supplied arguments
+// (#2614).
+const mcpHandler = createMcpHandler(() => createServer({ surface: 'remote' }), {
+  onerror: (error) => {
+    const current = inFlight.getStore();
+    log.warn('MCP transport rejected request', {
+      requestId: current?.requestId,
+      error: error?.message || String(error),
+      ...(current ? describeRejectedRequest(current.req, current.body) : {}),
+    });
+  },
+});
+
+const serveMcp = toNodeHandler(mcpHandler, {
+  // The adapter itself failed (converting the request, or the handler threw)
+  // and is about to answer 500.
+  onerror: (error) => {
+    log.error('MCP handler failed', {
+      requestId: inFlight.getStore()?.requestId,
+      error: error?.message || String(error),
+    });
+  },
+});
+
 function sendJson(res, status, body, extraHeaders = {}) {
   const payload = JSON.stringify(body);
   res.writeHead(status, {
@@ -173,22 +217,8 @@ async function handleMcpPost(req, res, requestId) {
     return rpcError(res, status, -32700, `Could not parse request body: ${error.message}`);
   }
 
-  // One server and transport per request — see the stateless note at the top.
-  // 'remote': excludes tools that operate on a local checkout, which do not
-  // exist here and whose git helpers shell out with caller-supplied arguments
-  // (#2614).
-  const server = createServer({ surface: 'remote' });
-  const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
-
-  // Closing on response end matters: without it every request leaks a transport
-  // and its server, and the leak only shows up under sustained load.
-  res.on('close', () => {
-    transport.close().catch(() => {});
-    server.close().catch(() => {});
-  });
-
-  await server.connect(transport);
-  await withRequestContext({ apiKey: token }, () => transport.handleRequest(req, res, body));
+  await withRequestContext({ apiKey: token }, () =>
+    inFlight.run({ requestId, req, body }, () => serveMcp(req, res, body)));
 }
 
 const httpServer = createHttpServer(async (req, res) => {
@@ -220,7 +250,7 @@ const httpServer = createHttpServer(async (req, res) => {
       });
     }
 
-    if (url.pathname === '/health' || url.pathname === '/healthz') {
+    if (HEALTH_PATHS.has(url.pathname)) {
       return sendJson(res, 200, { status: 'ok', version: MCP_VERSION, environment: CONFIG.environment });
     }
 
@@ -278,7 +308,7 @@ httpServer.listen(PORT, () => {
 for (const signal of ['SIGTERM', 'SIGINT']) {
   process.on(signal, () => {
     log.info('Shutting down', { signal });
-    httpServer.close(() => process.exit(0));
+    httpServer.close(() => mcpHandler.close().finally(() => process.exit(0)));
     setTimeout(() => process.exit(0), 10_000).unref();
   });
 }

package/index.js

@@ -7,7 +7,7 @@
  * projects, tasks, and documentation via HTTP API.
  */
 
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { serveStdio } from '@modelcontextprotocol/server/stdio';
 
 // Import configuration
 import { CONFIG } from './config/index.js';
@@ -65,11 +65,13 @@ console.error('');
 // build the same server through lib/create-server.js, so the tool surface
 // cannot differ between them.
 
-const server = createServer();
-
 async function main() {
-  const transport = new StdioServerTransport();
-  await server.connect(transport);
+  // serveStdio, not server.connect(new StdioServerTransport()): a Server wired
+  // straight to the transport speaks only the 2025-era protocol (SDK v2
+  // migration guide). serveStdio lets the client's opening message pick the
+  // era, 2026-07-28 or 2025, and pins one instance from the factory for the
+  // life of the connection.
+  serveStdio(() => createServer());
   log.info('MCP server running on stdio');
   console.error('✅ ezmodo MCP Server running on stdio');
 }

package/lib/create-server.js

@@ -12,13 +12,7 @@
  * credential in the request context.
  */
 
-import { Server } from '@modelcontextprotocol/sdk/server/index.js';
-import {
-  CallToolRequestSchema,
-  ListToolsRequestSchema,
-  ListPromptsRequestSchema,
-  GetPromptRequestSchema,
-} from '@modelcontextprotocol/sdk/types.js';
+import { Server } from '@modelcontextprotocol/server';
 
 import { TOOLS } from '../tools/index.js';
 import { HANDLERS } from '../handlers/index.js';
@@ -105,9 +99,9 @@ export function createServer({ surface = 'local', startSignIn = defaultStartSign
     }
   );
 
-  server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools }));
+  server.setRequestHandler('tools/list', async () => ({ tools }));
 
-  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  server.setRequestHandler('tools/call', async (request) => {
     const { name, arguments: args } = request.params;
 
     // Checked before the handler lookup: a tool excluded from this surface is
@@ -214,11 +208,11 @@ export function createServer({ surface = 'local', startSignIn = defaultStartSign
 
   // Filtered by surface exactly as tools are, and for the same reason: `submit`
   // reads git SHAs and links commits, which a hosted server cannot do.
-  server.setRequestHandler(ListPromptsRequestSchema, async () => ({
+  server.setRequestHandler('prompts/list', async () => ({
     prompts: listPrompts(surface),
   }));
 
-  server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+  server.setRequestHandler('prompts/get', async (request) => {
     const content = getPromptContent(request.params.name, request.params.arguments, surface);
     if (!content) {
       throw new Error(`Unknown prompt: ${request.params.name}`);

package/lib/http-client.js

@@ -172,6 +172,12 @@ export async function callZephlyAPI(endpoint, data) {
     if (typeof error.retryable === 'boolean') {
       thrown.retryable = error.retryable;
     }
+    // Structured details, when the API sent an object rather than a sentence —
+    // a plan conflict (E-259) carries the current plan and what changed, which
+    // is exactly what the agent needs to redo its edit.
+    if (error.details && typeof error.details === 'object') {
+      thrown.details = error.details;
+    }
     throw thrown;
   }
 

package/lib/http-diagnostics.js

@@ -0,0 +1,53 @@
+/**
+ * Small pure helpers for the HTTP transport (http.js), kept here because
+ * http.js starts listening the moment it is imported and so cannot be tested.
+ */
+
+/**
+ * The paths that answer a health check.
+ *
+ * `/health` and `/healthz` are what Cloud Run's probes dial, straight at the
+ * container. `${mcpPath}/health` is the only one reachable from OUTSIDE: the
+ * load balancer forwards just `/mcp` and `/mcp/*` here, with the path
+ * unchanged, and `/health` at the domain root belongs to the web app. The
+ * uptime check has always probed `/mcp/health`, and until this was added it
+ * got a 404 every minute.
+ *
+ * @param {string} mcpPath
+ * @returns {Set<string>}
+ */
+export function healthPaths(mcpPath) {
+  return new Set(['/health', '/healthz', `${mcpPath}/health`]);
+}
+
+/**
+ * What to log about a request the MCP transport refused.
+ *
+ * The SDK answers a malformed or unsupported request with a 400 and reports
+ * why only through `transport.onerror`. Without this, production logged a 400
+ * at the start of every Claude Desktop session and nothing else, so nobody
+ * could tell which request it was or what the SDK disliked about it.
+ *
+ * Only the shape is kept: JSON-RPC methods and the protocol headers. Never the
+ * Authorization header, and never params, which can carry user content.
+ *
+ * @param {import('node:http').IncomingMessage} req
+ * @param {unknown} body parsed JSON body, possibly a batch array
+ */
+export function describeRejectedRequest(req, body) {
+  const messages = Array.isArray(body) ? body : body ? [body] : [];
+  const methods = messages.map((m) => (m && typeof m === 'object' && typeof m.method === 'string'
+    ? m.method
+    : '(no method)'));
+  const initialize = messages.find((m) => m?.method === 'initialize');
+
+  return {
+    methods,
+    batch: Array.isArray(body),
+    protocolVersionHeader: req.headers['mcp-protocol-version'] ?? null,
+    sessionIdHeader: req.headers['mcp-session-id'] ? 'present' : null,
+    initializeProtocolVersion: initialize?.params?.protocolVersion ?? null,
+    accept: req.headers.accept ?? null,
+    contentType: req.headers['content-type'] ?? null,
+  };
+}

package/lib/logger.js

@@ -19,6 +19,11 @@ import { homedir } from 'os';
 const RETENTION_DAYS = 7;
 const DATE_PATTERN = /^ezmodo-(\d{4}-\d{2}-\d{2})\.log$/;
 
+// Cloud Logging's LogSeverity names. `warn` must become WARNING: an
+// unrecognised severity is stored as DEFAULT, which a severity>=WARNING filter
+// never matches.
+const CLOUD_SEVERITY = { debug: 'DEBUG', info: 'INFO', warn: 'WARNING', error: 'ERROR' };
+
 function getDateString() {
   return new Date().toISOString().slice(0, 10);
 }
@@ -32,14 +37,28 @@ function getLogFilePath(logsDir) {
  * @param {string} [options.source='mcp']
  * @param {boolean} [options.verbose=false]
  * @param {string} [options.logsDir]
+ * @param {boolean} [options.structured=false] write stderr lines as one JSON
+ *   object each — see stderrLine
  */
 export function createLogger(options = {}) {
   const {
     source = 'mcp',
     verbose = false,
     logsDir = join(homedir(), '.ezmodo', 'logs'),
+    structured = false,
   } = options;
 
+  // Over stdio a person reads stderr in a terminal, so it stays a short line.
+  // Over HTTP it is read by Cloud Logging, which parses a JSON line into
+  // jsonPayload and maps `severity`; and the log FILE is on an ephemeral
+  // container disk nobody ever sees. Plain lines there meant the connector's
+  // warnings reached production as a bare message, with every field
+  // (requestId, error, what was rejected) lost.
+  function stderrLine(level, msg, data) {
+    if (!structured) return `[${source}] ${msg}`;
+    return JSON.stringify({ severity: CLOUD_SEVERITY[level], message: msg, source, ...data });
+  }
+
   // Ensure logs directory exists (fire-and-forget)
   let dirReady = mkdir(logsDir, { recursive: true }).catch(() => {});
 
@@ -59,10 +78,8 @@ export function createLogger(options = {}) {
     }).catch(() => {});
 
     // stderr routing: warn/error always go to stderr; debug/info only if verbose
-    if (level === 'warn' || level === 'error') {
-      console.error(`[${source}] ${msg}`);
-    } else if (verbose) {
-      console.error(`[${source}] ${msg}`);
+    if (level === 'warn' || level === 'error' || verbose) {
+      console.error(stderrLine(level, msg, data));
     }
   }
 
@@ -101,8 +118,8 @@ export function createLogger(options = {}) {
 // Singleton
 let _logger = null;
 
-export function initLogger(verbose = false, logsDir) {
-  _logger = createLogger({ source: 'mcp', verbose, logsDir });
+export function initLogger(verbose = false, logsDir, { structured = false } = {}) {
+  _logger = createLogger({ source: 'mcp', verbose, logsDir, structured });
   _logger.cleanup();
   return _logger;
 }

package/lib/remote-tools.js

@@ -58,6 +58,7 @@ export const LOCAL_ONLY_TOOLS = Object.freeze([
 /** Tools safe to serve over the remote transport. */
 export const REMOTE_SAFE_TOOLS = Object.freeze([
   'accept_agent_suggestion',
+  'add_epic_comment',
   'configure_agent',
   'create_tasks',
   'delete_attachment',
@@ -75,6 +76,8 @@ export const REMOTE_SAFE_TOOLS = Object.freeze([
   'get_document',
   'get_document_template',
   'get_epic',
+  'get_epic_activity',
+  'get_epic_plan',
   'get_feature',
   'get_feature_flag',
   'get_goal',
@@ -93,7 +96,9 @@ export const REMOTE_SAFE_TOOLS = Object.freeze([
   'list_attachments',
   'list_catalog_items',
   'list_catalogs',
+  'list_unmapped_paths',
   'list_designs',
+  'list_epic_comments',
   'list_epics',
   'list_facts',
   'list_feature_flags',
@@ -139,10 +144,13 @@ export const REMOTE_SAFE_TOOLS = Object.freeze([
   'resolve_concepts',
   'resolve_link_suggestions',
   'resolve_links',
+  'resolve_unmapped',
+  'manage_plan_proposal',
   'run_agent_now',
   'search_epics',
   'search_features',
   'search_tasks',
+  'update_epic_plan',
   'update_manifest_entries',
   'validate_manifest',
 ]);

package/lib/version.js

@@ -7,4 +7,4 @@
  *
  * Update this when bumping the version in package.json.
  */
-export const MCP_VERSION = '0.17.1';
+export const MCP_VERSION = '0.19.0';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ezmodo/mcp-server",
-  "version": "0.17.1",
+  "version": "0.19.0",
   "description": "MCP server for ezmodo - AI-first project management",
   "main": "index.js",
   "type": "module",
@@ -60,7 +60,9 @@
     "email": "help@ezmodo.com"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.30.0",
+    "@modelcontextprotocol/node": "^2.0.0",
+    "@modelcontextprotocol/server": "^2.0.0",
+    "hono": "^4.13.8",
     "node-fetch": "^3.3.2"
   },
   "devDependencies": {
@@ -70,6 +72,6 @@
     "jest": "^30.5.1"
   },
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=20.0.0"
   }
 }

package/tools/decisions.js

@@ -11,6 +11,11 @@
  * Decisions capture "why we built it this way" so the rationale survives the work
  * that produced it. A task's decision-type knowledge item can be elevated into a
  * durable Decision via promote_from_knowledge.
+ *
+ * Decisions to make (E-259): a proposed Decision asked on an epic, with a plain
+ * question, options, a recommendation and the people who should weigh in. Each
+ * of them, or their AI, adds a pick (add_input); the epic's owner or an editor
+ * decides (decide). A decision can hold tasks back until it is decided.
  */
 
 import { LINKABLE_TYPES } from './linkable-types.js';
@@ -23,17 +28,81 @@ export const DECISION_TOOLS = [
       'options, decision, consequences, status), link/unlink it to existing artifacts, mark it ' +
       'superseded by another decision, or promote a task\'s decision-type knowledge item into a ' +
       'durable Decision. Decisions are org-level and LINK to features/epics/tasks/milestones/etc., ' +
-      'they do not contain them.',
+      'they do not contain them.\n\n' +
+      'DECISIONS TO MAKE (open choices on an epic that several people weigh in on): create with ' +
+      'epicId + question + choices + recommendation + requestedFrom (the people whose view is ' +
+      'wanted; they are notified). Write the question, options and recommendation in plain ' +
+      'language a non-developer can answer. Then "add_input" records a pick (choiceId + a ' +
+      'one-line reason; your pick counts for the person whose key you use, and replaces their ' +
+      'earlier one). "decide" is for the epic\'s owner or an editor only: pass choiceId, ' +
+      'optionally decision (the answer in plain words) and rejectedReasons {choiceId: why}. ' +
+      '"hold_task" makes a task wait until the decision is made (it is blocked, and released on ' +
+      'decide); "release_task" undoes that. Do not decide on someone\'s behalf unless they asked ' +
+      'you to — add a pick instead.',
     inputSchema: {
       type: 'object',
       properties: {
         action: {
           type: 'string',
-          enum: ['create', 'update', 'delete', 'link', 'unlink', 'supersede', 'promote_from_knowledge'],
+          enum: ['create', 'update', 'delete', 'link', 'unlink', 'supersede', 'promote_from_knowledge',
+            'add_input', 'decide', 'hold_task', 'release_task'],
           description: 'Action to perform. "supersede" marks a decision as superseded by another ' +
             '(pass decisionId + supersededById). "promote_from_knowledge" elevates a task\'s ' +
             'decision-type knowledge item into a durable Decision (pass organizationId + taskId + ' +
-            'knowledgeId, optionally title + linkToType/linkToId to link it on creation).',
+            'knowledgeId, optionally title + linkToType/linkToId to link it on creation). ' +
+            '"add_input" (decisionId + choiceId + reason), "decide" (decisionId + choiceId), ' +
+            '"hold_task" / "release_task" (decisionId + taskId) are for decisions to make on an epic.',
+        },
+        // --- Decisions to make (E-259) ---
+        epicId: {
+          type: 'string',
+          description: 'Ask this decision on an epic (create). Its owner or an editor decides it; the ' +
+            'decision is scoped to the epic\'s project and linked to it.',
+        },
+        question: {
+          type: 'string',
+          description: 'The plain question to answer, e.g. "Who should review changes to the plan?" ' +
+            '(create, update)',
+        },
+        recommendation: {
+          type: 'string',
+          description: 'The recommended answer and why, in a sentence or two (create, update)',
+        },
+        choices: {
+          type: 'array',
+          items: {
+            oneOf: [
+              { type: 'string' },
+              {
+                type: 'object',
+                properties: { id: { type: 'string' }, label: { type: 'string' } },
+                required: ['label'],
+              },
+            ],
+          },
+          description: 'The options to pick from. On create, a list of plain labels. On update, the ' +
+            'full list as {id, label}: keep an option\'s id to keep the picks made for it; leave id ' +
+            'off to add one; omit an option to remove it (create, update)',
+        },
+        requestedFrom: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'User ids of the people whose view is wanted. They are notified (on update, ' +
+            'only the newly added ones) (create, update)',
+        },
+        choiceId: {
+          type: 'string',
+          description: 'An option id from the decision\'s choices, e.g. "c2" (add_input: your pick, ' +
+            'omit for "none of these" and say why in reason; decide: the chosen option)',
+        },
+        reason: {
+          type: 'string',
+          description: 'One line on why you picked it (add_input)',
+        },
+        rejectedReasons: {
+          type: 'object',
+          additionalProperties: { type: 'string' },
+          description: 'Why each option was turned down, as {choiceId: reason} (decide)',
         },
         // --- Identifiers ---
         organizationId: {
@@ -74,7 +143,9 @@ export const DECISION_TOOLS = [
         status: {
           type: 'string',
           enum: ['proposed', 'accepted', 'rejected', 'superseded', 'deprecated'],
-          description: 'Decision lifecycle status (default: "proposed") (create, update)',
+          description: 'Decision lifecycle status (default: "proposed") (create, update). For decide: ' +
+            '"accepted" (default) or "rejected" (none of the options). A decision to make on an epic ' +
+            'cannot change status through update; use decide.',
         },
         projectId: {
           type: 'string',
@@ -95,7 +166,8 @@ export const DECISION_TOOLS = [
         // --- promote_from_knowledge fields ---
         taskId: {
           type: 'string',
-          description: 'Task whose knowledge item to promote (required for promote_from_knowledge)',
+          description: 'Task whose knowledge item to promote (required for promote_from_knowledge), ' +
+            'or the task to hold back / release (hold_task, release_task)',
         },
         knowledgeId: {
           type: 'string',
@@ -121,8 +193,10 @@ export const DECISION_TOOLS = [
     name: 'get_decision',
     description: 'Retrieve a single Decision, list an organization\'s decisions, or list the decisions ' +
       'linked to a given entity (e.g. all decisions on a feature). Provide decisionId for a single ' +
-      'lookup; provide linkedType + linkedId to list decisions linked to that entity; otherwise ' +
-      'provide organizationId to list.',
+      'lookup; provide linkedType + linkedId to list decisions linked to that entity; provide ' +
+      'epicId to list the decisions to make on an epic (open ones first, each with everyone\'s ' +
+      'picks and the tasks it holds back; add status "proposed" for only the open ones); ' +
+      'otherwise provide organizationId to list.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -132,7 +206,11 @@ export const DECISION_TOOLS = [
         },
         organizationId: {
           type: 'string',
-          description: 'Organization ID (required for list, unless using linkedType + linkedId)',
+          description: 'Organization ID (required for list, unless using linkedType + linkedId or epicId)',
+        },
+        epicId: {
+          type: 'string',
+          description: 'List the decisions to make on this epic, with picks and held tasks',
         },
         linkedType: {
           type: 'string',

package/tools/epics.js

@@ -15,6 +15,28 @@
 import { LINKS_ARRAY_SCHEMA, RELATED_ITEM_SCHEMA } from './link-params.js';
 import { TASK_ITEM_PROPERTIES } from './task-item-schema.js';
 
+// A link staged on a plan or planned task before it exists (#2199, #2752).
+// Mirrors the desktop LinkDraft shape so a plan an AI saves back keeps the
+// links the desktop staged.
+const PLAN_LINKS_SCHEMA = {
+  type: 'array',
+  items: {
+    type: 'object',
+    properties: {
+      targetType: { type: 'string' },
+      targetId: { type: 'string' },
+      title: { type: 'string' },
+      source: { type: 'string', enum: ['deterministic', 'suggested', 'manual'] },
+      accepted: { type: 'boolean', description: 'false only for a suggestion that was turned down' },
+      rule: { type: 'string' },
+      confidence: { type: 'number' },
+      suggestionId: { type: 'string' },
+      matchedPaths: { type: 'array', items: { type: 'string' } },
+    },
+    required: ['targetType', 'targetId'],
+  },
+};
+
 export const EPIC_TOOLS = [
   {
     name: 'manage_epic',
@@ -259,4 +281,213 @@ export const EPIC_TOOLS = [
       },
     },
   },
+  {
+    name: 'get_epic_plan',
+    description: 'Read an epic\'s plan (E-259): the planned tasks, notes, status, staged links and any ' +
+      'open planner questions, with ' +
+      '`currentRevision`, the version number you must send back to `update_epic_plan`. ' +
+      'Several people and their AIs can work on one plan, so read it right before you change it. ' +
+      'Pass `includeHistory` to see who changed what, in plain sentences, and `revision` to read an older version.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        epicId: { type: 'string', description: 'The epic ID (required)' },
+        revision: { type: 'number', description: 'Read this saved version instead of the current one' },
+        includeHistory: {
+          type: 'boolean',
+          description: 'Also return recent versions: who saved each, which AI, and what changed',
+        },
+        historyLimit: { type: 'number', description: 'How many versions of history to return (default 20)' },
+      },
+      required: ['epicId'],
+    },
+  },
+  {
+    name: 'update_epic_plan',
+    description: 'Save an epic\'s plan as a new version (E-259). Send the WHOLE plan, changed where you ' +
+      'mean to change it, plus `baseRevision`: the `currentRevision` you read with `get_epic_plan` ' +
+      '(0 when the epic has no plan). Keep each planned task\'s `id` so the change is matched to the right task. ' +
+      'If someone else saved since you read it, nothing is written and you get `PLAN_CONFLICT` with the ' +
+      'current plan and what changed — apply your change to THAT plan and save again with its revision. ' +
+      'Never resend your old copy: that erases their work. ' +
+      'Keep plans simple and readable by anyone: a plain title and one line on why for each task. ' +
+      'Only the epic\'s owner, its creator or an organization admin can save the plan. If you are ' +
+      'refused, do not give up: send the SAME plan to manage_plan_proposal action "propose" and the ' +
+      'owner can accept your changes one at a time.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        epicId: { type: 'string', description: 'The epic ID (required)' },
+        baseRevision: {
+          type: 'number',
+          description: 'The currentRevision you started from (required; 0 for a new plan)',
+        },
+        plan: {
+          type: 'object',
+          description: 'The full plan. Fields not listed here (conversation, targetFeatureId, …) ' +
+            'are kept only if you send them back.',
+          properties: {
+            notes: { type: 'string', description: 'Assumptions, risks and scope notes' },
+            status: { type: 'string', enum: ['draft', 'approved'], description: 'draft (default) or approved' },
+            proposedTasks: {
+              type: 'array',
+              items: {
+                type: 'object',
+                properties: {
+                  id: { type: 'string', description: 'Keep the id from get_epic_plan; omit for a new task' },
+                  title: { type: 'string' },
+                  workType: { type: 'string' },
+                  description: { type: 'string' },
+                  steps: { type: 'array', items: { type: 'string' } },
+                  rationale: { type: 'string', description: 'One line on why this task exists' },
+                  dependsOnIndices: { type: 'array', items: { type: 'number' } },
+                  needsHumanGate: { type: 'boolean' },
+                  links: {
+                    ...PLAN_LINKS_SCHEMA,
+                    description: 'Links to create with this task when the plan is approved. Send back ' +
+                      'what get_epic_plan returned',
+                  },
+                },
+                required: ['title'],
+              },
+            },
+            links: {
+              ...PLAN_LINKS_SCHEMA,
+              description: 'Links for the epic, applied when the plan is approved. Send back what ' +
+                'get_epic_plan returned',
+            },
+            questions: {
+              type: 'array',
+              description: 'The planner\'s open clarifying questions, kept as returned by get_epic_plan. ' +
+                'A choice that needs several people\'s view belongs on the epic as a decision to make ' +
+                '(manage_decision with epicId) instead.',
+              items: {
+                type: 'object',
+                properties: {
+                  id: { type: 'string' },
+                  question: { type: 'string' },
+                  header: { type: 'string' },
+                  options: {
+                    type: 'array',
+                    items: {
+                      type: 'object',
+                      properties: { label: { type: 'string' }, description: { type: 'string' } },
+                      required: ['label'],
+                    },
+                  },
+                  multiSelect: { type: 'boolean' },
+                },
+                required: ['question'],
+              },
+            },
+          },
+        },
+      },
+      required: ['epicId', 'baseRevision', 'plan'],
+    },
+  },
+  {
+    name: 'get_epic_activity',
+    description: 'Catch me up on an epic (E-259): what changed since YOU last looked. Returns `summary`, ' +
+      'plain sentences you can relay to your person as-is, most important first: decisions waiting on ' +
+      'their view, comments that mention or reply to them, decisions made, new plan versions (who ' +
+      'changed what, and which AI did it for them), and tasks added, started, finished or blocked. ' +
+      'The details are alongside. Their own changes are left out. Call it when you start or resume ' +
+      'work on an epic other people also work on, and before changing its plan. By default this also ' +
+      'marks the epic as caught up, so the next call shows only newer changes; pass markSeen:false to ' +
+      'look without that.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        epicId: { type: 'string', description: 'The epic ID (required)' },
+        since: {
+          type: 'string',
+          description: 'Show changes since this time (RFC 3339, e.g. 2026-09-19T14:00:00Z) instead of ' +
+            'since the last catch-up. The first catch-up on an epic covers the last 7 days.',
+        },
+        markSeen: {
+          type: 'boolean',
+          description: 'Mark the epic as caught up after answering (default true)',
+        },
+      },
+      required: ['epicId'],
+    },
+  },
+  {
+    name: 'list_epic_comments',
+    description: 'Read an epic\'s discussion (E-259), oldest first. Each comment says who wrote it and, ' +
+      'when an AI wrote it for them, which AI (`agentName`). Replies carry `parentId`. ' +
+      'Read this before planning or changing a shared epic: other people\'s questions and objections live here.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        epicId: { type: 'string', description: 'The epic ID (required)' },
+        limit: { type: 'number', description: 'Maximum comments to return (default 100, max 500)' },
+      },
+      required: ['epicId'],
+    },
+  },
+  {
+    name: 'add_epic_comment',
+    description: 'Post to an epic\'s discussion (E-259), or reply to a comment with `parentId`. ' +
+      'Posted as the person whose key you use, marked as written by you. ' +
+      'Mentioned people, the author you reply to and everyone following the epic are notified, ' +
+      'and posting makes that person follow it. Write plainly: one point per comment, readable by anyone.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        epicId: { type: 'string', description: 'The epic ID (required)' },
+        content: { type: 'string', description: 'The comment (markdown)' },
+        parentId: { type: 'string', description: 'Reply to this comment' },
+        mentions: { type: 'array', items: { type: 'string' }, description: 'User IDs to notify' },
+      },
+      required: ['epicId', 'content'],
+    },
+  },
+  {
+    name: 'manage_plan_proposal',
+    description: 'Suggest a change to an epic\'s plan when you cannot save it yourself, and answer ' +
+      'suggestions on plans you own (E-259).\n\n' +
+      'propose: send the plan you WANT, exactly as you would to update_epic_plan. The server works out ' +
+      'what you changed and lists it as separate changes, each with a plain sentence, so the owner can ' +
+      'take some and leave others. Nothing changes until they do.\n' +
+      'list: what is waiting on an epic. Open ones come first, and each change that no longer fits the ' +
+      'current plan is flagged with the reason.\n' +
+      'review (owner, creator or org admin only): `accept` and `reject` name changes by their op id. ' +
+      'A change you name in neither is left for later and the proposal stays open. A change whose task ' +
+      'someone has since removed is reported back as stale rather than quietly reapplied.\n' +
+      'withdraw: take back a proposal you made.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        action: {
+          type: 'string',
+          enum: ['propose', 'list', 'get', 'review', 'withdraw'],
+          description: 'What to do',
+        },
+        epicId: { type: 'string', description: 'The epic (required for propose and list)' },
+        proposalId: { type: 'string', description: 'The proposal (required for get, review and withdraw)' },
+        plan: {
+          type: 'object',
+          description: 'propose: the whole plan you want, same shape as update_epic_plan. Keep each ' +
+            'planned task\'s id so your change is matched to the right task.',
+        },
+        title: { type: 'string', description: 'propose: a short name for the proposal' },
+        rationale: { type: 'string', description: 'propose: why, in a sentence or two, in plain language' },
+        accept: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'review: op ids of the changes you are taking',
+        },
+        reject: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'review: op ids of the changes you are turning down',
+        },
+        note: { type: 'string', description: 'review: what you want to say back, in your own words' },
+        status: { type: 'string', description: 'list: only proposals in this state (default: all)' },
+      },
+      required: ['action'],
+    },
+  },
 ];

package/tools/index.js

@@ -16,6 +16,7 @@ import { FEATURE_TOOLS } from './features.js';
 import { DECISION_TOOLS } from './decisions.js';
 import { DESIGN_TOOLS } from './designs.js';
 import { CATALOG_TOOLS } from './catalogs.js';
+import { UNMAPPED_PATH_TOOLS } from './unmapped-paths.js';
 import { FEATURE_FLAG_TOOLS } from './feature-flags.js';
 import { TASK_TOOLS } from './tasks.js';
 import { DOCUMENT_TOOLS } from './documents.js';
@@ -53,6 +54,7 @@ export const TOOLS = [
   ...DECISION_TOOLS,
   ...DESIGN_TOOLS,
   ...CATALOG_TOOLS,
+  ...UNMAPPED_PATH_TOOLS,
   ...FEATURE_FLAG_TOOLS,
   ...TASK_TOOLS,
   ...RECURRING_TASK_TOOLS,

package/tools/unmapped-paths.js

@@ -0,0 +1,72 @@
+/**
+ * Unmapped code path tools (E-258 #2756)
+ *
+ * When Components were retired, every component source path that belonged to no
+ * feature was recorded for review instead of being dropped. Each row is one
+ * question — "which capability owns this code?" — and until it is answered, work
+ * touching those files auto-links to nothing.
+ *
+ * The list lived only on the project Features page, so an agent asked to tidy it
+ * could set feature paths but never see or close the rows. These two tools make
+ * that loop completable.
+ */
+
+export const UNMAPPED_PATH_TOOLS = [
+  {
+    name: 'list_unmapped_paths',
+    description: 'List a project\'s unmapped code paths — former component paths that no feature owns ' +
+      '(E-258). Each row carries the source path and the component it came from. A pending row means ' +
+      'work touching those files links to no capability, so this is the backlog to work through when ' +
+      'a project\'s features are missing code ownership.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        projectId: {
+          type: 'string',
+          description: 'Project ID (required)',
+        },
+        status: {
+          type: 'string',
+          enum: ['pending', 'assigned', 'dismissed', 'all'],
+          description: 'Which rows to return (default "pending")',
+        },
+      },
+      required: ['projectId'],
+    },
+  },
+  {
+    name: 'resolve_unmapped',
+    description: 'Resolve unmapped code paths (E-258). "reconcile" is the one to reach for first: it ' +
+      'closes every pending row a feature has SINCE been given a path for, so the usual flow is to set ' +
+      'ownership with manage_feature action:"paths" and then reconcile, rather than answering rows one ' +
+      'by one. A path several features own stays pending — shared ownership is a judgement, and those ' +
+      'only ever produce link suggestions anyway.\n\n' +
+      '"assign" gives ONE row to a feature (adding that feature path, with the usual scope check), and ' +
+      '"dismiss" records that the path belongs to no capability — the right answer for shared plumbing.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        action: {
+          type: 'string',
+          enum: ['reconcile', 'assign', 'dismiss'],
+          description: 'reconcile: close every pending row an existing feature path already covers. ' +
+            'assign: give one row (pathId) to featureId. dismiss: mark one row (pathId) as owned by nobody.',
+        },
+        projectId: {
+          type: 'string',
+          description: 'Project ID (required for every action)',
+        },
+        pathId: {
+          type: 'string',
+          description: 'Unmapped path ID, from list_unmapped_paths (required for assign and dismiss)',
+        },
+        featureId: {
+          type: 'string',
+          description: 'Feature to give the path to (required for assign). It must span the project, ' +
+            'or be org-wide.',
+        },
+      },
+      required: ['action', 'projectId'],
+    },
+  },
+];