@ezmodo/mcp-server 0.19.1 → 0.20.0

package/config/endpoint-map.js

@@ -40,12 +40,18 @@ export const ENDPOINT_MAP = {
   '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' },
+  // Editors (E-259 #2802): who the owner lets change the plan.
+  'mcpManageEpicEditors': { route: 'mcp/v1/epics/editors', 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' },
 
   // Tasks
   'mcpCreateTask': { route: 'mcp/v1/tasks', method: 'POST' },
+  // Claims (E-259 #2747): manage_task action "claim" / "release".
+  'mcpClaimTask': { route: 'mcp/v1/tasks/claim', method: 'POST' },
+  // Suggested edits on someone else's claimed task (E-259 #2809).
+  'mcpTaskSuggestedEdits': { route: 'mcp/v1/tasks/suggested-edits', method: 'POST' },
   'mcpBulkCreateTasks': { route: 'mcp/v1/tasks/bulk', method: 'POST' },
   'mcpUpdateTask': { route: 'mcp/v1/tasks', method: 'PUT' },
   'mcpCompleteTask': { route: 'mcp/v1/tasks/complete', method: 'POST' },

package/handlers/epics.js

@@ -79,12 +79,23 @@ export async function manageEpic(args) {
   case 'update': return updateEpic(params);
   case 'generate_how_it_works': return generateEpicHowItWorks(params);
   case 'apply_how_it_works': return applyEpicHowItWorks(params);
+  case 'add_editor': return manageEpicEditor('add', params);
+  case 'remove_editor': return manageEpicEditor('remove', params);
   default: throw new Error(
-    `Unknown action: ${action}. Expected create, update, generate_how_it_works, or apply_how_it_works.`,
+    `Unknown action: ${action}. Expected create, update, generate_how_it_works, apply_how_it_works, ` +
+    'add_editor or remove_editor.',
   );
   }
 }
 
+// Choose who else may change an epic's plan (E-259 #2802). The server decides
+// who may do this; the tool only checks it was asked something answerable.
+async function manageEpicEditor(action, { epicId, editorUserId }) {
+  if (!epicId) throw new Error(`epicId is required to ${action} an editor`);
+  if (!editorUserId) throw new Error(`editorUserId is required to ${action} an editor`);
+  return callZephlyAPI('mcpManageEpicEditors', { epicId, userId: editorUserId, action });
+}
+
 // (Re)generate the epic's grounded, source-attributed "how it works" living
 // description (E-237 #2382). An epic's reality is its tasks — their status,
 // captured decisions and linked commits — and its intent is the epic description
@@ -231,6 +242,8 @@ export async function getEpicActivity(args) {
   const params = { epicId: args.epicId };
   if (args.since) params.since = args.since;
   if (args.markSeen === false) params.markSeen = 'false';
+  // Live mode (#2748): the API waits for news, up to its own cap.
+  if (args.waitSeconds > 0) params.waitSeconds = Math.min(Math.floor(args.waitSeconds), 25);
   return callZephlyAPI('mcpGetEpicActivity', params);
 }
 
@@ -258,53 +271,53 @@ 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 '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 '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 '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 '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 });
-    }
+  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.`
-      );
+  default:
+    throw new Error(
+      `Unknown action "${action}". Use propose, list, get, review or withdraw.`
+    );
   }
 }

package/handlers/tasks.js

@@ -54,10 +54,35 @@ export async function manageTask(args) {
   case 'get_commits': return getTaskCommits(params);
   case 'generate_how_it_works': return generateTaskHowItWorks(params);
   case 'apply_how_it_works': return applyTaskHowItWorks(params);
+  case 'claim': return claimTask(params, false);
+  case 'release': return claimTask(params, true);
+  case 'list_suggested_edits': return suggestedEdits(params, false);
+  case 'answer_suggested_edit': return suggestedEdits(params, true);
   default: throw new Error(`Unknown action: ${action}`);
   }
 }
 
+/**
+ * Claim a task, or give it back (E-259 #2747). The server decides who may and
+ * words the answer; a task someone else holds comes back as an error naming
+ * them, which is the agent's cue to pick other work rather than retry.
+ */
+async function claimTask({ taskId, claimNote }, release) {
+  if (!taskId) throw new Error(`taskId is required to ${release ? 'release' : 'claim'} a task`);
+  return callZephlyAPI('mcpClaimTask', release ? { taskId, release: true } : { taskId, note: claimNote });
+}
+
+/**
+ * Suggested edits on a claimed task (E-259 #2809): list what is waiting, or
+ * answer one. The server decides who may accept, reject or withdraw.
+ */
+async function suggestedEdits({ taskId, editId, answer, note }, answering) {
+  if (!taskId) throw new Error('taskId is required');
+  if (!answering) return callZephlyAPI('mcpTaskSuggestedEdits', { taskId });
+  if (!editId || !answer) throw new Error('editId and answer (accept, reject or withdraw) are required');
+  return callZephlyAPI('mcpTaskSuggestedEdits', { taskId, editId, answer, note });
+}
+
 /**
  * Bridge user terminology ("dashboard") to code locations by searching the
  * manifest for the task's own words. Best-effort: returns null when there is

package/lib/create-server.js

@@ -20,6 +20,7 @@ import { listPrompts, getPromptContent } from '../prompts/index.js';
 import { MCP_VERSION } from './version.js';
 import { getLogger } from './logger.js';
 import { isRemoteSafe } from './remote-tools.js';
+import { annotate } from './tool-annotations.js';
 import {
   EMAIL_ALREADY_REGISTERED,
   NOT_AUTHENTICATED,
@@ -84,7 +85,7 @@ export function createServer({ surface = 'local', startSignIn = defaultStartSign
   // cannot disagree. They must agree: filtering only tools/list would leave
   // every excluded handler dispatchable by a client that guesses the name,
   // which is the failure this whole module exists to prevent.
-  const tools = surface === 'remote' ? TOOLS.filter((tool) => isRemoteSafe(tool.name)) : TOOLS;
+  const tools = (surface === 'remote' ? TOOLS.filter((tool) => isRemoteSafe(tool.name)) : TOOLS).map(annotate);
   const available = new Set(tools.map((tool) => tool.name));
 
   const server = new Server(

package/lib/tool-annotations.js

@@ -0,0 +1,104 @@
+/**
+ * MCP tool annotations: which tools only read (#2808).
+ *
+ * Without annotations a client must assume any tool may write or destroy data,
+ * which is what the MCP spec says an unannotated tool means. Claude uses the
+ * hint to sort a connector's tools into read-only and write/delete categories,
+ * so a policy that allows only read-only tools (Claude Team/Enterprise tool
+ * permissions) blocked EVERY tool here, reads included, while
+ * every tool was unannotated.
+ *
+ * A hint, not a control: the API enforces scopes and permissions whatever a
+ * client believes. So the list errs toward leaving a tool OUT. A write wrongly
+ * marked read-only would let it through a read-only policy, while a read left
+ * unmarked only costs the user an approval prompt.
+ *
+ * Membership was verified by tracing each handler to the endpoints it calls
+ * (config/endpoint-map.js): all GETs, or POSTs to query routes the API mounts
+ * behind OptionalReadScopeMiddleware (projects/story, organization/analyze,
+ * graph/*, tags/suggest, links/preview, attachments/download-url). Some have
+ * local side effects that change no EzModo data, and those count as reads:
+ * get_document caches the content into .ezmodo/docs, get_current_project_context
+ * and list_tags cache tags, and detect_git_repository and list_project_worktrees
+ * run read-only git commands.
+ *
+ * Adding a tool? If it only reads, add it here.
+ * __tests__/tool-annotations.test.js fails when a get_/list_/search_ tool is
+ * left unclassified, so a new read cannot silently default to "may write".
+ */
+
+export const READ_ONLY_TOOLS = new Set([
+  'detect_git_repository',
+  'estimate_task',
+  'evaluate_feature_flag',
+  'get_access',
+  'get_ai_insights',
+  'get_attachment_url',
+  'get_catalog',
+  'get_catalog_diff',
+  'get_context',
+  'get_current_project_context',
+  'get_decision',
+  'get_design',
+  'get_design_system',
+  'get_document',
+  'get_document_template',
+  'get_epic',
+  'get_epic_activity',
+  'get_epic_plan',
+  'get_feature',
+  'get_feature_flag',
+  'get_goal',
+  'get_graph',
+  'get_manifest_schema',
+  'get_milestone',
+  'get_org_areas',
+  'get_organization',
+  'get_project',
+  'get_project_changes',
+  'get_project_story',
+  'get_task',
+  'get_testing_summary',
+  'infer_dependencies',
+  'list_agent_suggestions',
+  'list_attachments',
+  'list_catalog_items',
+  'list_catalogs',
+  'list_designs',
+  'list_epic_comments',
+  'list_epics',
+  'list_facts',
+  'list_feature_flags',
+  'list_folders',
+  'list_links',
+  'list_notifications',
+  'list_org_documents',
+  'list_project_worktrees',
+  'list_repositories',
+  'list_tags',
+  'list_test_cases',
+  'list_test_suites',
+  'list_todos',
+  'list_unmapped_paths',
+  'list_watched',
+  'preview_links',
+  'resolve_concepts',
+  'search_epics',
+  'search_features',
+  'search_tasks',
+  'validate_manifest',
+]);
+
+/**
+ * The tool definition as a client should see it: read-only tools carry
+ * `annotations.readOnlyHint: true`; everything else is returned unchanged.
+ * Never mutates the shared definition in tools/.
+ *
+ * @template {{ name: string, annotations?: object }} T
+ * @param {T} tool
+ * @returns {T}
+ */
+export function annotate(tool) {
+  if (!READ_ONLY_TOOLS.has(tool.name)) return tool;
+  return { ...tool, annotations: { ...tool.annotations, readOnlyHint: true } };
+}

package/lib/version.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ezmodo/mcp-server",
-  "version": "0.19.1",
+  "version": "0.20.0",
   "description": "MCP server for ezmodo - AI-first project management",
   "main": "index.js",
   "type": "module",

package/tools/epics.js

@@ -56,8 +56,12 @@ export const EPIC_TOOLS = [
       properties: {
         action: {
           type: 'string',
-          enum: ['create', 'update', 'generate_how_it_works', 'apply_how_it_works'],
-          description: 'Action to perform. "generate_how_it_works" (re)generates the epic\'s grounded, ' +
+          enum: ['create', 'update', 'generate_how_it_works', 'apply_how_it_works', 'add_editor', 'remove_editor'],
+          description: 'Action to perform. "add_editor" / "remove_editor" (epicId + editorUserId) choose who ' +
+            'else may change the epic\'s plan, decide its questions and answer suggested changes (E-259). ' +
+            'Only the owner, the creator or an org admin may choose; an editor may remove themselves. ' +
+            'get_epic lists the current editors. ' +
+            '"generate_how_it_works" (re)generates the epic\'s grounded, ' +
             'source-attributed "how it works" living description from its reality — its tasks\' status ' +
             'rollup, their captured decisions and their linked commits (requires epicId; AI-quota gated). ' +
             'An epic is where intent and reality drift furthest apart: intent is a charter written once, ' +
@@ -68,7 +72,12 @@ export const EPIC_TOOLS = [
         // --- Identifiers ---
         epicId: {
           type: 'string',
-          description: 'Epic ID (required for update, generate_how_it_works, apply_how_it_works)',
+          description: 'Epic ID (required for update, generate_how_it_works, apply_how_it_works, ' +
+            'add_editor, remove_editor)',
+        },
+        editorUserId: {
+          type: 'string',
+          description: 'add_editor / remove_editor: the user to add or remove (must be in the organization)',
         },
         markdown: {
           type: 'string',
@@ -255,7 +264,8 @@ export const EPIC_TOOLS = [
       'Responses include `descriptionDocumentId` — the id of the backing rich-description Document ' +
       'when the description has been promoted to one (E-189), otherwise omitted. ' +
       'Responses also include `derivedGoalIds` — the organization goal(s) this epic aligns to, ' +
-      'derived via its milestone (epics have no direct goal field).',
+      'derived via its milestone (epics have no direct goal field). ' +
+      '`editors` lists the people besides the owner who may change its plan (E-259).',
     inputSchema: {
       type: 'object',
       properties: {
@@ -390,12 +400,18 @@ export const EPIC_TOOLS = [
     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 ' +
+      'their view, open questions put to them and open objections, 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.',
+      'look without that.\n\n' +
+      'LIVE: pass waitSeconds (up to 25) to wait for something to happen instead of hearing ' +
+      '"nothing has changed" — the call returns as soon as someone changes the plan, comments, ' +
+      'decides, or picks up or moves a task. Call it again to keep following a shared session. ' +
+      '`hereNow` says who else is on the epic right now, people and their AIs; calling any epic tool ' +
+      'shows you there too.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -409,6 +425,10 @@ export const EPIC_TOOLS = [
           type: 'boolean',
           description: 'Mark the epic as caught up after answering (default true)',
         },
+        waitSeconds: {
+          type: 'number',
+          description: 'Wait up to this many seconds (max 25) for something new before answering',
+        },
       },
       required: ['epicId'],
     },
@@ -417,12 +437,15 @@ export const EPIC_TOOLS = [
     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.',
+      'Read this before planning or changing a shared epic: other people\'s questions and objections live here. ' +
+      'Each comment has a `kind` (comment, question, objection, alternative); the last three stay open until ' +
+      '`resolvedAt` is set. Pass open:true for only the ones still waiting — check it before approving a plan.',
     inputSchema: {
       type: 'object',
       properties: {
         epicId: { type: 'string', description: 'The epic ID (required)' },
         limit: { type: 'number', description: 'Maximum comments to return (default 100, max 500)' },
+        open: { type: 'boolean', description: 'Only the questions, objections and alternatives not yet settled' },
       },
       required: ['epicId'],
     },
@@ -432,7 +455,11 @@ export const EPIC_TOOLS = [
     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.',
+      'and posting makes that person follow it. Write plainly: one point per comment, readable by anyone.\n\n' +
+      'Say what the comment is with `kind`: a `question` you need answered, an `objection` to the plan, or ' +
+      'an `alternative` approach. Those stay open until settled, show up in catch me up, and an open objection ' +
+      'warns whoever approves the plan. To answer one, reply with parentId and resolvesParent:true ' +
+      '(the person who raised it, or the epic\'s owner, may settle it; anyone may reply).',
     inputSchema: {
       type: 'object',
       properties: {
@@ -440,6 +467,15 @@ export const EPIC_TOOLS = [
         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' },
+        kind: {
+          type: 'string',
+          enum: ['comment', 'question', 'objection', 'alternative'],
+          description: 'What this is (default comment). Replies are always comments.',
+        },
+        resolvesParent: {
+          type: 'boolean',
+          description: 'With parentId: this reply settles the question, objection or alternative it answers',
+        },
       },
       required: ['epicId', 'content'],
     },
@@ -453,7 +489,7 @@ export const EPIC_TOOLS = [
       '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. ' +
+      'review (owner, editors, 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.',

package/tools/tasks.js

@@ -32,14 +32,51 @@ export const TASK_TOOLS = [
       properties: {
         action: {
           type: 'string',
-          enum: ['create', 'update', 'complete', 'defer', 'link_commit', 'unlink_commit', 'get_commits', 'generate_how_it_works', 'apply_how_it_works'],
-          description: 'Action to perform. "generate_how_it_works" (re)generates the task\'s ' +
+          enum: [
+            'create', 'update', 'complete', 'defer', 'link_commit', 'unlink_commit', 'get_commits',
+            'generate_how_it_works', 'apply_how_it_works', 'claim', 'release',
+            'list_suggested_edits', 'answer_suggested_edit',
+          ],
+          description: 'Action to perform. "claim" (taskId, optional claimNote) says you are working on ' +
+            'this task, so other people\'s AIs on the same epic pick different work (E-259). Claim ' +
+            'BEFORE starting a task on a shared epic. It lasts 2 hours and renews while you update ' +
+            'the task or link commits; claiming again renews it. If someone else holds it you are ' +
+            'told who and which branch their work is on — pick another task. The answer warns about ' +
+            'other in-progress tasks on the epic that touch the same files, with the branch each is on, ' +
+            'so you can build on that work or keep clear of it. "release" gives it back when you stop. ' +
+            'TASK RULES: on a task someone ELSE has claimed, changing its title, description, steps or ' +
+            'epic, or deleting it, is sent to them as a suggested edit (the response says ' +
+            '`suggested: true`; anything else in the same update still applies), and changing its ' +
+            'status, assignee or step progress is refused — leave a comment instead. The claimer and ' +
+            'whoever runs the epic are not limited. "list_suggested_edits" (taskId) shows what is ' +
+            'waiting on a task; "answer_suggested_edit" (taskId, editId, answer: accept|reject|withdraw, ' +
+            'optional note) answers one — the claimer or whoever runs the epic accepts or rejects, the ' +
+            'author withdraws. ' +
+            '"generate_how_it_works" (re)generates the task\'s ' +
             'grounded, source-attributed "how it works" living description from its reality — ' +
             'subtasks, comments, status history, commits plus a manifest pass over linked files ' +
             '(requires taskId; AI-quota gated). "apply_how_it_works" (BYO-AI) persists a summary ' +
             'YOU authored: pass markdown + sources; the server validates your cited sources against ' +
             'the real grounded context (dropping fabricated ones) before saving — no server model call.',
         },
+        editId: {
+          type: 'string',
+          description: 'answer_suggested_edit: the suggested edit to answer',
+        },
+        answer: {
+          type: 'string',
+          enum: ['accept', 'reject', 'withdraw'],
+          description: 'answer_suggested_edit: accept or reject it (the claimer or whoever runs the epic), ' +
+            'or withdraw your own',
+        },
+        note: {
+          type: 'string',
+          description: 'answer_suggested_edit: what you want to say back, optional',
+        },
+        claimNote: {
+          type: 'string',
+          description: 'claim: what you are about to do, in a few words (shown to the others)',
+        },
         // --- Identifiers (used by most actions) ---
         taskId: {
           type: 'string',