@ezmodo/mcp-server 0.13.0

package/handlers/decisions.js

@@ -0,0 +1,114 @@
+/**
+ * Decision Handlers
+ * Handler functions for the Decisions / ADRs MCP tools (E-170).
+ *
+ * Decisions are org-level, durable ADR-style records (title, context, options,
+ * decision, consequences, status) that LINK to features and other artifacts via
+ * the generic link graph. These handlers are thin wrappers over
+ * /api/mcp/v1/decisions; dispatch and validation happen server-side in
+ * core/decisions.Service.
+ */
+
+import { callZephlyAPI } from '../lib/http-client.js';
+import { attachLinks } from '../lib/links-at-create.js';
+
+/**
+ * Dispatch manage_decision actions.
+ */
+export async function manageDecision(args) {
+  const { action, ...params } = args;
+  switch (action) {
+  case 'create': return createDecision(params);
+  case 'update': return updateDecision(params);
+  case 'delete': return deleteDecision(params);
+  case 'link': return linkDecisionArtifact(params);
+  case 'unlink': return unlinkDecisionArtifact(params);
+  case 'supersede': return supersedeDecision(params);
+  case 'promote_from_knowledge': return promoteFromKnowledge(params);
+  default:
+    throw new Error(`Unknown action: ${action}. Expected create, update, delete, link, unlink, supersede, or promote_from_knowledge.`);
+  }
+}
+
+/**
+ * Unified get/list handler for decisions.
+ * - decisionId → single lookup (optionally + links).
+ * - linkedType + linkedId → decisions linked to that entity (e.g. a feature).
+ * - organizationId only → list (optionally filtered by projectId/status/limit).
+ */
+export async function getDecision(args) {
+  const { includeLinks, decisionId, organizationId, linkedType, linkedId, ...filters } = args;
+
+  if (decisionId) {
+    const result = await callZephlyAPI('mcpGetDecision', { decisionId });
+    if (includeLinks) {
+      const links = await callZephlyAPI('mcpListDecisionLinks', { decisionId });
+      result.links = links?.links ?? links;
+    }
+    return result;
+  }
+
+  // List mode
+  const params = {};
+  if (organizationId) params.organizationId = organizationId;
+  if (linkedType && linkedId) {
+    params.linkedType = linkedType;
+    params.linkedId = linkedId;
+  }
+  if (filters.projectId) params.projectId = filters.projectId;
+  if (filters.status) params.status = filters.status;
+  if (filters.limit != null) params.limit = filters.limit;
+  return callZephlyAPI('mcpListDecisions', params);
+}
+
+// --- Private helpers ---
+
+async function createDecision(args) {
+  // `links` is applied by the MCP layer after the decision exists (E-225).
+  const { links, ...createArgs } = args;
+  const result = await callZephlyAPI('mcpCreateDecision', createArgs);
+
+  // Attach create-time links (E-225) — best effort, never fails the create.
+  await attachLinks(result, {
+    sourceType: 'decision',
+    sourceId: result?.decisionId || result?.decision?.id,
+    links,
+  });
+
+  return result;
+}
+
+async function updateDecision(args) {
+  return callZephlyAPI('mcpUpdateDecision', args);
+}
+
+async function deleteDecision({ decisionId }) {
+  return callZephlyAPI('mcpDeleteDecision', { decisionId });
+}
+
+async function linkDecisionArtifact({ decisionId, targetType, targetId }) {
+  return callZephlyAPI('mcpLinkDecisionArtifact', { decisionId, targetType, targetId });
+}
+
+async function unlinkDecisionArtifact({ decisionId, targetType, targetId }) {
+  return callZephlyAPI('mcpUnlinkDecisionArtifact', { decisionId, targetType, targetId });
+}
+
+// Mark a decision as superseded by another decision (records the supersession
+// chain; the superseded decision's status moves to "superseded" server-side).
+async function supersedeDecision({ decisionId, supersededById }) {
+  return callZephlyAPI('mcpSupersedeDecision', { decisionId, supersededById });
+}
+
+// Elevate a task's decision-type knowledge item into a durable Decision (E-170),
+// optionally linking the new decision to an artifact in the same call.
+async function promoteFromKnowledge({ organizationId, taskId, knowledgeId, title, linkToType, linkToId }) {
+  return callZephlyAPI('mcpPromoteDecisionFromKnowledge', {
+    organizationId,
+    taskId,
+    knowledgeId,
+    title,
+    linkToType,
+    linkToId,
+  });
+}

package/handlers/designs.js

@@ -0,0 +1,118 @@
+/**
+ * Design Handlers
+ * Handler functions for the Designs MCP tools (the in-product living design system).
+ *
+ * A Design is an AI-authored HTML/CSS artifact (kind ∈ theme|component|page) that
+ * captures the house style. Designs are org-level (project_id nullable) and LINK
+ * to features and other artifacts via the generic link graph. These handlers are
+ * thin wrappers over /api/mcp/v1/designs; dispatch and validation happen
+ * server-side in core/designs.Service.
+ */
+
+import { callZephlyAPI } from '../lib/http-client.js';
+import { attachLinks } from '../lib/links-at-create.js';
+
+/**
+ * Dispatch manage_design actions.
+ */
+export async function manageDesign(args) {
+  const { action, ...params } = args;
+  switch (action) {
+  case 'create': return createDesign(params);
+  case 'update': return updateDesign(params);
+  case 'delete': return deleteDesign(params);
+  case 'link': return linkDesignArtifact(params);
+  case 'unlink': return unlinkDesignArtifact(params);
+  default:
+    throw new Error(`Unknown action: ${action}. Expected create, update, delete, link, or unlink.`);
+  }
+}
+
+/**
+ * Unified get/list handler for designs.
+ * - linkedType + linkedId → designs linked to that entity (e.g. a feature).
+ * - designId → single lookup (optionally + links).
+ */
+export async function getDesign(args) {
+  const { includeLinks, designId, organizationId, linkedType, linkedId, ...filters } = args;
+
+  if (linkedType && linkedId) {
+    const params = { linkedType, linkedId };
+    if (organizationId) params.organizationId = organizationId;
+    if (filters.projectId) params.projectId = filters.projectId;
+    if (filters.kind) params.kind = filters.kind;
+    if (filters.status) params.status = filters.status;
+    if (filters.limit != null) params.limit = filters.limit;
+    return callZephlyAPI('mcpListDesigns', params);
+  }
+
+  if (designId) {
+    const result = await callZephlyAPI('mcpGetDesign', { designId });
+    if (includeLinks) {
+      const links = await callZephlyAPI('mcpListDesignLinks', { designId });
+      result.links = links?.links ?? links;
+    }
+    return result;
+  }
+
+  // Fall back to list mode (organizationId + filters)
+  return listDesigns({ organizationId, ...filters });
+}
+
+/**
+ * List designs for an organization, optionally filtered by project/kind/status.
+ */
+export async function listDesigns(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.status) params.status = args.status;
+  if (args.includeOrgWide != null) params.includeOrgWide = args.includeOrgWide;
+  if (args.limit != null) params.limit = args.limit;
+  return callZephlyAPI('mcpListDesigns', params);
+}
+
+/**
+ * Retrieve the design system (theme + components) for an org/project. Call this
+ * first to learn the existing house style before authoring new UI.
+ */
+export async function getDesignSystem(args) {
+  const params = {};
+  if (args.organizationId) params.organizationId = args.organizationId;
+  if (args.projectId) params.projectId = args.projectId;
+  return callZephlyAPI('mcpGetDesignSystem', params);
+}
+
+// --- Private helpers ---
+
+async function createDesign(args) {
+  // `links` is applied by the MCP layer after the design exists (E-225).
+  const { links, ...createArgs } = args;
+  const result = await callZephlyAPI('mcpCreateDesign', createArgs);
+
+  // Attach create-time links (E-225) — best effort, never fails the create.
+  await attachLinks(result, {
+    sourceType: 'design',
+    sourceId: result?.designId || result?.design?.id,
+    links,
+  });
+
+  return result;
+}
+
+async function updateDesign(args) {
+  return callZephlyAPI('mcpUpdateDesign', args);
+}
+
+async function deleteDesign({ designId }) {
+  return callZephlyAPI('mcpDeleteDesign', { designId });
+}
+
+async function linkDesignArtifact({ designId, targetType, targetId }) {
+  return callZephlyAPI('mcpLinkDesign', { designId, targetType, targetId });
+}
+
+async function unlinkDesignArtifact({ designId, targetType, targetId }) {
+  return callZephlyAPI('mcpUnlinkDesign', { designId, targetType, targetId });
+}

package/handlers/documents.js

@@ -0,0 +1,227 @@
+/**
+ * Document Handlers
+ * Handler functions for documentation-related MCP tools
+ */
+
+import fs from 'fs/promises';
+import path from 'path';
+import { callZephlyAPI } from '../lib/http-client.js';
+import { findConfigPath } from '../lib/local-cache.js';
+import { getLogger } from '../lib/logger.js';
+import { attachLinks } from '../lib/links-at-create.js';
+
+/**
+ * Dispatch manage_document actions to the appropriate handler
+ */
+export async function manageDocument(args) {
+  const { action, ...params } = args;
+  switch (action) {
+  case 'create': return createDocument(params);
+  case 'update': return updateDocument(params);
+  case 'create_version': throw new Error('Document versioning is not yet supported. Use the "update" action to modify documents.');
+  default: throw new Error(`Unknown action: ${action}`);
+  }
+}
+
+/**
+ * Dispatch manage_document_template actions to the appropriate handler
+ */
+export async function manageDocumentTemplate(args) {
+  const { action, ...params } = args;
+  switch (action) {
+  case 'create': return createDocumentTemplate(params);
+  case 'delete': return deleteDocumentTemplate(params);
+  default: throw new Error(`Unknown action: ${action}`);
+  }
+}
+
+/**
+ * Unified get/list handler for documents.
+ * - If documentId or slug is provided, returns a single document.
+ * - Otherwise, lists all documents for the project with optional filters.
+ * - Optionally includes version history or fetches a specific version.
+ */
+export async function getDocument(args) {
+  const { docType, tags, status, includeVersions, versionNumber, versionLimit, ...rest } = args;
+  const isSingleLookup = rest.documentId || rest.slug;
+
+  if (isSingleLookup) {
+    // Specific version requested
+    if (versionNumber !== undefined) {
+      return fetchDocumentVersion({ documentId: rest.documentId, versionNumber });
+    }
+
+    const result = await fetchSingleDocument(rest);
+
+    // Include version history if requested
+    if (includeVersions) {
+      const versions = await listDocumentVersions({
+        documentId: rest.documentId || result?.document?.id,
+        limit: versionLimit,
+      });
+      result.versions = versions;
+    }
+
+    return result;
+  }
+
+  // List mode
+  const listArgs = { projectId: rest.projectId };
+  if (docType) listArgs.docType = docType;
+  if (tags) listArgs.tags = tags;
+  if (status) listArgs.status = status;
+
+  return getDocumentation(listArgs);
+}
+
+/**
+ * Unified get/list handler for document templates.
+ * - If templateId is provided, returns a single template.
+ * - Otherwise, lists all templates with optional filters.
+ */
+export async function getDocumentTemplate(args) {
+  const { templateId, category, type } = args;
+
+  if (templateId) {
+    return fetchSingleDocumentTemplate({ templateId });
+  }
+
+  // List mode
+  const listArgs = {};
+  if (category) listArgs.category = category;
+  if (type) listArgs.type = type;
+
+  return listDocumentTemplates(listArgs);
+}
+
+// --- Private helpers ---
+
+async function getDocumentation(args) {
+  return callZephlyAPI('mcpGetDocumentation', args);
+}
+
+async function fetchSingleDocument(args) {
+  const data = await callZephlyAPI('mcpGetDocument', args);
+  const doc = data.document;
+
+  if (!doc) {
+    return data;
+  }
+
+  if (!doc.content) {
+    return data;
+  }
+
+  // Save content to <repo-config-dir>/docs/<slug-or-id>.md
+  const configPath = await findConfigPath();
+  if (!configPath) {
+    // No project config directory found — return as-is.
+    return data;
+  }
+
+  const configDir = path.dirname(configPath);
+  const docsDir = path.join(configDir, 'docs');
+  const filename = `${doc.slug || doc.id}.md`;
+  const filePath = path.resolve(docsDir, filename);
+
+  try {
+    await fs.mkdir(docsDir, { recursive: true });
+    await fs.writeFile(filePath, doc.content, 'utf-8');
+  } catch (err) {
+    getLogger().warn('Failed to save document to local file', { error: err.message, filePath });
+    // Fall back to returning full content in response
+    return data;
+  }
+
+  // Return metadata + file path, omit heavy content from response
+  const { content, ...metadata } = doc;
+  return {
+    ...data,
+    document: metadata,
+    localFilePath: filePath,
+    message: `Document content saved to ${filePath}. Use the Read tool to access it when needed.`,
+  };
+}
+
+async function createDocument(args) {
+  // Support both top-level summary/keyPoints and nested aiContext input.
+  // `links` is applied by the MCP layer after the document exists (E-225).
+  const { summary, keyPoints, aiContext, links, ...rest } = args;
+  const hasFlatFields = summary !== undefined || keyPoints !== undefined;
+  if (hasFlatFields || aiContext) {
+    rest.aiContext = {
+      ...(aiContext || {}),
+      ...(summary !== undefined ? { summary } : {}),
+      ...(keyPoints !== undefined ? { keyPoints } : {}),
+    };
+  }
+
+  const result = await callZephlyAPI('mcpCreateDocument', rest);
+
+  // Attach create-time links (E-225) — best effort, never fails the create.
+  await attachLinks(result, {
+    sourceType: 'document',
+    sourceId: result?.documentId,
+    links,
+  });
+
+  return result;
+}
+
+async function updateDocument(args) {
+  // Support both top-level summary/keyPoints and nested aiContext input
+  const { summary, keyPoints, aiContext, addRelatedItem, removeRelatedItem, ...rest } = args;
+  const hasFlatFields = summary !== undefined || keyPoints !== undefined;
+  if (hasFlatFields || aiContext) {
+    rest.aiContext = {
+      ...(aiContext || {}),
+      ...(summary !== undefined ? { summary } : {}),
+      ...(keyPoints !== undefined ? { keyPoints } : {}),
+    };
+  }
+
+  if (addRelatedItem !== undefined) {
+    rest.addRelatedItem = addRelatedItem;
+  }
+  if (removeRelatedItem !== undefined) {
+    rest.removeRelatedItem = removeRelatedItem;
+  }
+
+  return callZephlyAPI('mcpUpdateDocument', rest);
+}
+
+/**
+ * List an organization's project-less (org-scoped) documents. (E-195)
+ * Params: organizationId (required), folderId (optional), limit (optional).
+ */
+export async function listOrgDocuments(args) {
+  return callZephlyAPI('mcpListOrgDocuments', args);
+}
+
+// Document Version helpers
+
+async function listDocumentVersions(args) {
+  return callZephlyAPI('mcpListDocumentVersions', args);
+}
+
+async function fetchDocumentVersion(args) {
+  return callZephlyAPI('mcpGetDocumentVersion', args);
+}
+
+// Document Template helpers
+
+async function listDocumentTemplates(args) {
+  return callZephlyAPI('mcpListDocumentTemplates', args);
+}
+
+async function fetchSingleDocumentTemplate(args) {
+  return callZephlyAPI('mcpGetDocumentTemplate', args);
+}
+
+async function createDocumentTemplate(args) {
+  return callZephlyAPI('mcpCreateDocumentTemplate', args);
+}
+
+async function deleteDocumentTemplate(args) {
+  return callZephlyAPI('mcpDeleteDocumentTemplate', args);
+}

package/handlers/entities.js

@@ -0,0 +1,95 @@
+/**
+ * Entity Handlers
+ * Handler functions for goals, teams, and labels
+ *
+ * Consolidated: manageGoal dispatches create/update/delete.
+ * manageTeam dispatches create.
+ * getGoal unifies get (by ID or number) and list.
+ */
+
+import { callZephlyAPI } from '../lib/http-client.js';
+import { buildGoalUrl } from '../lib/web-url.js';
+
+/**
+ * Dispatch manage_goal actions to the appropriate handler
+ */
+export async function manageGoal(args) {
+  const { action, ...params } = args;
+  switch (action) {
+  case 'create': return createGoal(params);
+  case 'update': return updateGoal(params);
+  case 'delete': return deleteGoal(params);
+  case 'generate_how_it_works': return generateGoalHowItWorks(params);
+  case 'apply_how_it_works': return applyGoalHowItWorks(params);
+  default: throw new Error(`Unknown action: ${action}`);
+  }
+}
+
+/**
+ * Dispatch manage_team actions to the appropriate handler
+ */
+export async function manageTeam(args) {
+  const { action, ...params } = args;
+  switch (action) {
+  case 'create': return createTeam(params);
+  default: throw new Error(`Unknown action: ${action}`);
+  }
+}
+
+/**
+ * Unified get/list handler for goals
+ */
+export async function getGoal(args) {
+  // Single goal lookup by ID or number
+  if (args.goalId || args.goalNumber) {
+    const result = await callZephlyAPI('mcpGetGoal', args);
+    const goalId = result?.goal?.id || result?.goal?.goalId;
+    const webUrl = await buildGoalUrl(goalId);
+    if (webUrl && result?.goal) result.goal.webUrl = webUrl;
+    return result;
+  }
+
+  // List mode
+  return callZephlyAPI('mcpListGoals', args);
+}
+
+// --- Private helpers ---
+
+async function createGoal(args) {
+  const result = await callZephlyAPI('mcpCreateGoal', args);
+  const webUrl = await buildGoalUrl(result?.goalId);
+  if (webUrl) result.webUrl = webUrl;
+  return result;
+}
+
+async function updateGoal(args) {
+  return callZephlyAPI('mcpUpdateGoal', args);
+}
+
+async function deleteGoal(args) {
+  return callZephlyAPI('mcpDeleteGoal', args);
+}
+
+// Generate (and persist) the goal's grounded "how it works" living description
+// via the model. AI-quota gated server-side (mirrors features.generateHowItWorks).
+async function generateGoalHowItWorks({ goalId }) {
+  const result = await callZephlyAPI('mcpGenerateGoalHowItWorks', { goalId });
+  const id = result?.goal?.id || result?.goal?.goalId || goalId;
+  const webUrl = await buildGoalUrl(id);
+  if (webUrl && result?.goal) result.goal.webUrl = webUrl;
+  return result;
+}
+
+// Apply (persist) a LOCAL-agent-authored "how it works" for a goal (BYO-AI,
+// E-190). Cited sources are validated server-side before saving; no model call.
+async function applyGoalHowItWorks({ goalId, markdown, sources }) {
+  const result = await callZephlyAPI('mcpApplyGoalHowItWorks', { goalId, markdown, sources });
+  const id = result?.goal?.id || result?.goal?.goalId || goalId;
+  const webUrl = await buildGoalUrl(id);
+  if (webUrl && result?.goal) result.goal.webUrl = webUrl;
+  return result;
+}
+
+async function createTeam(args) {
+  return callZephlyAPI('mcpCreateTeam', args);
+}