cotx-engine 0.1.0

package/dist/mcp/tools.d.ts

@@ -0,0 +1,37 @@
+/**
+ * MCP Tool Definitions and Handlers
+ *
+ * Defines the MCP tools cotx-engine exposes to AI agents.
+ * The current surface includes compile/query/context/impact plus map, write,
+ * batch_write, enrich, lint, and diff.
+ */
+type McpContent = {
+    type: 'text';
+    text: string;
+};
+type McpResult = {
+    content: McpContent[];
+    isError?: boolean;
+};
+export declare function handleToolCall(name: string, args: Record<string, unknown>): Promise<McpResult>;
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: 'object';
+        properties: Record<string, {
+            type: string;
+            description?: string;
+            default?: unknown;
+            items?: {
+                type: string;
+            };
+            enum?: string[];
+            minimum?: number;
+            maximum?: number;
+        }>;
+        required: string[];
+    };
+}
+export declare const COTX_TOOLS: ToolDefinition[];
+export {};

package/dist/mcp/tools.js

@@ -0,0 +1,650 @@
+/**
+ * MCP Tool Definitions and Handlers
+ *
+ * Defines the MCP tools cotx-engine exposes to AI agents.
+ * The current surface includes compile/query/context/impact plus map, write,
+ * batch_write, enrich, lint, and diff.
+ */
+import { commandCompile } from '../commands/compile.js';
+import { commandUpdate } from '../commands/update.js';
+import { commandLint } from '../commands/lint.js';
+import { commandWrite } from '../commands/write.js';
+import { detectStale } from '../compiler/stale-detector.js';
+import { generateMapSummary } from '../commands/map.js';
+import { commandDiff } from '../commands/diff.js';
+import { CotxStore } from '../store/store.js';
+import { CotxGraph } from '../query/graph-index.js';
+function ok(data) {
+    return { content: [{ type: 'text', text: JSON.stringify(data) }] };
+}
+function err(message) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify({ error: message }) }],
+        isError: true,
+    };
+}
+export async function handleToolCall(name, args) {
+    switch (name) {
+        case 'cotx_compile': {
+            const projectRoot = args.project_root;
+            const mode = args.mode ?? 'full';
+            if (mode === 'delta') {
+                const files = args.files;
+                const result = await commandUpdate(projectRoot, files, { silent: true });
+                return ok({ status: 'updated', ...result });
+            }
+            else {
+                await commandCompile(projectRoot, { silent: true });
+                const store = new CotxStore(projectRoot);
+                const meta = store.readMeta();
+                const staleResult = detectStale(store);
+                const staleCount = staleResult.summary.enrichments;
+                return ok({
+                    status: 'compiled',
+                    compiled_at: meta.compiled_at,
+                    stats: meta.stats,
+                    stale_enrichments: staleCount,
+                    hint: staleCount > 0
+                        ? `${staleCount} enrichments stale. Call cotx_enrich to refresh.`
+                        : undefined,
+                });
+            }
+        }
+        case 'cotx_query': {
+            const projectRoot = args.project_root;
+            const keyword = args.query;
+            const layer = args.layer;
+            const store = new CotxStore(projectRoot);
+            if (!store.exists()) {
+                return err('No .cotx/ found. Run cotx_compile first.');
+            }
+            const graph = CotxGraph.fromStoreCached(store);
+            const results = graph.search(keyword, layer, 2.0);
+            const output = results.map((node) => {
+                const data = node.data;
+                const base = { id: node.id, layer: node.layer };
+                if (node.layer === 'module') {
+                    base.canonical_entry = data.canonical_entry;
+                    base.files_count = Array.isArray(data.files) ? data.files.length : 0;
+                }
+                else if (node.layer === 'concept') {
+                    base.appears_in_count = Array.isArray(data.appears_in) ? data.appears_in.length : 0;
+                    base.module = data.layer;
+                }
+                else if (node.layer === 'contract') {
+                    base.consumer = data.consumer;
+                    base.provider = data.provider;
+                    base.interface = data.interface;
+                }
+                else if (node.layer === 'flow') {
+                    base.trigger = data.trigger;
+                    base.steps_count = Array.isArray(data.steps) ? data.steps.length : 0;
+                }
+                else if (node.layer === 'concern') {
+                    base.type = data.type;
+                    base.severity = data.severity;
+                }
+                const edges = graph.neighbors(node.id, 'both');
+                base.relations_count = edges.length;
+                return base;
+            });
+            const capped = output.slice(0, 15);
+            return ok({ query: keyword, layer: layer ?? null, count: capped.length, total_matches: output.length, results: capped });
+        }
+        case 'cotx_context': {
+            const projectRoot = args.project_root;
+            const nodeId = args.node_id;
+            const store = new CotxStore(projectRoot);
+            if (!store.exists()) {
+                return err('No .cotx/ found. Run cotx_compile first.');
+            }
+            const graph = CotxGraph.fromStoreCached(store);
+            const node = graph.findNode(nodeId);
+            if (!node) {
+                return err(`Node "${nodeId}" not found. Try cotx_query to search by keyword.`);
+            }
+            const outEdges = graph.neighbors(node.id, 'out').map((e) => {
+                const target = graph.findNode(e.to);
+                return { to: e.to, layer: target?.layer ?? null, relation: e.relation };
+            });
+            const inEdges = graph.neighbors(node.id, 'in').map((e) => {
+                const source = graph.findNode(e.from);
+                return { from: e.from, layer: source?.layer ?? null, relation: e.relation };
+            });
+            return ok({
+                id: node.id,
+                layer: node.layer,
+                data: node.data,
+                outgoing: outEdges,
+                incoming: inEdges,
+            });
+        }
+        case 'cotx_impact': {
+            const projectRoot = args.project_root;
+            const target = args.target;
+            const direction = args.direction;
+            const store = new CotxStore(projectRoot);
+            if (!store.exists()) {
+                return err('No .cotx/ found. Run cotx_compile first.');
+            }
+            const graph = CotxGraph.fromStoreCached(store);
+            let node = graph.findNode(target);
+            if (!node) {
+                const matches = graph.search(target);
+                if (matches.length === 0) {
+                    return err(`"${target}" not found in map.`);
+                }
+                if (matches.length > 1) {
+                    return ok({
+                        ambiguous: true,
+                        query: target,
+                        matches: matches.slice(0, 10).map((m) => ({ id: m.id, layer: m.layer })),
+                        hint: 'Use an exact node ID to disambiguate.',
+                    });
+                }
+                node = matches[0];
+            }
+            const bfsDirection = (direction === 'downstream' ? 'out' : 'in');
+            const bfsResult = graph.bfs(node.id, bfsDirection, 3);
+            const depths = {};
+            const affectedModules = new Set();
+            const affectedContracts = new Set();
+            const affectedFlows = new Set();
+            const affectedConcerns = new Set();
+            let totalAffected = 0;
+            const depthLabels = {
+                1: 'WILL BREAK',
+                2: 'LIKELY AFFECTED',
+                3: 'MAY NEED TESTING',
+            };
+            for (const [depth, nodeIds] of bfsResult) {
+                const dModules = [];
+                const dConcerns = [];
+                let dFlows = 0;
+                let dContracts = 0;
+                for (const id of nodeIds) {
+                    const n = graph.findNode(id);
+                    if (!n)
+                        continue;
+                    totalAffected++;
+                    if (n.layer === 'module') {
+                        affectedModules.add(id);
+                        dModules.push(id);
+                    }
+                    else if (n.layer === 'flow') {
+                        affectedFlows.add(id);
+                        dFlows++;
+                    }
+                    else if (n.layer === 'contract') {
+                        affectedContracts.add(id);
+                        dContracts++;
+                    }
+                    else if (n.layer === 'concern') {
+                        affectedConcerns.add(id);
+                        dConcerns.push(id);
+                    }
+                }
+                depths[`d${depth}`] = {
+                    label: depthLabels[depth] ?? `d${depth}`,
+                    modules: dModules,
+                    flows_count: dFlows,
+                    contracts_count: dContracts,
+                    concerns: dConcerns,
+                    total: dModules.length + dFlows + dContracts + dConcerns.length,
+                };
+            }
+            const d1Count = bfsResult.get(1)?.length ?? 0;
+            let risk;
+            if (d1Count === 0)
+                risk = 'LOW';
+            else if (d1Count <= 3)
+                risk = 'LOW';
+            else if (d1Count <= 9)
+                risk = 'MEDIUM';
+            else if (affectedConcerns.size > 0)
+                risk = 'CRITICAL';
+            else
+                risk = 'HIGH';
+            return ok({
+                target: { id: node.id, layer: node.layer },
+                direction: direction === 'downstream' ? 'downstream' : 'upstream',
+                depths,
+                summary: {
+                    total_affected: totalAffected,
+                    risk,
+                    affected_modules: [...affectedModules],
+                    affected_contracts_count: affectedContracts.size,
+                    affected_flows_count: affectedFlows.size,
+                    affected_concerns: [...affectedConcerns],
+                },
+            });
+        }
+        case 'cotx_batch_write': {
+            const projectRoot = args.project_root;
+            const writes = args.writes;
+            if (!Array.isArray(writes) || writes.length === 0) {
+                return err('writes must be a non-empty array of {node_id, field, content}');
+            }
+            const results = [];
+            for (const w of writes) {
+                const r = await commandWrite(projectRoot, w.node_id, w.field, w.content, { author: 'agent' });
+                results.push({ node_id: w.node_id, ...r });
+            }
+            const succeeded = results.filter((r) => r.success).length;
+            return ok({ total: writes.length, succeeded, failed: writes.length - succeeded, results });
+        }
+        case 'cotx_write': {
+            const result = await commandWrite(args.project_root, args.node_id, args.field, args.content, { author: 'agent' });
+            return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+        }
+        case 'cotx_map': {
+            const projectRoot = args.project_root;
+            const store = new CotxStore(projectRoot);
+            if (!store.exists()) {
+                return err('No .cotx/ found. Run cotx_compile first.');
+            }
+            const scope = args.scope ?? 'overview';
+            const depth = args.depth ?? 2;
+            const markdown = generateMapSummary(store, scope, depth);
+            return ok(markdown);
+        }
+        case 'cotx_lint': {
+            const projectRoot = args.project_root;
+            const strict = args.strict ?? false;
+            const issues = await commandLint(projectRoot, { json: false, strict, silent: true });
+            return ok({ issues, count: issues.length });
+        }
+        case 'cotx_enrich': {
+            const projectRoot = args.project_root;
+            const store = new CotxStore(projectRoot);
+            if (!store.exists()) {
+                return err('No .cotx/ found. Run cotx_compile first.');
+            }
+            const layer = args.layer ?? 'module';
+            const limit = args.limit ?? 10;
+            const tasks = [];
+            if (layer === 'module' || layer === 'all') {
+                // Build module → exported function names from graph
+                const graph = CotxGraph.fromStoreCached(store);
+                const moduleExports = new Map();
+                for (const node of graph.allNodes('module')) {
+                    const data = node.data;
+                    const files = data.files;
+                    if (!files)
+                        continue;
+                    // Collect exported symbols from contracts (interface functions)
+                    const exports = [];
+                    const outEdges = graph.neighbors(node.id, 'out');
+                    for (const edge of outEdges) {
+                        if (edge.relation === 'contract') {
+                            const contractNode = graph.findNode(edge.to);
+                            if (!contractNode)
+                                continue;
+                            // The edge goes to another module via contract, but we need the contract data
+                        }
+                    }
+                    // Use contracts where this module is provider → interface is its exported API
+                    const inEdges = graph.neighbors(node.id, 'in');
+                    for (const edge of inEdges) {
+                        if (edge.relation === 'contract') {
+                            const cNode = graph.findNode(edge.from);
+                            if (!cNode)
+                                continue;
+                            const cData = cNode.data;
+                            const iface = cData.interface;
+                            if (iface)
+                                exports.push(...iface.slice(0, 5));
+                        }
+                    }
+                    moduleExports.set(node.id, [...new Set(exports)].slice(0, 15));
+                }
+                // Build dep descriptions for richer context
+                const depDescriptions = new Map();
+                for (const id of store.listModules()) {
+                    const mod = store.readModule(id);
+                    const resp = mod.enriched?.responsibility ?? mod.enriched?.auto_description;
+                    if (resp)
+                        depDescriptions.set(id, resp);
+                }
+                for (const id of store.listModules()) {
+                    if (tasks.length >= limit)
+                        break;
+                    const mod = store.readModule(id);
+                    if (mod.enriched?.responsibility && mod.enriched.source_hash === mod.struct_hash)
+                        continue;
+                    const depCtx = mod.depends_on.slice(0, 5).map((d) => {
+                        const desc = depDescriptions.get(d);
+                        return desc ? `${d} (${desc})` : d;
+                    });
+                    tasks.push({
+                        node_id: id,
+                        layer: 'module',
+                        field: 'enriched.responsibility',
+                        context: {
+                            files_count: mod.files.length,
+                            files_sample: mod.files.slice(0, 8),
+                            canonical_entry: mod.canonical_entry,
+                            exported_api: moduleExports.get(id) ?? [],
+                            depends_on_with_desc: depCtx,
+                            depended_by: mod.depended_by.slice(0, 5),
+                            auto_description: mod.enriched?.auto_description ?? null,
+                        },
+                        instruction: 'Write a one-sentence description of this module\'s responsibility. You have: file names, entry point, exported API functions, and dependency descriptions. Write a human-quality sentence, not a keyword list. Use cotx_write with field "enriched.responsibility".',
+                    });
+                }
+            }
+            if (layer === 'concept' || layer === 'all') {
+                for (const id of store.listConcepts()) {
+                    if (tasks.length >= limit)
+                        break;
+                    const concept = store.readConcept(id);
+                    if (concept.enriched?.definition && concept.enriched.source_hash === concept.struct_hash)
+                        continue;
+                    tasks.push({
+                        node_id: id,
+                        layer: 'concept',
+                        field: 'enriched.definition',
+                        context: {
+                            aliases: concept.aliases,
+                            appears_in_count: concept.appears_in.length,
+                            appears_in_sample: concept.appears_in.slice(0, 5),
+                            home_module: concept.layer,
+                        },
+                        instruction: 'Write a one-sentence definition of this domain concept. Use cotx_write with field "enriched.definition".',
+                    });
+                }
+            }
+            if (layer === 'contract' || layer === 'all') {
+                for (const id of store.listContracts()) {
+                    if (tasks.length >= limit)
+                        break;
+                    const contract = store.readContract(id);
+                    if (contract.enriched?.guarantees && contract.enriched.source_hash === contract.struct_hash)
+                        continue;
+                    tasks.push({
+                        node_id: id,
+                        layer: 'contract',
+                        field: 'enriched.guarantees',
+                        context: {
+                            provider: contract.provider,
+                            consumer: contract.consumer,
+                            interface_sample: contract.interface.slice(0, 10),
+                        },
+                        instruction: 'Describe what this contract guarantees: what the consumer can rely on from the provider. Use cotx_write with field "enriched.guarantees" and a JSON array of strings.',
+                    });
+                }
+            }
+            if (layer === 'flow' || layer === 'all') {
+                for (const id of store.listFlows()) {
+                    if (tasks.length >= limit)
+                        break;
+                    const flow = store.readFlow(id);
+                    if (flow.enriched?.error_paths && flow.enriched.source_hash === flow.struct_hash)
+                        continue;
+                    if (flow.type !== 'flow' || !flow.steps || flow.steps.length === 0)
+                        continue;
+                    tasks.push({
+                        node_id: id,
+                        layer: 'flow',
+                        field: 'enriched.error_paths',
+                        context: {
+                            trigger: flow.trigger,
+                            steps_count: flow.steps.length,
+                            steps_sample: flow.steps.slice(0, 5).map((s) => `${s.module}.${s.function}`),
+                        },
+                        instruction: 'Describe what happens when steps in this flow fail. Use cotx_write with field "enriched.error_paths" and a JSON array of {condition, behavior} objects.',
+                    });
+                }
+            }
+            return ok({
+                tasks,
+                total: tasks.length,
+                hint: 'For each task, generate a one-sentence description from the context, then call cotx_batch_write with all results.',
+                delegation: tasks.length > 5
+                    ? 'These are independent, simple text generation tasks (~300 tokens each). If you have sub-agent capability, delegate to a lightweight model (e.g. haiku) for cost efficiency.'
+                    : undefined,
+            });
+        }
+        case 'cotx_diff': {
+            const result = await commandDiff(args.project_root, {
+                snapshot: args.snapshot,
+                silent: true,
+            });
+            return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+        }
+        default:
+            return ok({ status: 'not_implemented', tool: name });
+    }
+}
+export const COTX_TOOLS = [
+    {
+        name: 'cotx_compile',
+        description: 'Compile codebase into semantic map. Returns stale_enrichments count — if > 0, call cotx_enrich to get enrichment tasks, generate descriptions with your LLM, then cotx_batch_write to save them.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project_root: {
+                    type: 'string',
+                    description: 'Absolute path to project root',
+                },
+                mode: {
+                    type: 'string',
+                    enum: ['full', 'delta'],
+                    default: 'full',
+                    description: 'Compilation mode',
+                },
+                files: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Files to update (delta mode only)',
+                },
+            },
+            required: ['project_root'],
+        },
+    },
+    {
+        name: 'cotx_query',
+        description: 'Search map nodes by keyword across all semantic layers',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project_root: {
+                    type: 'string',
+                    description: 'Absolute path to project root',
+                },
+                query: {
+                    type: 'string',
+                    description: 'Search keyword or phrase',
+                },
+                layer: {
+                    type: 'string',
+                    enum: ['module', 'concept', 'contract', 'flow', 'concern'],
+                    description: 'Filter by layer',
+                },
+            },
+            required: ['project_root', 'query'],
+        },
+    },
+    {
+        name: 'cotx_context',
+        description: '360° view of a map node: details, dependencies, flows, concerns, annotations',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project_root: {
+                    type: 'string',
+                    description: 'Absolute path to project root',
+                },
+                node_id: {
+                    type: 'string',
+                    description: 'Node ID to inspect',
+                },
+            },
+            required: ['project_root', 'node_id'],
+        },
+    },
+    {
+        name: 'cotx_impact',
+        description: 'Blast radius analysis: what breaks if you change a node',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project_root: {
+                    type: 'string',
+                    description: 'Absolute path to project root',
+                },
+                target: {
+                    type: 'string',
+                    description: 'Node ID or keyword to analyze',
+                },
+                direction: {
+                    type: 'string',
+                    enum: ['upstream', 'downstream'],
+                    default: 'upstream',
+                    description: 'Impact direction',
+                },
+            },
+            required: ['project_root', 'target'],
+        },
+    },
+    {
+        name: 'cotx_map',
+        description: 'Generate prompt-friendly map summary in markdown',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project_root: {
+                    type: 'string',
+                    description: 'Absolute path to project root',
+                },
+                scope: {
+                    type: 'string',
+                    default: 'overview',
+                    description: 'overview, module:<id>, or flow:<id>',
+                },
+                depth: {
+                    type: 'number',
+                    minimum: 1,
+                    maximum: 3,
+                    default: 2,
+                    description: 'Detail level (1=minimal, 3=detailed)',
+                },
+            },
+            required: ['project_root'],
+        },
+    },
+    {
+        name: 'cotx_batch_write',
+        description: 'Write enrichments for multiple nodes in a single call. Use after cotx_enrich to write all generated descriptions at once.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project_root: {
+                    type: 'string',
+                    description: 'Absolute path to project root',
+                },
+                writes: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'JSON array of {node_id, field, content} objects',
+                },
+            },
+            required: ['project_root', 'writes'],
+        },
+    },
+    {
+        name: 'cotx_write',
+        description: 'Write to enriched or annotation zone of a map node',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project_root: {
+                    type: 'string',
+                    description: 'Absolute path to project root',
+                },
+                node_id: {
+                    type: 'string',
+                    description: 'Node ID to write to',
+                },
+                field: {
+                    type: 'string',
+                    description: 'Field path (e.g., enriched.responsibility or annotation.constraint)',
+                },
+                content: {
+                    type: 'string',
+                    description: 'Content to write',
+                },
+            },
+            required: ['project_root', 'node_id', 'field', 'content'],
+        },
+    },
+    {
+        name: 'cotx_lint',
+        description: 'Check map ↔ code consistency, report stale enrichments and broken references',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project_root: {
+                    type: 'string',
+                    description: 'Absolute path to project root',
+                },
+                scope: {
+                    type: 'string',
+                    description: 'Scope to lint (module ID or empty for all)',
+                },
+                strict: {
+                    type: 'boolean',
+                    default: false,
+                    description: 'Exit with error on any issue',
+                },
+            },
+            required: ['project_root'],
+        },
+    },
+    {
+        name: 'cotx_enrich',
+        description: 'Get stale/unenriched nodes with context for LLM enrichment. For each task: read the context (files, API, dependencies), write a one-sentence description, then call cotx_batch_write with all results. Only returns nodes that changed since last enrichment (incremental).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project_root: {
+                    type: 'string',
+                    description: 'Absolute path to project root',
+                },
+                layer: {
+                    type: 'string',
+                    enum: ['module', 'concept', 'contract', 'flow', 'all'],
+                    default: 'module',
+                    description: 'Which layer to enrich (module, concept, or all)',
+                },
+                limit: {
+                    type: 'number',
+                    minimum: 1,
+                    maximum: 50,
+                    default: 10,
+                    description: 'Max number of enrichment tasks to return',
+                },
+            },
+            required: ['project_root'],
+        },
+    },
+    {
+        name: 'cotx_diff',
+        description: 'Semantic diff between two versions of the map',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project_root: {
+                    type: 'string',
+                    description: 'Absolute path to project root',
+                },
+                snapshot: {
+                    type: 'string',
+                    description: 'Snapshot tag to compare against',
+                },
+            },
+            required: ['project_root'],
+        },
+    },
+];
+//# sourceMappingURL=tools.js.map