@ezmodo/mcp-server 0.18.0 → 0.19.1

package/config/endpoint-map.js

@@ -33,6 +33,12 @@ export const ENDPOINT_MAP = {
   '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' },

package/handlers/epics.js

@@ -224,7 +224,18 @@ export async function updateEpicPlan(args) {
 }
 
 /**
- * Read an epic's discussion (E-259).
+ * 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);
@@ -236,3 +247,64 @@ export async function listEpicComments(args) {
 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

@@ -62,6 +62,8 @@ export const HANDLERS = {
   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

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-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

@@ -76,6 +76,7 @@ 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',
@@ -144,6 +145,7 @@ export const REMOTE_SAFE_TOOLS = Object.freeze([
   'resolve_link_suggestions',
   'resolve_links',
   'resolve_unmapped',
+  'manage_plan_proposal',
   'run_agent_now',
   'search_epics',
   'search_features',

package/lib/version.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ezmodo/mcp-server",
-  "version": "0.18.0",
+  "version": "0.19.1",
   "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/epics.js

@@ -311,8 +311,9 @@ export const EPIC_TOOLS = [
       '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; anyone else ' +
-      'suggests the change with add_epic_comment or asks it as a decision to make (manage_decision).',
+      '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: {
@@ -385,6 +386,33 @@ export const EPIC_TOOLS = [
       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, ' +
@@ -416,4 +444,50 @@ export const EPIC_TOOLS = [
       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'],
+    },
+  },
 ];