@ezmodo/mcp-server 0.13.0

package/tools/components.js

@@ -0,0 +1,249 @@
+/**
+ * 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'],
+    },
+  },
+];

package/tools/context-manifest.js

@@ -0,0 +1,236 @@
+/**
+ * Context Manifest Tools
+ * MCP tools for querying the project's context manifest — a structured index
+ * of all files, their roles, dependencies, and AI-useful summaries.
+ *
+ * `get_context` is the unified query tool replacing search_project_context,
+ * get_related_files, get_project_overview, get_critical_files,
+ * query_project_graph, analyze_impact, get_graph_stats, and
+ * analyze_project_organization.
+ */
+
+export const CONTEXT_MANIFEST_TOOLS = [
+  {
+    name: 'get_context',
+    description:
+      'Get contextual information about any entity (project, task, epic, component, file, tag). ' +
+      'Replaces search_project_context, get_related_files, get_project_overview, get_critical_files, ' +
+      'query_project_graph, analyze_impact, get_graph_stats, analyze_project_organization. ' +
+      'Use `query` for keyword search, or `entityType` + `entityId` for entity-specific context. ' +
+      'Control what\'s returned via `include` array.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        projectId: {
+          type: 'string',
+          description: 'Project ID (required)',
+        },
+        entityType: {
+          type: 'string',
+          enum: ['project', 'task', 'epic', 'component', 'file', 'tag'],
+          description: 'Type of entity to get context for',
+        },
+        entityId: {
+          type: 'string',
+          description:
+            'Entity ID or file path (required when entityType is not project)',
+        },
+        query: {
+          type: 'string',
+          description:
+            'Search query for keyword-based context search (alternative to entityType+entityId)',
+        },
+        include: {
+          type: 'array',
+          items: {
+            type: 'string',
+            enum: [
+              'graph',
+              'files',
+              'dependencies',
+              'impact',
+              'overview',
+              'critical_files',
+              'graph_stats',
+              'organization',
+            ],
+          },
+          description:
+            'What to include in response. Defaults to all relevant sections for the entityType.',
+        },
+        queryType: {
+          type: 'string',
+          enum: ['context', 'impact', 'feature', 'task_context', 'connection'],
+          description: 'Graph query type (when include contains "graph")',
+        },
+        depth: {
+          type: 'number',
+          description: 'Graph traversal depth (default: 2)',
+        },
+        format: {
+          type: 'string',
+          enum: ['compact', 'detailed', 'structured'],
+          description: 'Output format for file context',
+        },
+        limit: {
+          type: 'number',
+          description: 'Max results for search queries',
+        },
+        tags: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Filter by tags (for context search)',
+        },
+        direction: {
+          type: 'string',
+          enum: ['forward', 'reverse', 'both'],
+          description: 'Dependency traversal direction (for file context)',
+        },
+      },
+      required: ['projectId'],
+    },
+  },
+  {
+    name: 'rebuild_manifest',
+    description:
+      'Trigger regeneration of the project context manifest. ' +
+      '"incremental" re-analyzes only files changed since last generation (fast). ' +
+      '"full" regenerates everything with static analysis.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        mode: {
+          type: 'string',
+          enum: ['incremental', 'full'],
+          description:
+            'Regeneration mode. "incremental" = git diff-based (fast). ' +
+            '"full" = re-analyze all files (slower). Default: "incremental"',
+          default: 'incremental',
+        },
+        target_paths: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Limit regeneration to specific paths or directories (optional)',
+        },
+      },
+    },
+  },
+  {
+    name: 'update_manifest_entries',
+    description:
+      'Write AI-enriched summaries back to the context manifest. ' +
+      'After reading critical files and generating better summaries, ' +
+      'use this tool to persist them. Marks entries as LLM-enriched ' +
+      'and saves to disk.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        project_id: {
+          type: 'string',
+          description:
+            'Project ID for remote manifest access. Required when no local manifest is available.',
+        },
+        updates: {
+          type: 'array',
+          description: 'Array of entries to update with enriched summaries',
+          items: {
+            type: 'object',
+            properties: {
+              path: {
+                type: 'string',
+                description: 'File path relative to project root',
+              },
+              summary: {
+                type: 'string',
+                description:
+                  'New AI-enriched summary. Should capture intent, ' +
+                  'key behaviors, integrations, and gotchas. ' +
+                  'Keep under 200 words.',
+              },
+              criticality_score: {
+                type: 'number',
+                description: 'Criticality score 0-1 (optional)',
+              },
+              criticality_signals: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'Criticality signals (optional)',
+              },
+            },
+            required: ['path', 'summary'],
+          },
+        },
+      },
+      required: ['updates'],
+    },
+  },
+  {
+    name: 'get_manifest_schema',
+    description:
+      'Get the full context manifest JSON schema with documentation and examples. ' +
+      'Use this when you need to generate a manifest for a language or project that ' +
+      'the built-in generator doesn\'t support. The schema includes field descriptions, ' +
+      'valid enum values, example entries, and a reusable prompt template for AI agents. ' +
+      'Supported natively: TypeScript/JavaScript, Go, Python, Rust, Java, Kotlin, Dart, ' +
+      'C#, Swift, PHP, Ruby, C/C++. For any other language, use this schema to generate ' +
+      'a valid manifest yourself.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        includeExamples: {
+          type: 'boolean',
+          description: 'Include annotated example entries for common patterns (default: true)',
+          default: true,
+        },
+        language: {
+          type: 'string',
+          description:
+            'If provided, tailor examples to this language (e.g., "scala", "elixir", "haskell"). ' +
+            'The schema itself is language-agnostic — this only affects examples.',
+        },
+      },
+    },
+  },
+  {
+    name: 'resolve_concepts',
+    description:
+      'Resolve user-facing product terms to code locations. Use this when a user ' +
+      'refers to a feature by its product name (e.g., "dashboard", "board", "settings") ' +
+      'and you need to find the corresponding code files. Returns matching concept aliases ' +
+      'from the manifest, plus get_context results for broader matching.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        projectId: {
+          type: 'string',
+          description: 'Project ID (required)',
+        },
+        terms: {
+          type: 'array',
+          items: { type: 'string' },
+          description:
+            'User-facing terms to resolve (e.g., ["dashboard", "tour", "sprint board"])',
+        },
+      },
+      required: ['projectId', 'terms'],
+    },
+  },
+  {
+    name: 'validate_manifest',
+    description:
+      'Validate a manifest JSON against the schema. Returns errors and warnings. ' +
+      'Use this after generating a manifest to check it before uploading. ' +
+      'Checks: required fields, valid enum values, dependency paths exist in manifest, ' +
+      'entry count matches metadata, and common issues.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        manifest: {
+          type: 'object',
+          description: 'The full ContextManifest JSON object to validate',
+        },
+      },
+      required: ['manifest'],
+    },
+  },
+];

package/tools/decisions.js

@@ -0,0 +1,168 @@
+/**
+ * Decision Tools
+ * MCP tools for Decisions / ADRs (E-170).
+ *
+ * A Decision is a durable, org-level ADR-style record of a choice and its
+ * rationale (title, context, options, decision, consequences, status). Decisions
+ * live on the capability/knowledge axis: they LINK to features, epics, tasks,
+ * milestones, and other artifacts via the generic link graph — they do not own
+ * them.
+ *
+ * Decisions capture "why we built it this way" so the rationale survives the work
+ * that produced it. A task's decision-type knowledge item can be elevated into a
+ * durable Decision via promote_from_knowledge.
+ */
+
+import { LINKABLE_TYPES } from './linkable-types.js';
+import { LINKS_ARRAY_SCHEMA } from './link-params.js';
+
+export const DECISION_TOOLS = [
+  {
+    name: 'manage_decision',
+    description: 'Create, update, or delete a Decision (a durable ADR-style record: title, context, ' +
+      'options, decision, consequences, status), link/unlink it to existing artifacts, mark it ' +
+      'superseded by another decision, or promote a task\'s decision-type knowledge item into a ' +
+      'durable Decision. Decisions are org-level and LINK to features/epics/tasks/milestones/etc., ' +
+      'they do not contain them.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        action: {
+          type: 'string',
+          enum: ['create', 'update', 'delete', 'link', 'unlink', 'supersede', 'promote_from_knowledge'],
+          description: 'Action to perform. "supersede" marks a decision as superseded by another ' +
+            '(pass decisionId + supersededById). "promote_from_knowledge" elevates a task\'s ' +
+            'decision-type knowledge item into a durable Decision (pass organizationId + taskId + ' +
+            'knowledgeId, optionally title + linkToType/linkToId to link it on creation).',
+        },
+        // --- Identifiers ---
+        organizationId: {
+          type: 'string',
+          description: 'Organization ID (required for create and promote_from_knowledge)',
+        },
+        decisionId: {
+          type: 'string',
+          description: 'Decision ID (required for update, delete, link, unlink, supersede)',
+        },
+        supersededById: {
+          type: 'string',
+          description: 'ID of the decision that supersedes this one (required for supersede)',
+        },
+        // --- Create / update fields ---
+        title: {
+          type: 'string',
+          description: 'Decision title (required for create), e.g. "Use PostgreSQL over Firestore". ' +
+            'Optional for promote_from_knowledge (defaults from the knowledge item).',
+        },
+        context: {
+          type: 'string',
+          description: 'The situation / forces that motivated the decision, supports markdown ' +
+            '(create, update)',
+        },
+        options: {
+          type: 'string',
+          description: 'The options considered, supports markdown (create, update)',
+        },
+        decision: {
+          type: 'string',
+          description: 'The decision that was made, supports markdown (create, update)',
+        },
+        consequences: {
+          type: 'string',
+          description: 'The resulting consequences / trade-offs, supports markdown (create, update)',
+        },
+        status: {
+          type: 'string',
+          enum: ['proposed', 'accepted', 'rejected', 'superseded', 'deprecated'],
+          description: 'Decision lifecycle status (default: "proposed") (create, update)',
+        },
+        projectId: {
+          type: 'string',
+          description: 'Scope the decision to a project. Omit/empty = cross-project / org-wide ' +
+            '(create, update)',
+        },
+        // --- link / unlink fields ---
+        targetType: {
+          type: 'string',
+          enum: LINKABLE_TYPES,
+          description: 'Type of artifact to link/unlink (required for link, unlink)',
+        },
+        targetId: {
+          type: 'string',
+          description: 'ID of the artifact to link/unlink (required for link, unlink)',
+        },
+        links: LINKS_ARRAY_SCHEMA,
+        // --- promote_from_knowledge fields ---
+        taskId: {
+          type: 'string',
+          description: 'Task whose knowledge item to promote (required for promote_from_knowledge)',
+        },
+        knowledgeId: {
+          type: 'string',
+          description: 'ID of the decision-type knowledge item to promote ' +
+            '(required for promote_from_knowledge)',
+        },
+        linkToType: {
+          type: 'string',
+          enum: LINKABLE_TYPES,
+          description: 'Optionally link the new decision to this artifact type on creation ' +
+            '(create, promote_from_knowledge)',
+        },
+        linkToId: {
+          type: 'string',
+          description: 'ID of the artifact to link the new decision to on creation ' +
+            '(create, promote_from_knowledge; requires linkToType)',
+        },
+      },
+      required: ['action'],
+    },
+  },
+  {
+    name: 'get_decision',
+    description: 'Retrieve a single Decision, list an organization\'s decisions, or list the decisions ' +
+      'linked to a given entity (e.g. all decisions on a feature). Provide decisionId for a single ' +
+      'lookup; provide linkedType + linkedId to list decisions linked to that entity; otherwise ' +
+      'provide organizationId to list.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        decisionId: {
+          type: 'string',
+          description: 'Decision ID for a single lookup',
+        },
+        organizationId: {
+          type: 'string',
+          description: 'Organization ID (required for list, unless using linkedType + linkedId)',
+        },
+        linkedType: {
+          type: 'string',
+          enum: LINKABLE_TYPES,
+          description: 'List decisions linked to this entity type (requires linkedId), ' +
+            'e.g. all decisions on a feature',
+        },
+        linkedId: {
+          type: 'string',
+          description: 'ID of the entity to list linked decisions for (requires linkedType)',
+        },
+        includeLinks: {
+          type: 'boolean',
+          description: 'If true (single lookup), also return the decision\'s linked artifacts',
+        },
+        // --- List filters ---
+        projectId: {
+          type: 'string',
+          description: 'Filter to a single project\'s decisions (list mode)',
+        },
+        status: {
+          type: 'string',
+          enum: ['proposed', 'accepted', 'rejected', 'superseded', 'deprecated'],
+          description: 'Filter by status (list mode)',
+        },
+        limit: {
+          type: 'number',
+          description: 'Maximum number of results (list mode)',
+        },
+      },
+    },
+  },
+];