@ezmodo/mcp-server 0.13.0

package/handlers/todos.js

@@ -0,0 +1,43 @@
+/**
+ * Todo Handlers
+ * Handler functions for personal todo MCP tools
+ *
+ * Consolidated: manageTodo dispatches create/complete/move_to_project.
+ * listTodos is unchanged.
+ *
+ * Todos are lightweight personal tasks in the user's todo list.
+ * They can be promoted to project tasks via move_to_project.
+ */
+
+import { callZephlyAPI } from '../lib/http-client.js';
+
+/**
+ * Dispatch manage_todo actions to the appropriate handler
+ */
+export async function manageTodo(args) {
+  const { action, ...params } = args;
+  switch (action) {
+  case 'create': return createTodo(params);
+  case 'complete': return completeTodo(params);
+  case 'move_to_project': return moveTodoToProject(params);
+  default: throw new Error(`Unknown action: ${action}`);
+  }
+}
+
+export async function listTodos(args) {
+  return callZephlyAPI('mcpListTodos', args || {});
+}
+
+// --- Private helpers ---
+
+async function createTodo(args) {
+  return callZephlyAPI('mcpCreateTodo', args);
+}
+
+async function completeTodo(args) {
+  return callZephlyAPI('mcpCompleteTodo', args);
+}
+
+async function moveTodoToProject(args) {
+  return callZephlyAPI('mcpMoveTodo', args);
+}

package/handlers/watchers.js

@@ -0,0 +1,54 @@
+/**
+ * Watching Handlers
+ * Handler functions for task subscriptions and the notification inbox (E-41)
+ */
+
+import { callZephlyAPI } from '../lib/http-client.js';
+
+/**
+ * Watch or unwatch a task.
+ */
+export async function manageWatch(args) {
+  const { action, taskId } = args;
+
+  if (action !== 'watch' && action !== 'unwatch') {
+    throw new Error(`Unknown action: ${action}. Expected "watch" or "unwatch".`);
+  }
+  if (!taskId) {
+    throw new Error('taskId is required');
+  }
+
+  return callZephlyAPI('mcpManageWatch', { action, taskId });
+}
+
+/**
+ * List the tasks the caller is watching.
+ */
+export async function listWatched(args) {
+  const { organizationId, limit, offset } = args;
+
+  if (!organizationId) {
+    throw new Error('organizationId is required');
+  }
+
+  return callZephlyAPI('mcpListWatched', {
+    organizationId,
+    ...(limit ? { limit } : {}),
+    // offset 0 is the default, so sending it would only be query-string noise.
+    ...(offset ? { offset } : {}),
+  });
+}
+
+/**
+ * List the caller's in-app notifications.
+ */
+export async function listNotifications(args = {}) {
+  const { unreadOnly, limit } = args;
+
+  return callZephlyAPI('mcpListNotifications', {
+    // Only send unreadOnly when explicitly false — the API defaults to unread,
+    // and sending the default back would just be noise in the query string.
+    ...(unreadOnly === false ? { unreadOnly: false } : {}),
+    ...(limit ? { limit } : {}),
+  });
+}

package/handlers/work-templates.js

@@ -0,0 +1,32 @@
+/**
+ * Work Template Handlers
+ * Handler for the E-211 task/epic template MCP tool.
+ *
+ * Thin wrappers over /api/mcp/v1/work-templates; validation, blueprint handling,
+ * and instantiation (task or epic+children) happen server-side in
+ * core/worktemplates.Service.
+ */
+
+import { callZephlyAPI } from '../lib/http-client.js';
+
+/**
+ * Dispatch manage_work_template actions.
+ */
+export async function manageWorkTemplate(args) {
+  const { action, ...params } = args;
+  switch (action) {
+  case 'create': return callZephlyAPI('mcpCreateWorkTemplate', params);
+  case 'update': return callZephlyAPI('mcpUpdateWorkTemplate', params);
+  case 'delete': return callZephlyAPI('mcpDeleteWorkTemplate', { templateId: params.templateId });
+  case 'get': return callZephlyAPI('mcpGetWorkTemplate', { templateId: params.templateId });
+  case 'instantiate': return callZephlyAPI('mcpInstantiateWorkTemplate', params);
+  case 'list': {
+    const listParams = {};
+    if (params.organizationId) listParams.organizationId = params.organizationId;
+    if (params.kind) listParams.kind = params.kind;
+    return callZephlyAPI('mcpListWorkTemplates', listParams);
+  }
+  default:
+    throw new Error(`Unknown action: ${action}. Expected create, update, delete, list, get, or instantiate.`);
+  }
+}

package/index.js

@@ -0,0 +1,175 @@
+#!/usr/bin/env node
+
+/**
+ * EzModo MCP Server
+ *
+ * Provides Model Context Protocol tools for AI agents to interact with EzModo
+ * projects, tasks, and documentation via HTTP API.
+ */
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  ListPromptsRequestSchema,
+  GetPromptRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+
+// Import configuration
+import { CONFIG } from './config/index.js';
+
+// Import tool definitions and handlers
+import { TOOLS } from './tools/index.js';
+import { HANDLERS } from './handlers/index.js';
+
+// Import prompts
+import { PROMPTS, getPromptContent } from './prompts/index.js';
+
+import { MCP_VERSION } from './lib/version.js';
+import { initLogger, getLogger } from './lib/logger.js';
+import { getApiKey } from './lib/env.js';
+
+// ============================================================
+// Configuration Validation
+// ============================================================
+
+const apiKey = getApiKey();
+
+// Initialize logger early (before any logging)
+initLogger();
+const log = getLogger();
+
+if (!apiKey) {
+  log.error('Missing required environment variable: EZMODO_API_KEY', {
+    settingsUrl: CONFIG.settingsUrl,
+  });
+  console.error('ERROR: Missing required environment variable:');
+  console.error('- EZMODO_API_KEY (or legacy ZEPHLY_API_KEY)');
+  console.error('\nPlease set your ezmodo API key to use this MCP server.');
+  console.error(`Generate one at: ${CONFIG.settingsUrl}`);
+  console.error('\nOptional environment variables:');
+  console.error('- EZMODO_API_URL (default: production Go API URL)');
+  console.error('- EZMODO_ENVIRONMENT (dev/staging/production)');
+  console.error('\nEnvironment-specific URLs:');
+  console.error('  - dev: https://dev.ezmodo.com/api');
+  console.error('  - staging: https://staging.ezmodo.com/api');
+  console.error('  - production: https://ezmodo.com/api');
+  console.error('  - local: http://localhost:8787/api');
+  process.exit(1);
+}
+
+log.info('MCP server starting', {
+  environment: CONFIG.environment,
+  apiUrl: CONFIG.apiUrl,
+  apiKeyPrefix: apiKey.substring(0, 12),
+});
+console.error('🔧 ezmodo MCP Server Configuration:');
+console.error(`   Environment: ${CONFIG.environment} (build-time)`);
+console.error(`   API URL: ${CONFIG.apiUrl}`);
+console.error(`   API Key: ${apiKey.substring(0, 12)}...`);
+console.error('');
+
+// ============================================================
+// MCP Server Setup
+// ============================================================
+
+const server = new Server(
+  {
+    name: 'ezmodo-mcp-server',
+    version: MCP_VERSION,
+  },
+  {
+    capabilities: {
+      tools: {},
+      prompts: {},
+    },
+  }
+);
+
+// Register tool handlers
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: TOOLS,
+}));
+
+// Register tool call handler
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  // Get handler function for this tool
+  const handler = HANDLERS[name];
+
+  if (!handler) {
+    throw new Error(`Unknown tool: ${name}`);
+  }
+
+  const start = Date.now();
+  try {
+    const result = await handler(args || {});
+    log.debug('Tool call succeeded', { tool: name, durationMs: Date.now() - start });
+    return {
+      content: [
+        {
+          type: 'text',
+          text: JSON.stringify(result, null, 2),
+        },
+      ],
+    };
+  } catch (error) {
+    const errMsg = error.message || String(error);
+    log.error('Tool call failed', { tool: name, error: errMsg, durationMs: Date.now() - start });
+    return {
+      content: [
+        {
+          type: 'text',
+          text: JSON.stringify({
+            error: error.message || String(error),
+          }, null, 2),
+        },
+      ],
+      isError: true,
+    };
+  }
+});
+
+// Register prompt handlers
+server.setRequestHandler(ListPromptsRequestSchema, async () => ({
+  prompts: PROMPTS,
+}));
+
+server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+  const content = getPromptContent(request.params.name);
+
+  if (!content) {
+    throw new Error(`Unknown prompt: ${request.params.name}`);
+  }
+
+  return {
+    messages: [
+      {
+        role: 'user',
+        content: {
+          type: 'text',
+          text: content,
+        },
+      },
+    ],
+  };
+});
+
+// ============================================================
+// Start Server
+// ============================================================
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  log.info('MCP server running on stdio');
+  console.error('✅ ezmodo MCP Server running on stdio');
+}
+
+main().catch((error) => {
+  log.error('Fatal error in main()', { error: error.message || String(error) });
+  console.error('Fatal error in main():', error);
+  process.exit(1);
+});

package/lib/active-session.js

@@ -0,0 +1,86 @@
+/**
+ * Active Session File Management
+ *
+ * Writes/clears <repo-config-dir>/active-session.json to communicate the
+ * active task between Claude Code (via MCP server) and the EzModo desktop
+ * app. The session file lives inside whichever config directory the repo
+ * already uses — `.ezmodo/` for current repos, `.zephly/` for legacy.
+ */
+
+import { execSync } from 'child_process';
+import fs from 'fs/promises';
+import path from 'path';
+import { getLogger } from './logger.js';
+import { findRepoConfigDir } from './repo-config-dir.js';
+
+/**
+ * Get the current git branch name, or null if not in a git repo.
+ */
+function getCurrentBranch() {
+  try {
+    return execSync('git rev-parse --abbrev-ref HEAD', {
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Write the active-session.json file inside the project's config directory
+ * (`.ezmodo/active-session.json`, or legacy `.zephly/active-session.json` if
+ * that's what the repo already uses).
+ *
+ * @param {object} taskData
+ * @param {string} taskData.taskId
+ * @param {number} taskData.taskNumber
+ * @param {string} taskData.title
+ * @param {string} [taskData.epicId]
+ * @param {number} [taskData.epicNumber]
+ */
+export async function writeActiveSession(taskData) {
+  try {
+    const configDir = await findRepoConfigDir(process.cwd());
+    if (!configDir) {
+      getLogger().debug('No project config directory found, skipping session file write');
+      return;
+    }
+
+    const session = {
+      taskId: taskData.taskId,
+      taskNumber: taskData.taskNumber,
+      title: taskData.title,
+      ...(taskData.epicId && { epicId: taskData.epicId }),
+      ...(taskData.epicNumber && { epicNumber: taskData.epicNumber }),
+      branch: getCurrentBranch(),
+      startedAt: new Date().toISOString(),
+      agentName: 'claude',
+    };
+
+    const sessionPath = path.join(configDir, 'active-session.json');
+    await fs.writeFile(sessionPath, JSON.stringify(session, null, 2), 'utf-8');
+    getLogger().info('Wrote active session file', { taskId: taskData.taskId });
+  } catch (err) {
+    getLogger().warn('Failed to write active session file', { error: err.message });
+  }
+}
+
+/**
+ * Clear (delete) the active-session.json file inside the project's config
+ * directory when task work ends. Operates on whichever directory the repo
+ * uses (`.ezmodo/` or legacy `.zephly/`).
+ */
+export async function clearActiveSession() {
+  try {
+    const configDir = await findRepoConfigDir(process.cwd());
+    if (!configDir) return;
+
+    const sessionPath = path.join(configDir, 'active-session.json');
+    await fs.unlink(sessionPath);
+    getLogger().info('Cleared active session file');
+  } catch (err) {
+    if (err.code === 'ENOENT') return; // Already gone, that's fine
+    getLogger().warn('Failed to clear active session file', { error: err.message });
+  }
+}

package/lib/auto-assign.js

@@ -0,0 +1,93 @@
+/**
+ * Auto-assign Utility
+ * Matches task/epic content against cached tags and components
+ * for automatic assignment during creation.
+ */
+
+import { readConfig } from './local-cache.js';
+
+/**
+ * Escape special regex characters in a string.
+ */
+function escapeRegex(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Match components against text content using word boundary matching.
+ * @param {string} text - Combined title + description
+ * @param {Array} components - Array of {id, name, description}
+ * @returns {Array} Matching component objects
+ */
+export function matchComponents(text, components) {
+  if (!text || !components?.length) return [];
+  return components.filter((c) => {
+    const regex = new RegExp(`\\b${escapeRegex(c.name)}\\b`, 'i');
+    return regex.test(text);
+  });
+}
+
+/**
+ * Match tags against text content using word boundary matching.
+ * @param {string} text - Combined title + description
+ * @param {Array} tags - Array of {id, name, color, category, description}
+ * @returns {Array} Matching tag objects
+ */
+export function matchTags(text, tags) {
+  if (!text || !tags?.length) return [];
+  return tags.filter((t) => {
+    const regex = new RegExp(`\\b${escapeRegex(t.name)}\\b`, 'i');
+    return regex.test(text);
+  });
+}
+
+/**
+ * Resolve auto-assignment for a task being created.
+ * Returns { matchedTags, availableComponents, organizationId } or null if no cache available.
+ *
+ * Components are NOT auto-assigned — agents must explicitly provide componentId.
+ * This function returns available components so the handler can hint at them if needed.
+ *
+ * @param {string} projectId - The task's project ID
+ * @param {string} title - Task title
+ * @param {string} description - Task description
+ * @returns {Promise<object|null>}
+ */
+export async function resolveTaskAutoAssign(projectId, title, description) {
+  const config = await readConfig();
+  if (!config) return null;
+
+  const text = `${title || ''} ${description || ''}`.trim();
+
+  const components = config.projectId === projectId ? (config.components || []) : [];
+  const tags = config.tags || [];
+
+  return {
+    matchedTags: text ? matchTags(text, tags) : [],
+    availableComponents: components.map((c) => ({ id: c.id, name: c.name })),
+    organizationId: config.organizationId || null,
+  };
+}
+
+/**
+ * Resolve auto-assignment for an epic being created.
+ * Returns { matchedTags, organizationId } or null if no cache available.
+ *
+ * @param {string} title - Epic title
+ * @param {string} description - Epic description
+ * @returns {Promise<object|null>}
+ */
+export async function resolveEpicAutoAssign(title, description) {
+  const config = await readConfig();
+  if (!config) return null;
+
+  const text = `${title || ''} ${description || ''}`.trim();
+  if (!text) return null;
+
+  const tags = config.tags || [];
+
+  return {
+    matchedTags: matchTags(text, tags),
+    organizationId: config.organizationId || null,
+  };
+}

package/lib/autolink.js

@@ -0,0 +1,176 @@
+import { callZephlyAPI } from './http-client.js';
+
+/**
+ * Auto-linking helpers (E-225).
+ *
+ * The API resolves file paths to the components that own them and previews what
+ * the autolink engine would propose. Both are read-only, so an agent can ask
+ * "what does this touch?" before it creates or commits anything.
+ *
+ * Everything here is best-effort: a resolver that is unavailable, or an API
+ * older than E-225, must degrade to "no information" rather than failing the
+ * surrounding create/update. A missing link is recoverable; a failed task
+ * create loses the agent's work.
+ */
+
+/**
+ * Resolve repo-relative file paths to the components that own them.
+ *
+ * @param {object} params
+ * @param {string} params.projectId
+ * @param {string[]} params.paths - repo-relative paths
+ * @returns {Promise<{matches: object[], unresolved: string[]}>}
+ */
+export async function resolvePathsToComponents({ projectId, paths }) {
+  if (!projectId || !Array.isArray(paths) || paths.length === 0) {
+    return { matches: [], unresolved: [] };
+  }
+  try {
+    const result = await callZephlyAPI('mcpResolvePaths', { projectId, paths });
+    return {
+      matches: result?.matches || [],
+      unresolved: result?.unresolved || [],
+    };
+  } catch {
+    // An API predating E-225 has no such route. Report nothing rather than
+    // surfacing a 404 the agent can do nothing about.
+    return { matches: [], unresolved: paths };
+  }
+}
+
+/**
+ * Preview what the autolink engine would propose for an entity, writing
+ * nothing. This is the explicit-gate mechanism: show the proposals, let the
+ * caller confirm the ones it wants via manage_link (which records them as
+ * human-asserted).
+ *
+ * @param {object} params
+ * @param {string} params.projectId
+ * @param {string} params.subjectType - e.g. 'task'
+ * @param {string} params.subjectId
+ * @param {string[]} [params.paths]
+ * @param {string} [params.trigger]
+ * @param {string} [params.componentId]
+ * @param {string} [params.epicId]
+ * @returns {Promise<{proposals: object[]}>}
+ */
+export async function previewEntityLinks({
+  projectId,
+  subjectType,
+  subjectId,
+  paths,
+  trigger,
+  componentId,
+  epicId,
+}) {
+  if (!subjectType || !subjectId) return { proposals: [] };
+  try {
+    const result = await callZephlyAPI('mcpPreviewLinks', {
+      projectId,
+      subjectType,
+      subjectId,
+      paths,
+      trigger,
+      componentId,
+      epicId,
+    });
+    return { proposals: result?.proposals || [] };
+  } catch {
+    return { proposals: [] };
+  }
+}
+
+/**
+ * Split preview proposals into the two groups a caller cares about: what the
+ * engine would write on its own, and what it wants a human to confirm.
+ *
+ * Callers surface these differently — "already handled" vs "please look" — so
+ * doing the split once here keeps every handler from re-deriving it.
+ */
+export function partitionProposals(proposals = []) {
+  const autoLinked = [];
+  const linkSuggestions = [];
+  for (const p of proposals) {
+    (p?.autoApplies ? autoLinked : linkSuggestions).push({
+      targetType: p.targetType,
+      targetId: p.targetId,
+      linkType: p.linkType,
+      rule: p.rule,
+      confidence: p.confidence,
+      evidence: p.evidence,
+    });
+  }
+  return { autoLinked, linkSuggestions };
+}
+
+/** Key a suggestion by what it points at — the only thing a preview proposal
+ *  and its persisted row are guaranteed to agree on. */
+function targetKey(targetType, targetId) {
+  return `${targetType || ''}:${targetId || ''}`;
+}
+
+/**
+ * Read the pending link suggestions the engine actually persisted for an entity.
+ *
+ * The API returns Go-shaped rows (`ID`, `TargetEntityType`, …); normalise here so
+ * no caller has to know that. Best-effort like everything else in this module:
+ * an unavailable queue costs the ids, not the surrounding create.
+ */
+export async function fetchPendingLinkSuggestions({ subjectType, subjectId }) {
+  if (!subjectType || !subjectId) return [];
+  try {
+    const result = await callZephlyAPI('mcpListAgentSuggestions', {
+      entityType: subjectType,
+      entityId: subjectId,
+      action: 'link',
+    });
+    const rows = result?.suggestions || [];
+    return rows.map((row) => ({
+      suggestionId: row.ID ?? row.id ?? row.suggestionId,
+      targetType: row.TargetEntityType ?? row.targetEntityType ?? row.targetType,
+      targetId: row.TargetEntityID ?? row.targetEntityId ?? row.targetId,
+      linkType: row.Payload?.link_type ?? row.payload?.link_type ?? 'relates_to',
+      rule: row.Payload?.rule ?? row.payload?.rule,
+      confidence: row.Confidence ?? row.confidence,
+      evidence: row.Payload ?? row.payload,
+    })).filter((s) => s.suggestionId);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Give each suggestion the `suggestionId` that `resolve_link_suggestions` needs.
+ *
+ * Without this an agent is told to clear its suggestions and handed nothing to
+ * clear them WITH — the preview that produces them is read-only, so its
+ * proposals carry no id (#2297).
+ *
+ * The persisted queue is also the authoritative set, not the preview: the
+ * engine's semantic rules land a beat after the deterministic ones, so a
+ * preview taken at create time can legitimately show fewer. Rows the preview
+ * missed are appended rather than dropped, and `partial` warns when some
+ * proposal has no row yet — resolvable only on a later read.
+ */
+export async function attachSuggestionIds({ subjectType, subjectId, linkSuggestions = [] }) {
+  const persisted = await fetchPendingLinkSuggestions({ subjectType, subjectId });
+  if (persisted.length === 0) {
+    return { linkSuggestions, partial: linkSuggestions.length > 0 };
+  }
+
+  const byTarget = new Map(persisted.map((s) => [targetKey(s.targetType, s.targetId), s]));
+  const seen = new Set();
+  const merged = linkSuggestions.map((s) => {
+    const key = targetKey(s.targetType, s.targetId);
+    const match = byTarget.get(key);
+    if (!match) return s;
+    seen.add(key);
+    return { suggestionId: match.suggestionId, ...s };
+  });
+
+  for (const s of persisted) {
+    if (!seen.has(targetKey(s.targetType, s.targetId))) merged.push(s);
+  }
+
+  return { linkSuggestions: merged, partial: merged.some((s) => !s.suggestionId) };
+}

package/lib/changed-files.js

@@ -0,0 +1,22 @@
+/**
+ * Normalize the two ways a caller can name files it touched: the E-225
+ * `changedFiles` string array, or the pre-existing `linkedFiles` object array.
+ * Explicit input always wins over auto-resolution — the agent knows better than
+ * a similarity search what it actually edited.
+ *
+ * Lives in lib/ rather than in the task handler because the epic-with-tasks
+ * create (#2247) needs it too, and a handler importing another handler would
+ * drag the whole task-handler dependency set into every epic test.
+ */
+export function normalizeChangedFiles(changedFiles, linkedFiles) {
+  const out = [];
+  const seen = new Set();
+  for (const f of linkedFiles || []) {
+    const path = typeof f === 'string' ? f : f?.path;
+    if (path && !seen.has(path)) { seen.add(path); out.push({ path, source: f?.source || 'mcp' }); }
+  }
+  for (const path of changedFiles || []) {
+    if (path && !seen.has(path)) { seen.add(path); out.push({ path, source: 'mcp' }); }
+  }
+  return out;
+}