@ezmodo/mcp-server 0.13.0

package/handlers/activity.js

@@ -0,0 +1,112 @@
+/**
+ * Activity Timeline Handler
+ * Handles get_project_changes MCP tool calls
+ */
+
+import { callZephlyAPI } from '../lib/http-client.js';
+
+/**
+ * Parse a relative duration string (e.g., "7d", "2w") into an ISO date string.
+ * Returns the input unchanged if it's already an ISO date.
+ */
+function parseSinceParam(since) {
+  if (!since) {
+    // Default: 7 days ago
+    const d = new Date();
+    d.setDate(d.getDate() - 7);
+    return d.toISOString();
+  }
+
+  // Check for relative duration: Nd, Nw, Nm
+  const match = since.match(/^(\d+)([dwm])$/);
+  if (match) {
+    const n = parseInt(match[1], 10);
+    const unit = match[2];
+    const d = new Date();
+    if (unit === 'd') d.setDate(d.getDate() - n);
+    else if (unit === 'w') d.setDate(d.getDate() - n * 7);
+    else if (unit === 'm') d.setMonth(d.getMonth() - n);
+    return d.toISOString();
+  }
+
+  // Assume ISO date
+  return since;
+}
+
+/**
+ * Format an event into a human-readable description for AI agents.
+ */
+function formatEventDescription(event) {
+  const actor = event.actor?.name || 'Someone';
+  const title = event.entityTitle || event.entityId;
+  const taskNum = event.metadata?.taskNumber ? `#${event.metadata.taskNumber}` : '';
+  const epicNum = event.metadata?.epicNumber ? `E-${event.metadata.epicNumber}` : '';
+  const entityLabel = taskNum || epicNum || '';
+  const titleWithNum = entityLabel ? `${entityLabel} '${title}'` : `'${title}'`;
+
+  switch (event.eventType) {
+  case 'task_created': return `${actor} created task ${titleWithNum}`;
+  case 'task_completed': return `${actor} completed task ${titleWithNum}`;
+  case 'task_status_changed': {
+    const newStatus = event.metadata?.newStatus || '';
+    return `${actor} moved task ${titleWithNum} to ${newStatus}`;
+  }
+  case 'task_assigned': return `${actor} assigned task ${titleWithNum}`;
+  case 'task_updated': return `${actor} updated task ${titleWithNum}`;
+  case 'task_deleted': return `${actor} deleted task ${titleWithNum}`;
+  case 'task_comment_added': return `${actor} commented on task ${titleWithNum}`;
+  case 'task_priority_changed': return `${actor} changed priority on task ${titleWithNum}`;
+  case 'epic_created': return `${actor} created epic ${titleWithNum}`;
+  case 'epic_completed': return `${actor} completed epic ${titleWithNum}`;
+  case 'epic_status_changed': {
+    const newStatus = event.metadata?.newStatus || '';
+    return `${actor} moved epic ${titleWithNum} to ${newStatus}`;
+  }
+  case 'epic_progress_changed': return `Progress changed on epic ${titleWithNum}`;
+  case 'goal_created': return `${actor} created goal '${title}'`;
+  case 'goal_completed': return `${actor} completed goal '${title}'`;
+  case 'milestone_created': return `${actor} created milestone '${title}'`;
+  case 'milestone_completed': return `${actor} completed milestone '${title}'`;
+  case 'milestone_status_changed': {
+    const newStatus = event.metadata?.newStatus || '';
+    return `${actor} moved milestone '${title}' to ${newStatus}`;
+  }
+  case 'milestone_updated': return `${actor} updated milestone '${title}'`;
+  case 'milestone_deleted': return `${actor} deleted milestone '${title}'`;
+  case 'document_created': return `${actor} created document '${title}'`;
+  case 'document_updated': return `${actor} updated document '${title}'`;
+  default: return event.description || `${actor} performed ${event.eventType} on ${event.entityType} '${title}'`;
+  }
+}
+
+export async function getProjectChanges(args) {
+  const { projectId, since, entityTypes, eventTypes, limit } = args;
+
+  if (!projectId) {
+    throw new Error('projectId is required');
+  }
+
+  const params = {
+    projectId,
+    since: parseSinceParam(since),
+    limit: Math.min(limit || 20, 100),
+    includeSummary: true,
+  };
+
+  if (entityTypes) params.entityType = entityTypes;
+  if (eventTypes) params.eventType = eventTypes;
+
+  const result = await callZephlyAPI('mcpGetProjectChanges', params);
+
+  // Enrich events with human-readable descriptions
+  const events = (result.events || []).map(event => ({
+    ...event,
+    humanDescription: formatEventDescription(event),
+  }));
+
+  return {
+    summary: result.summary || null,
+    totalCount: result.totalCount || 0,
+    events,
+  };
+}

package/handlers/agents.js

@@ -0,0 +1,95 @@
+/**
+ * Background Agents Handlers (E-150)
+ *
+ * Thin wrappers over /api/mcp/v1/agent-* — all real logic lives in
+ * api/internal/core/agents. These tools let an MCP client review and act on
+ * what the background agents staged in agent_suggestions.
+ */
+
+import { callZephlyAPI } from '../lib/http-client.js';
+
+export async function listAgentSuggestions({
+  limit, entityType, entityId, action, agentType, minConfidence,
+} = {}) {
+  const params = {};
+  if (limit !== undefined) params.limit = limit;
+  if (entityType) params.entityType = entityType;
+  if (entityId) params.entityId = entityId;
+  if (action) params.action = action;
+  if (agentType) params.agentType = agentType;
+  if (minConfidence !== undefined) params.minConfidence = minConfidence;
+  return callZephlyAPI('mcpListAgentSuggestions', params);
+}
+
+/**
+ * Accept and/or reject a batch of suggestions in one tool call.
+ *
+ * The API has no bulk endpoint, so this fans out sequentially — but from the
+ * agent's side it is ONE call, which is the point. Clearing a queue item by
+ * item costs a round trip each, and anything that expensive gets skipped;
+ * suggestions then pile up until someone bulk-dismisses them unread.
+ *
+ * Sequential rather than parallel on purpose: accepting runs a real side effect
+ * (inserting the link), and the dedup/quota bookkeeping behind it is easier to
+ * reason about serialized. These batches are small — a handful per task.
+ *
+ * A failure is recorded against its id and the batch continues. One bad id must
+ * not cost the rest.
+ */
+export async function resolveLinkSuggestions({ accept = [], reject = [], reviewNote } = {}) {
+  const accepted = [];
+  const rejected = [];
+  const failed = [];
+
+  for (const id of accept) {
+    if (!id) continue;
+    try {
+      await acceptAgentSuggestion({ id, reviewNote });
+      accepted.push(id);
+    } catch (err) {
+      failed.push({ id, action: 'accept', error: err?.message || String(err) });
+    }
+  }
+
+  for (const item of reject) {
+    const id = typeof item === 'string' ? item : item?.id;
+    if (!id) continue;
+    try {
+      await rejectAgentSuggestion({ id, reviewNote: (typeof item === 'object' && item.reason) || reviewNote });
+      rejected.push(id);
+    } catch (err) {
+      failed.push({ id, action: 'reject', error: err?.message || String(err) });
+    }
+  }
+
+  return { accepted, rejected, failed, resolved: accepted.length + rejected.length };
+}
+
+export async function acceptAgentSuggestion({ id, reviewNote } = {}) {
+  if (!id) throw new Error('accept_agent_suggestion: id is required');
+  const body = { id };
+  if (reviewNote) body.reviewNote = reviewNote;
+  return callZephlyAPI('mcpAcceptAgentSuggestion', body);
+}
+
+export async function rejectAgentSuggestion({ id, reviewNote } = {}) {
+  if (!id) throw new Error('reject_agent_suggestion: id is required');
+  const body = { id };
+  if (reviewNote) body.reviewNote = reviewNote;
+  return callZephlyAPI('mcpRejectAgentSuggestion', body);
+}
+
+export async function runAgentNow({ agentType, scope } = {}) {
+  if (!agentType) throw new Error('run_agent_now: agentType is required');
+  const body = { agentType };
+  if (scope) body.scope = scope;
+  return callZephlyAPI('mcpRunAgentNow', body);
+}
+
+export async function configureAgent({ agentType, enabled, cadenceSeconds } = {}) {
+  if (!agentType) throw new Error('configure_agent: agentType is required');
+  const body = { agentType };
+  if (enabled !== undefined) body.enabled = enabled;
+  if (cadenceSeconds !== undefined) body.cadenceSeconds = cadenceSeconds;
+  return callZephlyAPI('mcpConfigureAgent', body);
+}

package/handlers/ai-intelligence.js

@@ -0,0 +1,55 @@
+/**
+ * AI Intelligence Handlers
+ * Handler functions for project insights and intelligent analysis
+ *
+ * Consolidated: getAiInsights dispatches by type param.
+ */
+
+import { callZephlyAPI } from '../lib/http-client.js';
+
+/**
+ * Dispatch get_ai_insights by type to the appropriate handler
+ */
+export async function getAiInsights(args) {
+  const { type, ...params } = args;
+  switch (type) {
+  case 'project_insights': return getProjectInsights(params);
+  case 'suggest_next': return suggestNextActions(params);
+  case 'dependency_graph': return analyzeDependencyGraph(params);
+  case 'build_failure': return analyzeBuildFailure(params);
+  case 'deployment_risk': return predictDeploymentRisk(params);
+  default: throw new Error(`Unknown insight type: ${type}`);
+  }
+}
+
+// --- Private helpers ---
+
+async function getProjectInsights(args) {
+  return callZephlyAPI('mcpGetProjectInsights', args);
+}
+
+async function suggestNextActions(args) {
+  return callZephlyAPI('mcpSuggestNextActions', args);
+}
+
+async function analyzeDependencyGraph(args) {
+  return callZephlyAPI('mcpAnalyzeDependencyGraph', args);
+}
+
+async function analyzeBuildFailure(args) {
+  return callZephlyAPI('mcpAnalyzeBuildFailure', args);
+}
+
+async function predictDeploymentRisk(args) {
+  return callZephlyAPI('mcpPredictDeploymentRisk', args);
+}
+
+export async function estimateTask(args) {
+  const { taskId } = args;
+  return callZephlyAPI('mcpEstimateTask', { taskId });
+}
+
+export async function inferDependencies(args) {
+  const { projectId } = args;
+  return callZephlyAPI('mcpGetInferredDependencies', { projectId });
+}

package/handlers/attachments.js

@@ -0,0 +1,30 @@
+/**
+ * Attachment Handlers (E-21 #158)
+ * Handler functions for attachment-related MCP tools. Read/manage only —
+ * uploads go through the app's two-phase signed-URL flow, not MCP.
+ */
+
+import { callZephlyAPI } from '../lib/http-client.js';
+
+/**
+ * List attachments for a single entity (entityType + entityId) or the
+ * project-wide aggregate (projectId). Validation of the mutually-exclusive
+ * modes is enforced server-side.
+ */
+export async function listAttachments(args) {
+  return callZephlyAPI('mcpListAttachments', args);
+}
+
+/**
+ * Get a signed download/preview URL for an attachment.
+ */
+export async function getAttachmentUrl(args) {
+  return callZephlyAPI('mcpGetAttachmentUrl', args);
+}
+
+/**
+ * Delete an attachment (also removes the stored file and releases usage).
+ */
+export async function deleteAttachment(args) {
+  return callZephlyAPI('mcpDeleteAttachment', args);
+}

package/handlers/catalogs.js

@@ -0,0 +1,169 @@
+/**
+ * Catalog Handlers (E-215)
+ * Handler functions for the catalog MCP tools. These are thin wrappers over
+ * /api/mcp/v1/catalogs; validation, checksum-gating, and version bumping all
+ * happen server-side in core/catalogs.Service.
+ *
+ * A Catalog is a generalized, code-derived catalog; its versions are immutable
+ * { columns, items } snapshots. Agents read the current snapshot (get_catalog)
+ * to understand a catalog and push new snapshots after changing its source of
+ * truth in code (capture-at-build).
+ */
+
+import { callZephlyAPI } from '../lib/http-client.js';
+
+/**
+ * Dispatch manage_catalog actions.
+ */
+export async function manageCatalog(args) {
+  const { action, ...params } = args;
+  switch (action) {
+  case 'create': return createCatalog(params);
+  case 'update': return updateCatalog(params);
+  case 'delete': return deleteCatalog(params);
+  case 'link': return params.itemKey ? linkCatalogItem(params) : linkCatalogArtifact(params);
+  case 'unlink': return params.itemKey ? unlinkCatalogItem(params) : unlinkCatalogArtifact(params);
+  case 'snapshot': return snapshotCatalog(params);
+  default:
+    throw new Error(`Unknown action: ${action}. Expected create, update, delete, link, unlink, or snapshot.`);
+  }
+}
+
+/**
+ * Retrieve a single catalog and, by default, its current snapshot.
+ * - version → that specific version's full snapshot (result.version)
+ * - else (unless metadataOnly) → the current version's full snapshot (result.currentVersion)
+ * - includeVersions → version metadata history (result.versions)
+ *
+ * The current-version fetch is best-effort: a freshly created catalog has no
+ * snapshot yet, so a 404 there leaves currentVersion null instead of failing.
+ */
+export async function getCatalog(args) {
+  const { catalogId, version, includeVersions, versionsLimit, metadataOnly } = args;
+  if (!catalogId) {
+    throw new Error('catalogId is required');
+  }
+
+  const result = await callZephlyAPI('mcpGetCatalog', { catalogId });
+
+  if (version != null) {
+    result.version = await callZephlyAPI('mcpGetCatalogVersion', { catalogId, version });
+  } else if (!metadataOnly) {
+    try {
+      result.currentVersion = await callZephlyAPI('mcpGetCurrentCatalog', { catalogId });
+    } catch {
+      // No snapshot taken yet — leave the live catalog empty rather than erroring.
+      result.currentVersion = null;
+    }
+  }
+
+  if (includeVersions) {
+    const params = { catalogId };
+    if (versionsLimit != null) params.limit = versionsLimit;
+    const versions = await callZephlyAPI('mcpListCatalogVersions', params);
+    result.versions = versions?.versions ?? versions;
+  }
+
+  return result;
+}
+
+/**
+ * List catalogs for an organization, optionally filtered by project/kind, or the
+ * catalogs linked to a given entity (linkedType + linkedId).
+ */
+export async function listCatalogs(args) {
+  const params = {};
+  if (args.organizationId) params.organizationId = args.organizationId;
+  if (args.projectId) params.projectId = args.projectId;
+  if (args.kind) params.kind = args.kind;
+  if (args.linkedType) params.linkedType = args.linkedType;
+  if (args.linkedId) params.linkedId = args.linkedId;
+  if (args.limit != null) params.limit = args.limit;
+  return callZephlyAPI('mcpListCatalogs', params);
+}
+
+/**
+ * Diff two versions of a catalog (added/removed items + per-item changes).
+ */
+export async function getCatalogDiff(args) {
+  const { catalogId, from, to } = args;
+  return callZephlyAPI('mcpDiffCatalog', { catalogId, from, to });
+}
+
+/**
+ * List a catalog's entries that carry item-level links (E-218), each with its
+ * work links and external URLs attached (compact).
+ */
+export async function listCatalogItems(args) {
+  const { catalogId } = args;
+  if (!catalogId) {
+    throw new Error('catalogId is required');
+  }
+  return callZephlyAPI('mcpListCatalogItems', { catalogId });
+}
+
+// --- Private helpers ---
+
+async function createCatalog(args) {
+  return callZephlyAPI('mcpCreateCatalog', args);
+}
+
+async function updateCatalog(args) {
+  return callZephlyAPI('mcpUpdateCatalog', args);
+}
+
+async function deleteCatalog({ catalogId }) {
+  return callZephlyAPI('mcpDeleteCatalog', { catalogId });
+}
+
+async function linkCatalogArtifact({ catalogId, targetType, targetId }) {
+  return callZephlyAPI('mcpLinkCatalog', { catalogId, targetType, targetId });
+}
+
+async function unlinkCatalogArtifact({ catalogId, targetType, targetId }) {
+  return callZephlyAPI('mcpUnlinkCatalog', { catalogId, targetType, targetId });
+}
+
+// Item-level links (E-218): itemKey targets a single entry. With a url it's an
+// external-URL link; otherwise it's an internal work link (targetType/targetId).
+async function linkCatalogItem({ catalogId, itemKey, targetType, targetId, url, label }) {
+  const params = { catalogId, itemKey };
+  if (url) {
+    params.url = url;
+    if (label) params.label = label;
+  } else {
+    params.targetType = targetType;
+    params.targetId = targetId;
+  }
+  return callZephlyAPI('mcpLinkCatalogItem', params);
+}
+
+async function unlinkCatalogItem({ catalogId, itemKey, targetType, targetId, url }) {
+  const params = { catalogId, itemKey };
+  if (url) {
+    params.url = url;
+  } else {
+    params.targetType = targetType;
+    params.targetId = targetId;
+  }
+  return callZephlyAPI('mcpUnlinkCatalogItem', params);
+}
+
+/**
+ * Push a new version of a catalog's contents.
+ *
+ * Two modes (E-226). Replace (the default) sends the whole { columns, items }.
+ * Patch sends only upsertItems/removeKeys and the server merges them onto the
+ * current version — the cheap path for incremental capture, since a full
+ * snapshot has to be generated token by token. `snapshot` is still forwarded in
+ * patch mode because its columns/meta are honoured there.
+ */
+async function snapshotCatalog({ catalogId, mode, snapshot, upsertItems, removeKeys, source }) {
+  const params = { catalogId };
+  if (mode) params.mode = mode;
+  if (snapshot) params.snapshot = snapshot;
+  if (upsertItems) params.upsertItems = upsertItems;
+  if (removeKeys) params.removeKeys = removeKeys;
+  if (source) params.source = source;
+  return callZephlyAPI('mcpSnapshotCatalog', params);
+}