@ezmodo/mcp-server 0.13.0

package/handlers/github.js

@@ -0,0 +1,72 @@
+/**
+ * GitHub Handlers
+ * Handler functions for GitHub-related MCP tools
+ *
+ * Consolidated: managePullRequest dispatches create/update/merge/close/request_review.
+ */
+
+import { callZephlyAPI } from '../lib/http-client.js';
+
+/**
+ * List the git repositories linked to a project, each with the `repoId` every
+ * manage_pull_request action requires.
+ *
+ * This exists because that id was otherwise unknowable. It is
+ * `installationId:owner/repo`, and no other tool exposes an installation id:
+ * get_project returns `settings.integrations: null`, get_current_project_context
+ * has no repo fields, and GitHub will not tell an agent either — the endpoints
+ * that would (`/repos/{owner}/{repo}/installation`, `/user/installations`) need
+ * an app JWT or an app-authorized token. ezmodo holds the fact, so ezmodo has
+ * to hand it over.
+ */
+export async function listRepositories({ projectId }) {
+  return callZephlyAPI('mcpListRepositories', { projectId });
+}
+
+/**
+ * Dispatch manage_pull_request actions to the appropriate handler
+ */
+export async function managePullRequest(args) {
+  const { action, ...params } = args;
+  switch (action) {
+  case 'create': return createPullRequest(params);
+  case 'update': return updatePullRequest(params);
+  case 'merge': return mergePullRequest(params);
+  case 'close': return closePullRequest(params);
+  case 'request_review': return requestPRReview(params);
+  case 'suggest_reviewers': return suggestReviewers(params);
+  default: throw new Error(`Unknown action: ${action}`);
+  }
+}
+
+// --- Private helpers ---
+
+async function createPullRequest(args) {
+  return callZephlyAPI('mcpCreatePullRequest', args);
+}
+
+async function updatePullRequest(args) {
+  return callZephlyAPI('mcpUpdatePullRequest', args);
+}
+
+async function mergePullRequest(args) {
+  return callZephlyAPI('mcpMergePullRequest', args);
+}
+
+async function closePullRequest(args) {
+  return callZephlyAPI('mcpClosePullRequest', args);
+}
+
+async function requestPRReview(args) {
+  return callZephlyAPI('mcpRequestPRReview', args);
+}
+
+/**
+ * Ranks reviewer candidates from CODEOWNERS and file history. Suggests only —
+ * requesting the review is the separate 'request_review' action, because
+ * pinging the wrong three people is a social cost a suggestion tool has no
+ * business incurring on its own.
+ */
+async function suggestReviewers(args) {
+  return callZephlyAPI('mcpSuggestReviewers', args);
+}

package/handlers/graph.js

@@ -0,0 +1,23 @@
+/**
+ * Graph Handlers
+ *
+ * Thin wrapper over /api/mcp/v1/graph/traverse — the navigation-graph
+ * projection (E-209). The BFS walk + node hydration happen server-side in
+ * core/graph.ProjectionService; the MCP layer just forwards the request and
+ * only sends the optional bounding params when provided.
+ */
+
+import { callZephlyAPI } from '../lib/http-client.js';
+
+/**
+ * Walk the compendium navigation graph outward from a root node. projectId,
+ * rootType, and rootId are required; scope/depth/maxNodes are optional bounds
+ * (omitted params fall back to server defaults).
+ */
+export async function getGraph({ projectId, rootType, rootId, scope, depth, maxNodes }) {
+  const params = { projectId, rootType, rootId };
+  if (scope) params.scope = scope;
+  if (depth !== undefined) params.depth = depth;
+  if (maxNodes !== undefined) params.maxNodes = maxNodes;
+  return callZephlyAPI('mcpTraverseGraph', params);
+}

package/handlers/index.js

@@ -0,0 +1,205 @@
+/**
+ * Handler Functions Index
+ * Aggregates all MCP handler functions
+ *
+ * Consolidated handler set matching the ~40-tool definitions.
+ * Each manage_* handler dispatches to internal helpers based on action param.
+ */
+
+import * as organizationHandlers from './organizations.js';
+import * as projectHandlers from './projects.js';
+import * as epicHandlers from './epics.js';
+import * as componentHandlers from './components.js';
+import * as milestoneHandlers from './milestones.js';
+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 featureFlagHandlers from './feature-flags.js';
+import * as taskHandlers from './tasks.js';
+import * as documentHandlers from './documents.js';
+import * as folderHandlers from './folders.js';
+import * as attachmentHandlers from './attachments.js';
+import * as entityHandlers from './entities.js';
+import * as linkHandlers from './links.js';
+import * as accessHandlers from './access.js';
+import * as graphHandlers from './graph.js';
+import * as tagHandlers from './tags.js';
+import * as watcherHandlers from './watchers.js';
+import * as aiIntelligenceHandlers from './ai-intelligence.js';
+import * as gitContextHandlers from './git-context.js';
+import * as githubHandlers from './github.js';
+import * as todoHandlers from './todos.js';
+import * as testingHandlers from './testing.js';
+import * as contextManifestHandlers from './context-manifest.js';
+import * as activityHandlers from './activity.js';
+import * as factHandlers from './facts.js';
+import * as agentHandlers from './agents.js';
+import * as recurringTaskHandlers from './recurring-tasks.js';
+import * as workTemplateHandlers from './work-templates.js';
+import { manageWorktree, listProjectWorktrees } from '../lib/worktree-tools.js';
+
+/**
+ * Map of tool names to handler functions
+ * Used by the MCP server to route tool calls
+ */
+export const HANDLERS = {
+  // Organizations
+  get_organization: organizationHandlers.getOrganization,
+
+  // Projects
+  manage_project: projectHandlers.manageProject,
+  get_project: projectHandlers.getProject,
+  get_project_story: projectHandlers.getProjectStory,
+
+  // Epics
+  manage_epic: epicHandlers.manageEpic,
+  search_epics: epicHandlers.searchEpics,
+  list_epics: epicHandlers.listEpics,
+  get_epic: epicHandlers.getEpic,
+
+  // Components
+  manage_component: componentHandlers.manageComponent,
+  list_components: componentHandlers.listComponents,
+
+  // Milestones
+  manage_milestone: milestoneHandlers.manageMilestone,
+  get_milestone: milestoneHandlers.getMilestone,
+
+  // Features (Feature Compendium, E-162)
+  manage_feature: featureHandlers.manageFeature,
+  get_feature: featureHandlers.getFeature,
+  search_features: featureHandlers.searchFeatures,
+
+  // Decisions / ADRs (E-170)
+  manage_decision: decisionHandlers.manageDecision,
+  get_decision: decisionHandlers.getDecision,
+
+  // Recurring task schedules + work templates (E-211)
+  manage_recurring_task: recurringTaskHandlers.manageRecurringTask,
+  manage_work_template: workTemplateHandlers.manageWorkTemplate,
+
+  // Designs (living design system)
+  manage_design: designHandlers.manageDesign,
+  get_design: designHandlers.getDesign,
+  list_designs: designHandlers.listDesigns,
+  get_design_system: designHandlers.getDesignSystem,
+
+  // Catalogs (generalized code-derived catalogs, E-215)
+  manage_catalog: catalogHandlers.manageCatalog,
+  get_catalog: catalogHandlers.getCatalog,
+  list_catalogs: catalogHandlers.listCatalogs,
+  list_catalog_items: catalogHandlers.listCatalogItems,
+  get_catalog_diff: catalogHandlers.getCatalogDiff,
+
+  // Feature Flags (E-149)
+  manage_feature_flag: featureFlagHandlers.manageFeatureFlag,
+  get_feature_flag: featureFlagHandlers.getFeatureFlag,
+  list_feature_flags: featureFlagHandlers.listFeatureFlags,
+  evaluate_feature_flag: featureFlagHandlers.evaluateFeatureFlag,
+  manage_environment: featureFlagHandlers.manageEnvironment,
+
+  // Tasks
+  manage_task: taskHandlers.manageTask,
+  create_tasks: taskHandlers.bulkCreateTasks,
+  search_tasks: taskHandlers.searchTasks,
+  get_task: taskHandlers.getTask,
+  report_untracked_work: taskHandlers.reportUntrackedWork,
+
+  // Documents
+  manage_document: documentHandlers.manageDocument,
+  manage_document_template: documentHandlers.manageDocumentTemplate,
+  get_document: documentHandlers.getDocument,
+  get_document_template: documentHandlers.getDocumentTemplate,
+  list_org_documents: documentHandlers.listOrgDocuments,
+
+  // Folders
+  manage_folder: folderHandlers.manageFolder,
+  list_folders: folderHandlers.listFolders,
+  get_org_areas: folderHandlers.getOrgAreas,
+
+  // Attachments (read/manage only — E-21 #158)
+  list_attachments: attachmentHandlers.listAttachments,
+  get_attachment_url: attachmentHandlers.getAttachmentUrl,
+  delete_attachment: attachmentHandlers.deleteAttachment,
+
+  // Entities (goals, teams)
+  manage_goal: entityHandlers.manageGoal,
+  manage_team: entityHandlers.manageTeam,
+  get_goal: entityHandlers.getGoal,
+
+  // Tags
+  manage_tag: tagHandlers.manageTag,
+  list_tags: tagHandlers.listTags,
+
+  // Watching / subscriptions (E-41)
+  manage_watch: watcherHandlers.manageWatch,
+  list_watched: watcherHandlers.listWatched,
+  list_notifications: watcherHandlers.listNotifications,
+
+  // Links (polymorphic entity_links — task/epic/project/document)
+  manage_link: linkHandlers.manageLink,
+  list_links: linkHandlers.listLinks,
+  resolve_links: linkHandlers.resolveLinks,
+  preview_links: linkHandlers.previewLinks,
+
+  // Entity access control (#2170) — polymorphic over the types the access
+  // service supports. Mutations need an API key with the write:access scope.
+  get_access: accessHandlers.getAccess,
+  manage_access: accessHandlers.manageAccess,
+
+  // Navigation graph (E-209) — walk the compendium from a root node
+  get_graph: graphHandlers.getGraph,
+
+  // Background agents (E-150)
+  list_agent_suggestions: agentHandlers.listAgentSuggestions,
+  resolve_link_suggestions: agentHandlers.resolveLinkSuggestions,
+  accept_agent_suggestion: agentHandlers.acceptAgentSuggestion,
+  reject_agent_suggestion: agentHandlers.rejectAgentSuggestion,
+  run_agent_now: agentHandlers.runAgentNow,
+  configure_agent: agentHandlers.configureAgent,
+
+  // AI Intelligence
+  get_ai_insights: aiIntelligenceHandlers.getAiInsights,
+  estimate_task: aiIntelligenceHandlers.estimateTask,
+  infer_dependencies: aiIntelligenceHandlers.inferDependencies,
+
+  // Git Context
+  detect_git_repository: gitContextHandlers.detectGitRepository,
+  get_current_project_context: gitContextHandlers.getCurrentProjectContext,
+  initialize_project_context: gitContextHandlers.initializeProjectContext,
+
+  // Worktrees
+  manage_worktree: manageWorktree,
+  list_project_worktrees: listProjectWorktrees,
+
+  // GitHub
+  manage_pull_request: githubHandlers.managePullRequest,
+  list_repositories: githubHandlers.listRepositories,
+
+  // Todos
+  manage_todo: todoHandlers.manageTodo,
+  list_todos: todoHandlers.listTodos,
+
+  // Testing
+  manage_test_case: testingHandlers.manageTestCase,
+  manage_test_suite: testingHandlers.manageTestSuite,
+  list_test_cases: testingHandlers.listTestCases,
+  list_test_suites: testingHandlers.listTestSuites,
+  get_testing_summary: testingHandlers.getTestingSummary,
+
+  // Activity Timeline
+  get_project_changes: activityHandlers.getProjectChanges,
+
+  // Facts
+  manage_fact: factHandlers.manageFact,
+  list_facts: factHandlers.listFacts,
+
+  // Context Manifest
+  get_context: contextManifestHandlers.getContext,
+  rebuild_manifest: contextManifestHandlers.rebuildManifest,
+  update_manifest_entries: contextManifestHandlers.updateManifestEntriesHandler,
+  get_manifest_schema: contextManifestHandlers.getManifestSchema,
+  validate_manifest: contextManifestHandlers.validateManifest,
+  resolve_concepts: contextManifestHandlers.resolveConcepts,
+};

package/handlers/links.js

@@ -0,0 +1,156 @@
+/**
+ * Links Handlers
+ *
+ * Thin wrappers over /api/mcp/v1/links — the polymorphic entity_links
+ * surface added in Phase 3. Dispatch happens server-side in
+ * core/links.Service; the MCP layer just forwards the request.
+ */
+
+import {
+  resolvePathsToComponents,
+  previewEntityLinks,
+  partitionProposals,
+  attachSuggestionIds,
+} from '../lib/autolink.js';
+import { callZephlyAPI } from '../lib/http-client.js';
+
+/**
+ * Dispatch manage_link to add or remove a link.
+ */
+export async function manageLink(args) {
+  const { action, ...params } = args;
+  switch (action) {
+  case 'add':
+    return addLink(params);
+  case 'remove':
+    return removeLink(params);
+  case 'verify':
+    return verifyLink(params);
+  default:
+    throw new Error(`Unknown action: ${action}. Expected "add", "remove", or "verify".`);
+  }
+}
+
+async function addLink({ sourceType, sourceId, targetType, targetId, linkType }) {
+  return callZephlyAPI('mcpAddLink', {
+    sourceType,
+    sourceId,
+    targetType,
+    targetId,
+    linkType,
+  });
+}
+
+async function removeLink({ sourceType, sourceId, targetType, targetId, linkType }) {
+  return callZephlyAPI('mcpRemoveLink', {
+    sourceType,
+    sourceId,
+    targetType,
+    targetId,
+    linkType,
+  });
+}
+
+/**
+ * Stamp a link's freshness (E-166/E-154): record that you confirmed the link
+ * is still correct, optionally against the commit you verified it at. Call this
+ * after touching code that a linked document describes so the freshness signal
+ * stays accurate. commitSha is optional.
+ */
+async function verifyLink({ sourceType, sourceId, targetType, targetId, linkType, commitSha }) {
+  const params = { sourceType, sourceId, targetType, targetId, linkType };
+  if (commitSha) params.commitSha = commitSha;
+  return callZephlyAPI('mcpVerifyLink', params);
+}
+
+/**
+ * The tool speaks the agent's vocabulary (outgoing/incoming/both) because
+ * "outgoing" is unambiguous about whose perspective it is; the API's
+ * ?direction= speaks in anchor terms (source/target/both). Translate here —
+ * one mapping in one place — rather than leaking the API's wording into every
+ * agent's mental model.
+ */
+const DIRECTION_TO_API = {
+  outgoing: 'source',
+  incoming: 'target',
+  both: 'both',
+};
+
+/**
+ * List a given entity's links. Filters on linkType and targetType are
+ * optional — omit them for "all outgoing links".
+ *
+ * `direction` selects outgoing (default), incoming, or both — relates_to is
+ * not always stored bidirectionally, so "both" is what you want for an
+ * entity's full neighbourhood.
+ *
+ * `hydrate` resolves each target to its title/status so the caller can read the
+ * graph without a follow-up get_* per link. Opt-in because it costs a lookup
+ * per row.
+ */
+export async function listLinks({
+  sourceType,
+  sourceId,
+  linkType,
+  targetType,
+  hydrate,
+  direction,
+  includeSuggested,
+}) {
+  const params = { sourceType, sourceId };
+  if (linkType) params.linkType = linkType;
+  if (targetType) params.targetType = targetType;
+  if (hydrate) params.hydrate = 'true';
+  if (direction) params.direction = DIRECTION_TO_API[direction] || direction;
+  if (includeSuggested) params.includeSuggested = 'true';
+  return callZephlyAPI('mcpListLinks', params);
+}
+
+/**
+ * resolve_links — which components own these files?
+ *
+ * The read that makes linking cheap: an agent asks once, before creating work,
+ * and gets back the entities it should attach rather than having to know the
+ * component inventory. Returns `unresolved` too, because a path nothing covers
+ * is itself information — it usually means the inventory has a gap.
+ */
+export async function resolveLinks({ projectId, paths }) {
+  const { matches, unresolved } = await resolvePathsToComponents({ projectId, paths });
+  return {
+    deterministic: matches.filter((m) => m.score >= 1),
+    probable: matches.filter((m) => m.score < 1),
+    unmatchedPaths: unresolved,
+    count: matches.length,
+  };
+}
+
+/**
+ * preview_links — what would be linked, without writing.
+ *
+ * Split into the two groups a caller acts on differently: what EzModo records
+ * on its own, and what it wants confirmed.
+ */
+export async function previewLinks({
+  projectId,
+  subjectType,
+  subjectId,
+  paths,
+  componentId,
+  epicId,
+  trigger,
+}) {
+  const { proposals } = await previewEntityLinks({
+    projectId, subjectType, subjectId, paths, componentId, epicId, trigger,
+  });
+  const { autoLinked, linkSuggestions } = partitionProposals(proposals);
+
+  // Preview writes nothing, but the engine may already have queued rows for this
+  // entity from an earlier trigger. Attaching their ids lets a caller act on what
+  // it sees instead of taking a second lookup to find out how (#2297).
+  const resolved = await attachSuggestionIds({ subjectType, subjectId, linkSuggestions });
+  return {
+    autoLinked,
+    linkSuggestions: resolved.linkSuggestions,
+    count: autoLinked.length + resolved.linkSuggestions.length,
+  };
+}

package/handlers/milestones.js

@@ -0,0 +1,131 @@
+/**
+ * Milestone Handlers
+ * Handler functions for milestone-related MCP tools
+ *
+ * Milestones are project-scoped containers for tracking:
+ * - Version releases (e.g., v1.2.0, v2.0.0-beta)
+ * - Initiatives (e.g., Q1 2025, Sprint 5)
+ *
+ * Epics can be linked to milestones to track which features
+ * will be included in a release or initiative.
+ */
+
+import { callZephlyAPI } from '../lib/http-client.js';
+import { buildMilestoneUrl } from '../lib/web-url.js';
+
+/**
+ * Dispatch manage_milestone actions to the appropriate handler
+ */
+export async function manageMilestone(args) {
+  const { action, ...params } = args;
+  switch (action) {
+  case 'create': return createMilestone(params);
+  case 'update': return updateMilestone(params);
+  case 'delete': return deleteMilestone(params);
+  case 'link_epic': return linkEpicToMilestone(params);
+  case 'unlink_epic': return unlinkEpicFromMilestone(params);
+  case 'generate_changelog': return generateMilestoneChangelog(params);
+  case 'reorder_epics': return reorderMilestoneEpics(params);
+  case 'link_suite': return linkSuiteToMilestone(params);
+  case 'unlink_suite': return unlinkSuiteFromMilestone(params);
+  default: throw new Error(`Unknown action: ${action}`);
+  }
+}
+
+/**
+ * Unified get/list handler for milestones.
+ * - If milestoneId or milestoneSlug is provided, returns a single milestone.
+ * - Otherwise, lists all milestones for the project with optional filters.
+ * - If includeProgress is true, also fetches progress data.
+ */
+export async function getMilestone(args) {
+  const { includeProgress, type, status, ...rest } = args;
+  const isSingleLookup = rest.milestoneId || rest.milestoneSlug;
+
+  if (isSingleLookup) {
+    const result = await fetchSingleMilestone(rest);
+
+    if (includeProgress) {
+      const progress = await fetchMilestoneProgress(rest);
+      result.progress = progress;
+    }
+
+    return result;
+  }
+
+  // List mode
+  const listArgs = { projectId: rest.projectId };
+  if (type) listArgs.type = type;
+  if (status) listArgs.status = status;
+
+  return listMilestones(listArgs);
+}
+
+// --- Private helpers ---
+
+async function createMilestone(args) {
+  const result = await callZephlyAPI('mcpCreateMilestone', args);
+  const webUrl = await buildMilestoneUrl(result?.slug);
+  if (webUrl) result.webUrl = webUrl;
+  return result;
+}
+
+async function fetchSingleMilestone(args) {
+  const result = await callZephlyAPI('mcpGetMilestone', args);
+  const webUrl = await buildMilestoneUrl(result?.milestone?.slug);
+  if (webUrl && result?.milestone) result.milestone.webUrl = webUrl;
+  return result;
+}
+
+async function updateMilestone(args) {
+  return callZephlyAPI('mcpUpdateMilestone', args);
+}
+
+async function listMilestones(args) {
+  return callZephlyAPI('mcpListMilestones', args);
+}
+
+async function deleteMilestone(args) {
+  return callZephlyAPI('mcpDeleteMilestone', args);
+}
+
+async function linkEpicToMilestone(args) {
+  const { epicId, entityType, ...rest } = args;
+  return callZephlyAPI('mcpLinkEpicToMilestone', {
+    ...rest,
+    entityId: epicId,
+    entityType: entityType || 'epic',
+  });
+}
+
+async function unlinkEpicFromMilestone(args) {
+  return callZephlyAPI('mcpUnlinkEpicFromMilestone', args);
+}
+
+async function generateMilestoneChangelog(args) {
+  return callZephlyAPI('mcpGenerateMilestoneChangelog', args);
+}
+
+async function fetchMilestoneProgress(args) {
+  return callZephlyAPI('mcpGetMilestoneProgress', args);
+}
+
+async function reorderMilestoneEpics(args) {
+  const { itemIds, ...rest } = args;
+  return callZephlyAPI('mcpReorderMilestoneEpics', {
+    ...rest,
+    itemIds,
+  });
+}
+
+async function linkSuiteToMilestone(args) {
+  const { suiteId, ...rest } = args;
+  return callZephlyAPI('mcpLinkSuiteToMilestone', {
+    ...rest,
+    suiteId,
+  });
+}
+
+async function unlinkSuiteFromMilestone(args) {
+  return callZephlyAPI('mcpUnlinkSuiteFromMilestone', args);
+}

package/handlers/organizations.js

@@ -0,0 +1,14 @@
+/**
+ * Organization Handlers
+ * Handler functions for organization-related MCP tools
+ */
+
+import { callZephlyAPI } from '../lib/http-client.js';
+
+export async function getOrganization(args) {
+  const { mode = 'default' } = args;
+  if (mode === 'list') {
+    return callZephlyAPI('mcpListOrganizations', {});
+  }
+  return callZephlyAPI('mcpGetDefaultOrganization', {});
+}