@ezmodo/mcp-server 0.14.4 → 0.17.1

package/handlers/components.js

@@ -1,282 +0,0 @@
-/**
- * Component Handlers
- * Handler functions for component-related MCP tools
- *
- * Components are project-scoped entries in the unified UI inventory (E-168).
- * A single Component concept spans four kinds:
- * - area      — coarse codebase module (api, web, mobile); the legacy meaning
- * - screen    — a mobile / Flutter screen
- * - page      — a web route / page
- * - component — a reusable UI component
- * Components self-nest via parentComponentId (e.g. web → Sprint Board → TaskCard)
- * and carry sourcePath / route / framework. The task component-picker uses
- * kind=area. This is ONE concept — there is no separate "UI surface" entity.
- *
- * list_components uses local cache for simple requests, falling back to API.
- * Write operations (create, update, delete) invalidate the cache.
- */
-
-import { callZephlyAPI } from '../lib/http-client.js';
-import { getCachedComponents, updateCacheSections, invalidateCacheSection } from '../lib/local-cache.js';
-import { attachLinks, applyLinks } from '../lib/links-at-create.js';
-
-/**
- * Dispatch manage_component actions to the appropriate handler
- */
-export async function manageComponent(args) {
-  const { action, ...params } = args;
-  switch (action) {
-  case 'create': return createComponent(params);
-  case 'update': return updateComponent(params);
-  case 'delete': return deleteComponent(params);
-  case 'add_dependency': return addComponentDependency(params);
-  case 'remove_dependency': return removeComponentDependency(params);
-  case 'add_navigation': return addComponentNavigation(params);
-  case 'remove_navigation': return removeComponentNavigation(params);
-  case 'derive_navigation': return deriveComponentNavigation(params);
-  case 'discover': return discoverComponents(params);
-  case 'import': return importComponents(params);
-  default: throw new Error(`Unknown action: ${action}`);
-  }
-}
-
-/**
- * List components with optional enrichment data.
- * Uses local cache when available and fresh for basic list, falls back to API.
- */
-export async function listComponents(args) {
-  const { componentId, componentSlug, include, ...rest } = args;
-  const isSingleLookup = componentId || componentSlug;
-  const includes = include || [];
-
-  // Timeline is NOT a supported include. It is rejected here — loudly, and on
-  // every path — rather than dropped, because the API never had the data:
-  // nothing populates Component.CachedTimeline (there is no cached_timeline
-  // column, and repository_postgres.go neither reads nor writes the field), so
-  // Service.GetComponentTimeline always returns a zeroed struct. The single
-  // lookup therefore did not "work" while lists silently degraded; it answered
-  // all-zeros, which reads as a real empty result and is the worse failure of
-  // the two. Removing it from the schema enum is not enough on its own — a
-  // client that ignores the enum must still get an error, not a plain list.
-  if (includes.includes('timeline')) {
-    throw new Error(
-      'include:["timeline"] is not supported: component timeline data is not computed by the ' +
-      'API, so it would return all zeros rather than real data. Use include:["stats"] for task ' +
-      'counts (per component with componentId/componentSlug, or project-wide without one).'
-    );
-  }
-
-  // Stats. With an identifier: that component. Without one: every component in
-  // the project (the endpoint takes the identifier as optional). This branch
-  // used to require isSingleLookup, so `include:["stats"]` on a list fell
-  // through to the plain list and the stats request vanished without an error.
-  if (includes.includes('stats')) {
-    return getComponentStats({ projectId: rest.projectId, componentId, componentSlug });
-  }
-
-  // Navigation graph (project-wide screen→screen edges, E-223).
-  if (includes.includes('navigation')) {
-    return getComponentNavigation({ projectId: rest.projectId });
-  }
-
-  // Dependency graph (project-wide). The kind filter must be forwarded: this
-  // branch bypasses the plain list entirely, so dropping `kind` here silently
-  // returned the WHOLE inventory to a caller who asked for one kind.
-  if (includes.includes('dependency_graph')) {
-    const graphArgs = { projectId: rest.projectId };
-    if (rest.kind) graphArgs.kind = rest.kind;
-    return getComponentDependencyGraph(graphArgs);
-  }
-
-  // Basic list — use cache if available. Skip the cache when a kind filter is
-  // set (E-168): the cache holds the full inventory, not kind-filtered subsets.
-  if (rest.projectId && !isSingleLookup && !rest.kind) {
-    const cached = await getCachedComponents(rest.projectId);
-    if (cached !== null) {
-      return { components: cached, cached: true };
-    }
-  }
-
-  // The identifier must be forwarded: it is destructured out of `rest` above,
-  // so without this a single lookup fell through to a plain list and returned
-  // the WHOLE inventory to a caller who asked for one component — the same
-  // dropped-filter shape as the `kind` bug, and just as silent.
-  const listArgs = { ...rest };
-  if (componentId) listArgs.componentId = componentId;
-  if (componentSlug) listArgs.componentSlug = componentSlug;
-
-  const result = await callZephlyAPI('mcpListComponents', listArgs);
-
-  // Cache the results for future use. Only cache the FULL inventory — neither a
-  // kind-filtered result (e.g. kind='area' from the project-context path) nor a
-  // single lookup may overwrite the cache, or an unfiltered list_components
-  // would then read back a subset (mirrors the cache-read skip above). The
-  // single-lookup guard matters as of the fix above: while the identifier was
-  // being dropped this call returned the full list, so caching it was harmless.
-  if (rest.projectId && !isSingleLookup && !rest.kind && result?.components) {
-    const summaries = result.components.map((c) => ({
-      id: c.id,
-      name: c.name,
-      description: c.description || '',
-    }));
-    await updateCacheSections({ components: summaries });
-  }
-
-  return result;
-}
-
-/**
- * Create a new component
- */
-async function createComponent(args) {
-  // `links` is applied by the MCP layer after the component exists (E-225).
-  const { links, ...createArgs } = args;
-  const result = await callZephlyAPI('mcpCreateComponent', createArgs);
-  await invalidateCacheSection('components');
-
-  // Attach create-time links (E-225) — best effort, never fails the create.
-  await attachLinks(result, {
-    sourceType: 'component',
-    sourceId: result?.componentId,
-    links,
-  });
-
-  return result;
-}
-
-/**
- * Update an existing component
- */
-async function updateComponent(args) {
-  const result = await callZephlyAPI('mcpUpdateComponent', args);
-  await invalidateCacheSection('components');
-  return result;
-}
-
-/**
- * Delete a component
- */
-async function deleteComponent(args) {
-  const result = await callZephlyAPI('mcpDeleteComponent', args);
-  await invalidateCacheSection('components');
-  return result;
-}
-
-/**
- * Get stats for a component
- */
-async function getComponentStats(args) {
-  return callZephlyAPI('mcpGetComponentStats', args);
-}
-
-/**
- * Add a dependency between two components
- */
-async function addComponentDependency(args) {
-  return callZephlyAPI('mcpAddComponentDependency', args);
-}
-
-/**
- * Remove a dependency between two components
- */
-async function removeComponentDependency(args) {
-  return callZephlyAPI('mcpRemoveComponentDependency', args);
-}
-
-/**
- * Get the full dependency graph for a project's components
- */
-async function getComponentDependencyGraph(args) {
-  return callZephlyAPI('mcpGetComponentDependencyGraph', args);
-}
-
-/**
- * Add a screen→screen navigation edge (E-223). Endpoints may be given as IDs or
- * slugs. Idempotent — re-adding an existing edge is a no-op.
- */
-async function addComponentNavigation(args) {
-  return callZephlyAPI('mcpAddComponentNavigation', args);
-}
-
-/**
- * Remove a screen→screen navigation edge (E-223). Idempotent.
- */
-async function removeComponentNavigation(args) {
-  return callZephlyAPI('mcpRemoveComponentNavigation', args);
-}
-
-/**
- * Re-derive the screen-flow map from the synced Context Manifest (E-239 #2409).
- *
- * Idempotent, and it cannot destroy hand-drawn work: it reconciles only edges
- * still at origin auto/inferred under its own rules, so a human's edge — or one
- * they promoted — is left alone and reported as `spared`.
- *
- * Returns { result: { derived, byRule, retracted, spared, unresolved }, projectId }.
- * `unresolved` names navigation references no component matched, which is how a
- * stale inventory shows itself instead of the map silently shrinking.
- */
-async function deriveComponentNavigation({ projectId }) {
-  return callZephlyAPI('mcpDeriveComponentNavigation', { projectId });
-}
-
-/**
- * Read the project's navigation edges (E-223) so an agent can see the existing
- * flow before writing to it. Returns { edges, projectId }.
- */
-async function getComponentNavigation(args) {
-  return callZephlyAPI('mcpGetComponentNavigation', args);
-}
-
-/**
- * Discover candidate UI surfaces (page / component kinds) for a project from the
- * Context Manifest that are not yet in the inventory (E-168). Manifest-assisted;
- * returns { surfaces: [{kind,name,sourcePath,route,framework,summary}], projectId, count }.
- */
-async function discoverComponents({ projectId }) {
-  return callZephlyAPI('mcpDiscoverComponents', { projectId });
-}
-
-/**
- * Bulk-import UI surfaces as components (E-168). Each surface becomes a component,
- * optionally nested under parentComponentId and/or linked to featureId.
- * Returns { imported: [{componentId,slug,name,kind,sourcePath,linked}], count }.
- */
-async function importComponents({ projectId, parentComponentId, featureId, surfaces }) {
-  // Per-surface `links` are applied by the MCP layer after import, so a 90-screen
-  // import can carry its links in one call (E-225) instead of 90 manage_link
-  // round trips.
-  const list = Array.isArray(surfaces) ? surfaces : [];
-  const body = {
-    projectId,
-    surfaces: list.map(({ links, ...surface }) => surface),  
-  };
-  if (parentComponentId) body.parentComponentId = parentComponentId;
-  if (featureId) body.featureId = featureId;
-  const result = await callZephlyAPI('mcpImportComponents', body);
-  await invalidateCacheSection('components');
-
-  // Match each imported component back to the surface that asked for links.
-  // Matching on name + sourcePath rather than index because the API is free to
-  // skip surfaces that already exist.
-  const imported = Array.isArray(result?.imported) ? result.imported : [];
-  const linkResults = [];
-  for (const surface of list) {
-    if (!Array.isArray(surface?.links) || surface.links.length === 0) continue;
-    const match = imported.find(
-      (c) => c?.name === surface.name && (!surface.sourcePath || c?.sourcePath === surface.sourcePath),
-    );
-    if (!match?.componentId) continue;
-    const outcome = await applyLinks({
-      sourceType: 'component',
-      sourceId: match.componentId,
-      links: surface.links,
-    });
-    linkResults.push({ componentId: match.componentId, ...outcome });
-  }
-  if (linkResults.length > 0 && result && typeof result === 'object') {
-    result.links = linkResults;
-  }
-
-  return result;
-}

package/tools/components.js

@@ -1,249 +0,0 @@
-/**
- * Component Tools
- * MCP tools for the unified UI inventory (E-168).
- *
- * NAMING (E-107): a project's type renames the `area` kind only — a marketing
- * project calls an area a "Channel", a sales project a "Segment". The screen,
- * page and component kinds keep their literal names, because "Channel: screen"
- * is nonsense. Read the word from `get_current_project_context().terminology`.
- *
- * A Component is ONE concept that spans four kinds:
- *   - area      — coarse codebase module / domain (api, web, mcp-server); the
- *                 legacy meaning. The task component-picker uses kind=area.
- *   - screen    — a mobile / Flutter screen
- *   - page      — a web route / page
- *   - component — a reusable UI component
- * There is NO separate "UI surface" entity — surfaces ARE components. Components
- * self-nest via parentComponentId (e.g. web → Sprint Board → TaskCard) and carry
- * sourcePath / route / framework. They can be discovered from the Context
- * Manifest and bulk-imported.
- */
-
-import { LINKS_ARRAY_SCHEMA } from './link-params.js';
-
-export const COMPONENT_TOOLS = [
-  {
-    name: 'manage_component',
-    description: 'Create, update, delete components, manage component dependencies and screen ' +
-      'navigation edges, or discover/import ' +
-      'UI surfaces. A Component is the unified UI inventory entry — ONE concept spanning kinds ' +
-      'area|screen|page|component (there is no separate "UI surface" entity). "area" is the legacy ' +
-      'coarse codebase module (api, web, mobile) and is what the task component-picker uses; ' +
-      '"screen"/"page"/"component" describe mobile screens, web pages, and reusable UI components. ' +
-      'Components self-nest via parentComponentId and carry sourcePath/route/framework. ' +
-      '"discover" proposes page/component surfaces from the Context Manifest not yet in the inventory; ' +
-      '"import" bulk-creates surfaces (optionally nested under a parent and/or linked to a feature).',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        action: {
-          type: 'string',
-          enum: ['create', 'update', 'delete', 'add_dependency', 'remove_dependency',
-            'add_navigation', 'remove_navigation', 'derive_navigation', 'discover', 'import'],
-          description: 'Action to perform. "discover" (pass projectId) returns candidate UI surfaces ' +
-            'from the Context Manifest not yet in the inventory. "import" (pass projectId + surfaces, ' +
-            'optionally parentComponentId + featureId) bulk-creates components from surfaces. ' +
-            '"add_navigation"/"remove_navigation" (pass projectId + sourceComponentId + ' +
-            'targetComponentId) manage screen\u2192screen navigation edges for the screen-flow map ' +
-            '(E-223) \u2014 a DIFFERENT relation from add_dependency: navigation is "you can get ' +
-            'there from here" and only valid between screens/pages, whereas a dependency is a code ' +
-            'relationship. Read the current flow with list_components include:["navigation"]. ' +
-            '"derive_navigation" (pass projectId) RE-DERIVES the whole flow map from the synced ' +
-            'Context Manifest \u2014 prefer it to drawing edges by hand, because a derived map stays ' +
-            'true for free while an asserted one decays from the moment it is written (E-239). It is ' +
-            'idempotent and cannot delete a human\u2019s edge: it reconciles only edges still at ' +
-            'origin auto/inferred under its own rules, reporting the rest as `spared`. Check the ' +
-            '`unresolved` list in the response \u2014 references no component matched mean the ' +
-            'inventory is missing a screen, not that the code has no navigation.',
-        },
-        // --- Identifiers ---
-        projectId: {
-          type: 'string',
-          description: 'Project ID (required for create, delete, add_dependency, remove_dependency)',
-        },
-        componentId: {
-          type: 'string',
-          description: 'Component ID (required for update, delete, add_dependency, remove_dependency)',
-        },
-        componentSlug: {
-          type: 'string',
-          description: 'URL-friendly slug of the component (alternative to componentId for update, delete, add_dependency, remove_dependency)',
-        },
-        // --- Create / Update fields ---
-        name: {
-          type: 'string',
-          description: 'Component name (required for create, e.g., "api", "web", "mcp-server", "functions")',
-        },
-        description: {
-          type: 'string',
-          description: 'Description of what this component covers (create, update). ' +
-            'Writing this stays plain text; it does not create a backing document.',
-        },
-        color: {
-          type: 'string',
-          description: 'Hex color for UI display (e.g., "#3B82F6"). Defaults to blue if not provided. (create, update)',
-        },
-        icon: {
-          type: 'string',
-          description: 'Icon name for the component (create, update)',
-        },
-        // --- Unified UI-inventory fields (E-168) (create, update) ---
-        kind: {
-          type: 'string',
-          enum: ['area', 'screen', 'page', 'component'],
-          description: 'Kind of inventory entry (default "area"). "area" = coarse codebase module ' +
-            '(api/web/mobile — the legacy meaning, used by the task component-picker); "screen" = ' +
-            'mobile/Flutter screen; "page" = web route/page; "component" = reusable UI component. ' +
-            '(create, update)',
-        },
-        parentComponentId: {
-          type: 'string',
-          description: 'Parent component ID for self-nesting (e.g. web → Sprint Board → TaskCard). ' +
-            'On update, pass an empty string to clear it (make top-level). (create, update)',
-        },
-        sourcePath: {
-          type: 'string',
-          description: 'Repo file/dir path this surface maps to (create, update)',
-        },
-        route: {
-          type: 'string',
-          description: 'Route this surface serves, for page/screen kinds (create, update)',
-        },
-        framework: {
-          type: 'string',
-          description: 'Framework, e.g. "nextjs", "flutter", "react" (create, update)',
-        },
-        // --- import fields ---
-        featureId: {
-          type: 'string',
-          description: 'Optionally link every imported component to this feature (import only)',
-        },
-        surfaces: {
-          type: 'array',
-          description: 'UI surfaces to import as components (required for import)',
-          items: {
-            type: 'object',
-            properties: {
-              kind: {
-                type: 'string',
-                enum: ['area', 'screen', 'page', 'component'],
-                description: 'Kind of surface',
-              },
-              name: { type: 'string', description: 'Surface / component name' },
-              sourcePath: { type: 'string', description: 'Repo file/dir path it maps to' },
-              route: { type: 'string', description: 'Route it serves (page/screen kinds)' },
-              framework: { type: 'string', description: 'Framework (nextjs, flutter, react, ...)' },
-              links: LINKS_ARRAY_SCHEMA,
-            },
-            required: ['kind', 'name'],
-          },
-        },
-        links: LINKS_ARRAY_SCHEMA,
-        // --- Create-only fields ---
-        ownerId: {
-          type: 'string',
-          description: 'Owner user ID — who maintains this component (create only)',
-        },
-        ownerName: {
-          type: 'string',
-          description: 'Display name of the owner (required if ownerId is set, create only)',
-        },
-        teamId: {
-          type: 'string',
-          description: 'Team ID — which team is responsible (create, update)',
-        },
-        // --- Update-only fields ---
-        order: {
-          type: 'number',
-          description: 'Display order, lower = first (update only)',
-        },
-        owner: {
-          type: 'object',
-          description: 'Component owner object (set to null to clear). Object with id and name fields. (update only)',
-          properties: {
-            id: { type: 'string', description: 'Owner user ID' },
-            name: { type: 'string', description: 'Owner display name' },
-          },
-          nullable: true,
-        },
-        // --- Dependency fields (add_dependency, remove_dependency) ---
-        targetComponentId: {
-          type: 'string',
-          description: 'The other end of the edge. For add_dependency/remove_dependency: the ' +
-            'component depended on. For add_navigation/remove_navigation: the screen navigated TO ' +
-            '(must be kind screen or page).',
-        },
-        type: {
-          type: 'string',
-          enum: ['depends_on', 'blocks'],
-          description: 'Dependency type: "depends_on" (source needs target) or "blocks" ' +
-            '(source blocks target). Required for add_dependency. Cycles are ALLOWED \u2014 code ' +
-            'imports are legitimately mutual \u2014 but a dependency that closes one comes back with ' +
-            'a `warning` and the `cyclePath` naming the loop. Re-adding an existing dependency is ' +
-            'an idempotent no-op that returns `alreadyExisted: true`.',
-        },
-        // --- Navigation fields (add_navigation, remove_navigation) — E-223 ---
-        sourceComponentId: {
-          type: 'string',
-          description: 'Screen the user navigates FROM (required for add_navigation/remove_navigation, ' +
-            'unless sourceComponentSlug is given). Must be kind screen or page.',
-        },
-        sourceComponentSlug: {
-          type: 'string',
-          description: 'Slug alternative to sourceComponentId (add_navigation, remove_navigation)',
-        },
-        targetComponentSlug: {
-          type: 'string',
-          description: 'Slug alternative to targetComponentId (add_navigation, remove_navigation)',
-        },
-      },
-      required: ['action'],
-    },
-  },
-  {
-    name: 'list_components',
-    description: 'List components in a project, optionally with stats, dependency graph, or navigation data. ' +
-      'Provide componentId (or componentSlug) to get data for a single component — the response is the ' +
-      'same shape as a list, with `components` holding just that one; an identifier that matches nothing ' +
-      'is an error, never the full inventory. ' +
-      'Responses include `descriptionDocumentId` — the id of the backing rich-description Document ' +
-      'when the description has been promoted to one (E-189), otherwise omitted.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        projectId: {
-          type: 'string',
-          description: 'The project ID (required)',
-        },
-        componentId: {
-          type: 'string',
-          description: 'Optional component ID — narrows the listing to that one component',
-        },
-        componentSlug: {
-          type: 'string',
-          description: 'Optional component slug (alternative to componentId; the slug wins if both are given)',
-        },
-        kind: {
-          type: 'string',
-          enum: ['area', 'screen', 'page', 'component'],
-          description: 'Optional filter — only return components of this kind. Use kind="area" for ' +
-            'the coarse codebase modules the task component-picker uses.',
-        },
-        include: {
-          type: 'array',
-          items: {
-            type: 'string',
-            enum: ['stats', 'dependency_graph', 'navigation'],
-          },
-          description: 'Optional additional data to include: stats (task counts), dependency_graph ' +
-            '(all dependencies; honours the kind filter), ' +
-            'navigation (screen\u2192screen navigates_to edges for the screen-flow map, E-223). ' +
-            'Note: "timeline" is NOT available \u2014 component timeline data is not computed by the ' +
-            'API (nothing populates it, so it read back as all zeros on every path). Use ' +
-            '"stats" for task counts.',
-        },
-      },
-      required: ['projectId'],
-    },
-  },
-];