@opensip-cli/mcp 0.1.15

package/dist/tools/find-dead-code.js

@@ -0,0 +1,26 @@
+/**
+ * `find_dead_code` — orphan (unreachable) symbols (ADR-0084, Task 4.3).
+ *
+ * Delegates to `graphPort.deadCode()`, backed by graph's `orphan-subtree` rule
+ * (reachability from entry points) — NOT ad-hoc filesystem reachability. Returns
+ * the `{ data, freshness, truncated? }` envelope; `limit` caps the result.
+ */
+import { limit as limitSchema } from './schemas.js';
+import { errorResult, jsonResult } from './tool-result.js';
+export function registerFindDeadCode(server, deps) {
+    server.register('find_dead_code', {
+        title: 'Find dead code',
+        description: 'List symbols unreachable from any entry point (the graph orphan-subtree rule). Each ' +
+            'finding carries its symbolId + a reason. Reads the catalog only — no filesystem walk. ' +
+            'Use `limit` to cap results.',
+        inputSchema: {
+            limit: limitSchema(),
+        },
+    }, ({ limit }) => {
+        const outcome = deps.graph.deadCode(limit);
+        if (!outcome.ok)
+            return errorResult(outcome.error);
+        return jsonResult(outcome.value);
+    });
+}
+//# sourceMappingURL=find-dead-code.js.map

package/dist/tools/find-dead-code.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"find-dead-code.js","sourceRoot":"","sources":["../../src/tools/find-dead-code.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,KAAK,IAAI,WAAW,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAK3D,MAAM,UAAU,oBAAoB,CAAC,MAAsB,EAAE,IAAiB;IAC5E,MAAM,CAAC,QAAQ,CACb,gBAAgB,EAChB;QACE,KAAK,EAAE,gBAAgB;QACvB,WAAW,EACT,sFAAsF;YACtF,wFAAwF;YACxF,6BAA6B;QAC/B,WAAW,EAAE;YACX,KAAK,EAAE,WAAW,EAAE;SACrB;KACF,EACD,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE;QACZ,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;QAC3C,IAAI,CAAC,OAAO,CAAC,EAAE;YAAE,OAAO,WAAW,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QACnD,OAAO,UAAU,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IACnC,CAAC,CACF,CAAC;AACJ,CAAC"}

package/dist/tools/get-agent-catalog.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `get_agent_catalog` — the self-describing OpenSIP command catalog (ADR-0084,
+ * Task 4.5).
+ *
+ * Reads `resultsPort.agentCatalog()` ONLY — never invokes a tool. Highlights the
+ * result-first workflow: an agent inspects existing findings (get_latest_findings,
+ * show_run, list_runs) before re-running anything.
+ */
+import type { McpToolDeps } from './types.js';
+import type { McpStdioServer } from '../server.js';
+export declare function registerGetAgentCatalog(server: McpStdioServer, deps: McpToolDeps): void;
+//# sourceMappingURL=get-agent-catalog.d.ts.map

package/dist/tools/get-agent-catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-agent-catalog.d.ts","sourceRoot":"","sources":["../../src/tools/get-agent-catalog.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEnD,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,cAAc,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CAgBvF"}

package/dist/tools/get-agent-catalog.js

@@ -0,0 +1,23 @@
+/**
+ * `get_agent_catalog` — the self-describing OpenSIP command catalog (ADR-0084,
+ * Task 4.5).
+ *
+ * Reads `resultsPort.agentCatalog()` ONLY — never invokes a tool. Highlights the
+ * result-first workflow: an agent inspects existing findings (get_latest_findings,
+ * show_run, list_runs) before re-running anything.
+ */
+import { errorResult, jsonResult } from './tool-result.js';
+export function registerGetAgentCatalog(server, deps) {
+    server.register('get_agent_catalog', {
+        title: 'OpenSIP agent command catalog',
+        description: 'The self-describing catalog of OpenSIP commands an agent can run. Prefer the result ' +
+            'tools (get_latest_findings, show_run, list_runs) to inspect EXISTING findings before ' +
+            're-running any tool — re-running is expensive and usually unnecessary.',
+    }, () => {
+        const outcome = deps.results.agentCatalog();
+        if (!outcome.ok)
+            return errorResult(outcome.error);
+        return jsonResult(outcome.value);
+    });
+}
+//# sourceMappingURL=get-agent-catalog.js.map

package/dist/tools/get-agent-catalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-agent-catalog.js","sourceRoot":"","sources":["../../src/tools/get-agent-catalog.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAK3D,MAAM,UAAU,uBAAuB,CAAC,MAAsB,EAAE,IAAiB;IAC/E,MAAM,CAAC,QAAQ,CACb,mBAAmB,EACnB;QACE,KAAK,EAAE,+BAA+B;QACtC,WAAW,EACT,sFAAsF;YACtF,uFAAuF;YACvF,wEAAwE;KAC3E,EACD,GAAG,EAAE;QACH,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,YAAY,EAAE,CAAC;QAC5C,IAAI,CAAC,OAAO,CAAC,EAAE;YAAE,OAAO,WAAW,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QACnD,OAAO,UAAU,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IACnC,CAAC,CACF,CAAC;AACJ,CAAC"}

package/dist/tools/get-architecture.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `get_architecture` — compact codebase overview (ADR-0084, Task 4.3).
+ *
+ * Delegates to `graphPort.architectureSummary()`: function/edge counts,
+ * languages, the top-coupled packages, and the highest-blast hotspots (graph's
+ * canonical scoring). Capped via `limit`; carries `{ freshness }`.
+ */
+import type { McpToolDeps } from './types.js';
+import type { McpStdioServer } from '../server.js';
+export declare function registerGetArchitecture(server: McpStdioServer, deps: McpToolDeps): void;
+//# sourceMappingURL=get-architecture.d.ts.map

package/dist/tools/get-architecture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-architecture.d.ts","sourceRoot":"","sources":["../../src/tools/get-architecture.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEnD,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,cAAc,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CAmBvF"}

package/dist/tools/get-architecture.js

@@ -0,0 +1,26 @@
+/**
+ * `get_architecture` — compact codebase overview (ADR-0084, Task 4.3).
+ *
+ * Delegates to `graphPort.architectureSummary()`: function/edge counts,
+ * languages, the top-coupled packages, and the highest-blast hotspots (graph's
+ * canonical scoring). Capped via `limit`; carries `{ freshness }`.
+ */
+import { limit as limitSchema } from './schemas.js';
+import { errorResult, jsonResult } from './tool-result.js';
+export function registerGetArchitecture(server, deps) {
+    server.register('get_architecture', {
+        title: 'Architecture overview',
+        description: 'High-level shape of the codebase: function/edge counts, languages, the most-coupled ' +
+            'packages, and the highest blast-radius hotspots. A cheap first call to orient before ' +
+            'drilling in with who_calls/blast_radius. Use `limit` to cap rows.',
+        inputSchema: {
+            limit: limitSchema(),
+        },
+    }, ({ limit }) => {
+        const outcome = deps.graph.architectureSummary(limit);
+        if (!outcome.ok)
+            return errorResult(outcome.error);
+        return jsonResult(outcome.value);
+    });
+}
+//# sourceMappingURL=get-architecture.js.map

package/dist/tools/get-architecture.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-architecture.js","sourceRoot":"","sources":["../../src/tools/get-architecture.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,KAAK,IAAI,WAAW,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAK3D,MAAM,UAAU,uBAAuB,CAAC,MAAsB,EAAE,IAAiB;IAC/E,MAAM,CAAC,QAAQ,CACb,kBAAkB,EAClB;QACE,KAAK,EAAE,uBAAuB;QAC9B,WAAW,EACT,sFAAsF;YACtF,uFAAuF;YACvF,mEAAmE;QACrE,WAAW,EAAE;YACX,KAAK,EAAE,WAAW,EAAE;SACrB;KACF,EACD,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE;QACZ,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,mBAAmB,CAAC,KAAK,CAAC,CAAC;QACtD,IAAI,CAAC,OAAO,CAAC,EAAE;YAAE,OAAO,WAAW,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QACnD,OAAO,UAAU,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IACnC,CAAC,CACF,CAAC;AACJ,CAAC"}

package/dist/tools/get-latest-findings.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `get_latest_findings` — the behavior-critical, result-first tool (ADR-0084,
+ * Task 4.5).
+ *
+ * Reads `resultsPort.latestFindings()` ONLY — replays the most recent stored run
+ * for `tool`, severity/limit-filtered. Its description STEERS agents here before
+ * re-running OpenSIP (the verbatim instruction below is a product contract).
+ * Validates `tool` against the live registry → structured unknown-tool error.
+ */
+import type { McpToolDeps } from './types.js';
+import type { McpStdioServer } from '../server.js';
+export declare function registerGetLatestFindings(server: McpStdioServer, deps: McpToolDeps): void;
+//# sourceMappingURL=get-latest-findings.d.ts.map

package/dist/tools/get-latest-findings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-latest-findings.d.ts","sourceRoot":"","sources":["../../src/tools/get-latest-findings.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AASH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEnD,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,cAAc,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CA4BzF"}

package/dist/tools/get-latest-findings.js

@@ -0,0 +1,38 @@
+/**
+ * `get_latest_findings` — the behavior-critical, result-first tool (ADR-0084,
+ * Task 4.5).
+ *
+ * Reads `resultsPort.latestFindings()` ONLY — replays the most recent stored run
+ * for `tool`, severity/limit-filtered. Its description STEERS agents here before
+ * re-running OpenSIP (the verbatim instruction below is a product contract).
+ * Validates `tool` against the live registry → structured unknown-tool error.
+ */
+import { limit as limitSchema, severity as severitySchema, toolId as toolIdSchema, } from './schemas.js';
+import { errorResult, jsonResult, unknownToolError } from './tool-result.js';
+export function registerGetLatestFindings(server, deps) {
+    server.register('get_latest_findings', {
+        title: 'Latest findings for a tool',
+        description: 'Get the findings from the most recent OpenSIP run of a tool (fit, graph, yagni, sim). ' +
+            'Use this before re-running OpenSIP when the user mentions existing fit, graph, yagni, ' +
+            'sim, errors, warnings, findings, or prior results. Filter by `severity` ' +
+            '(errors/warnings/all) and cap with `limit`. Replays the persisted session; never ' +
+            're-runs the tool.',
+        inputSchema: {
+            tool: toolIdSchema(),
+            severity: severitySchema(),
+            limit: limitSchema(),
+        },
+    }, async ({ tool, severity, limit }) => {
+        if (!deps.validToolIds.has(tool))
+            return unknownToolError(tool, deps.validToolIds);
+        const outcome = await deps.results.latestFindings({
+            tool,
+            ...(severity === undefined ? {} : { severity }),
+            ...(limit === undefined ? {} : { limit }),
+        });
+        if (!outcome.ok)
+            return errorResult(outcome.error);
+        return jsonResult(outcome.value);
+    });
+}
+//# sourceMappingURL=get-latest-findings.js.map

package/dist/tools/get-latest-findings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-latest-findings.js","sourceRoot":"","sources":["../../src/tools/get-latest-findings.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EACL,KAAK,IAAI,WAAW,EACpB,QAAQ,IAAI,cAAc,EAC1B,MAAM,IAAI,YAAY,GACvB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAK7E,MAAM,UAAU,yBAAyB,CAAC,MAAsB,EAAE,IAAiB;IACjF,MAAM,CAAC,QAAQ,CACb,qBAAqB,EACrB;QACE,KAAK,EAAE,4BAA4B;QACnC,WAAW,EACT,wFAAwF;YACxF,wFAAwF;YACxF,0EAA0E;YAC1E,mFAAmF;YACnF,mBAAmB;QACrB,WAAW,EAAE;YACX,IAAI,EAAE,YAAY,EAAE;YACpB,QAAQ,EAAE,cAAc,EAAE;YAC1B,KAAK,EAAE,WAAW,EAAE;SACrB;KACF,EACD,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,EAAE,EAAE;QAClC,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,OAAO,gBAAgB,CAAC,IAAI,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC;QACnF,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,cAAc,CAAC;YAChD,IAAI;YACJ,GAAG,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC;YAC/C,GAAG,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC;SAC1C,CAAC,CAAC;QACH,IAAI,CAAC,OAAO,CAAC,EAAE;YAAE,OAAO,WAAW,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QACnD,OAAO,UAAU,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IACnC,CAAC,CACF,CAAC;AACJ,CAAC"}

package/dist/tools/get-symbol.d.ts

@@ -0,0 +1,18 @@
+/**
+ * `get_symbol` — resolve a symbol by file + line (ADR-0084, Task 4.1).
+ *
+ * Span-containment: every occurrence whose `[line, endLine]` span encloses the
+ * requested line. The result is deterministic and NEVER a silent pick:
+ *   - exactly one  → `{ data: SymbolRef, freshness }`
+ *   - more than one → `{ ambiguous: true, candidates: SymbolRef[], freshness }`
+ *     (the agent disambiguates by picking a `symbolId`)
+ *   - none          → a structured `symbol-not-found` error
+ *
+ * Each `SymbolRef` carries the stable `symbolId` + `bodyHash`. Reads only
+ * `graphPort` (no filesystem read — the `file` arg is matched against the
+ * catalog's project-relative paths).
+ */
+import type { McpToolDeps } from './types.js';
+import type { McpStdioServer } from '../server.js';
+export declare function registerGetSymbol(server: McpStdioServer, deps: McpToolDeps): void;
+//# sourceMappingURL=get-symbol.d.ts.map

package/dist/tools/get-symbol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-symbol.d.ts","sourceRoot":"","sources":["../../src/tools/get-symbol.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAKH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEnD,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,cAAc,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CAgCjF"}

package/dist/tools/get-symbol.js

@@ -0,0 +1,44 @@
+/**
+ * `get_symbol` — resolve a symbol by file + line (ADR-0084, Task 4.1).
+ *
+ * Span-containment: every occurrence whose `[line, endLine]` span encloses the
+ * requested line. The result is deterministic and NEVER a silent pick:
+ *   - exactly one  → `{ data: SymbolRef, freshness }`
+ *   - more than one → `{ ambiguous: true, candidates: SymbolRef[], freshness }`
+ *     (the agent disambiguates by picking a `symbolId`)
+ *   - none          → a structured `symbol-not-found` error
+ *
+ * Each `SymbolRef` carries the stable `symbolId` + `bodyHash`. Reads only
+ * `graphPort` (no filesystem read — the `file` arg is matched against the
+ * catalog's project-relative paths).
+ */
+import { filePath as filePathSchema, line as lineSchema } from './schemas.js';
+import { errorResult, failure, jsonResult } from './tool-result.js';
+export function registerGetSymbol(server, deps) {
+    server.register('get_symbol', {
+        title: 'Get symbol by location',
+        description: 'Resolve the function/method declared at a project-relative file + line into a stable ' +
+            'symbolId ("<filePath>:<line>:<column>") + bodyHash. On ambiguity (nested declarations ' +
+            'enclosing the line) returns a candidate list — never a silent pick. Use the returned ' +
+            'symbolId with who_calls, callees_of, blast_radius, or trace_path.',
+        inputSchema: {
+            file: filePathSchema(),
+            line: lineSchema(),
+        },
+    }, ({ file, line }) => {
+        const outcome = deps.graph.findBySpan(file, line);
+        if (!outcome.ok)
+            return errorResult(outcome.error);
+        const { data: candidates, freshness } = outcome.value;
+        if (candidates.length === 0) {
+            return failure('symbol-not-found', `No symbol declaration encloses ${file}:${String(line)}. ` +
+                (freshness.fresh
+                    ? 'Check the file/line, or use search_symbols by name.'
+                    : 'The catalog is stale/missing — run refresh_graph, then retry.'));
+        }
+        if (candidates.length === 1)
+            return jsonResult({ data: candidates[0], freshness });
+        return jsonResult({ ambiguous: true, candidates, freshness });
+    });
+}
+//# sourceMappingURL=get-symbol.js.map

package/dist/tools/get-symbol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-symbol.js","sourceRoot":"","sources":["../../src/tools/get-symbol.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,QAAQ,IAAI,cAAc,EAAE,IAAI,IAAI,UAAU,EAAE,MAAM,cAAc,CAAC;AAC9E,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAKpE,MAAM,UAAU,iBAAiB,CAAC,MAAsB,EAAE,IAAiB;IACzE,MAAM,CAAC,QAAQ,CACb,YAAY,EACZ;QACE,KAAK,EAAE,wBAAwB;QAC/B,WAAW,EACT,uFAAuF;YACvF,wFAAwF;YACxF,uFAAuF;YACvF,mEAAmE;QACrE,WAAW,EAAE;YACX,IAAI,EAAE,cAAc,EAAE;YACtB,IAAI,EAAE,UAAU,EAAE;SACnB;KACF,EACD,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE;QACjB,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAClD,IAAI,CAAC,OAAO,CAAC,EAAE;YAAE,OAAO,WAAW,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QACnD,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC,KAAK,CAAC;QACtD,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC5B,OAAO,OAAO,CACZ,kBAAkB,EAClB,kCAAkC,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI;gBACxD,CAAC,SAAS,CAAC,KAAK;oBACd,CAAC,CAAC,qDAAqD;oBACvD,CAAC,CAAC,+DAA+D,CAAC,CACvE,CAAC;QACJ,CAAC;QACD,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,UAAU,CAAC,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC;QACnF,OAAO,UAAU,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,UAAU,EAAE,SAAS,EAAE,CAAC,CAAC;IAChE,CAAC,CACF,CAAC;AACJ,CAAC"}

package/dist/tools/graph-walk.d.ts

@@ -0,0 +1,50 @@
+/**
+ * `boundedBfs` — the single MCP traversal primitive (ADR-0084, Task 4.2).
+ *
+ * `who_calls`, `callees_of`, and `trace_path` are three callers of ONE
+ * generic bounded-adjacency walk → rule of three satisfied. This helper lives in
+ * `packages/mcp/` because it is MCP-specific traversal vocabulary: blast scoring
+ * stays in `@opensip-cli/graph` (`buildFeatures(['blast'])`, reused via the
+ * port), symbol projection stays in graph (`buildSymbolIndexEntries`) — neither
+ * is reinvented here, and `boundedBfs` is NEVER pushed down into `core`/`graph`.
+ *
+ * The walk is over a body-hash adjacency map (the graph engine's
+ * `Indexes.callers` / `Indexes.callees`, twin-union per ADR-0003). It is:
+ *   - cycle-safe — a `visited` set guards re-entry,
+ *   - depth-bounded — at most {@link HARD_MAX_DEPTH} BFS levels,
+ *   - count-capped — stops at `cap` discovered nodes and reports `truncated`,
+ *   - optionally goal-directed — returns the moment a `goal` node is reached,
+ *     recording `parents` so the caller can reconstruct the path.
+ */
+/** Hard node cap on a single walk before `truncated` is set (mirrors the port's ceiling). */
+export declare const MAX_WALK_NODES = 2000;
+export interface BoundedBfsOptions {
+    /** BFS levels to expand (clamped to `[1, HARD_MAX_DEPTH]`). */
+    readonly depth: number;
+    /** Discovered-node ceiling; `<= 0` falls back to {@link MAX_WALK_NODES}. */
+    readonly cap: number;
+    /** When set, the walk returns the instant this node is reached (`foundGoal`). */
+    readonly goal?: string;
+}
+export interface BoundedBfsResult {
+    /** Nodes reached, in discovery order, EXCLUDING `start`. */
+    readonly order: readonly string[];
+    /** `node → predecessor` for every reached node (for path reconstruction). */
+    readonly parents: ReadonlyMap<string, string>;
+    /** `true` iff `opts.goal` was provided and reached within the bounds. */
+    readonly foundGoal: boolean;
+    /** `true` iff a depth/node cap truncated the walk. */
+    readonly truncated: boolean;
+}
+/**
+ * Bounded, cycle-safe BFS from `start` over `adjacency`. Returns the reached
+ * node set (discovery order), the predecessor map, whether `goal` was reached,
+ * and whether a cap truncated the walk.
+ */
+export declare function boundedBfs(adjacency: ReadonlyMap<string, readonly string[]>, start: string, opts: BoundedBfsOptions): BoundedBfsResult;
+/**
+ * Rebuild the path `start → … → goal` from a {@link BoundedBfsResult.parents}
+ * map. Only meaningful when the walk reached `goal` (`foundGoal`).
+ */
+export declare function reconstructPath(parents: ReadonlyMap<string, string>, start: string, goal: string): string[];
+//# sourceMappingURL=graph-walk.d.ts.map

package/dist/tools/graph-walk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-walk.d.ts","sourceRoot":"","sources":["../../src/tools/graph-walk.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,6FAA6F;AAC7F,eAAO,MAAM,cAAc,OAAO,CAAC;AASnC,MAAM,WAAW,iBAAiB;IAChC,+DAA+D;IAC/D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,4EAA4E;IAC5E,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,iFAAiF;IACjF,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,gBAAgB;IAC/B,4DAA4D;IAC5D,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,6EAA6E;IAC7E,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9C,yEAAyE;IACzE,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,sDAAsD;IACtD,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAOD;;;;GAIG;AACH,wBAAgB,UAAU,CACxB,SAAS,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,EACjD,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,iBAAiB,GACtB,gBAAgB,CAkBlB;AAsCD;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,EACpC,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,GACX,MAAM,EAAE,CASV"}

package/dist/tools/graph-walk.js

@@ -0,0 +1,89 @@
+/**
+ * `boundedBfs` — the single MCP traversal primitive (ADR-0084, Task 4.2).
+ *
+ * `who_calls`, `callees_of`, and `trace_path` are three callers of ONE
+ * generic bounded-adjacency walk → rule of three satisfied. This helper lives in
+ * `packages/mcp/` because it is MCP-specific traversal vocabulary: blast scoring
+ * stays in `@opensip-cli/graph` (`buildFeatures(['blast'])`, reused via the
+ * port), symbol projection stays in graph (`buildSymbolIndexEntries`) — neither
+ * is reinvented here, and `boundedBfs` is NEVER pushed down into `core`/`graph`.
+ *
+ * The walk is over a body-hash adjacency map (the graph engine's
+ * `Indexes.callers` / `Indexes.callees`, twin-union per ADR-0003). It is:
+ *   - cycle-safe — a `visited` set guards re-entry,
+ *   - depth-bounded — at most {@link HARD_MAX_DEPTH} BFS levels,
+ *   - count-capped — stops at `cap` discovered nodes and reports `truncated`,
+ *   - optionally goal-directed — returns the moment a `goal` node is reached,
+ *     recording `parents` so the caller can reconstruct the path.
+ */
+/** Hard node cap on a single walk before `truncated` is set (mirrors the port's ceiling). */
+export const MAX_WALK_NODES = 2000;
+/**
+ * Defence-in-depth depth ceiling, mirroring `schemas.MAX_DEPTH`. The Zod input
+ * schema already clamps `depth` to `[1, 5]` at the boundary; this keeps the pure
+ * walk correct even if invoked directly (tests) with an out-of-range depth.
+ */
+const HARD_MAX_DEPTH = 5;
+function clampDepth(depth) {
+    if (!Number.isFinite(depth))
+        return HARD_MAX_DEPTH;
+    return Math.min(Math.max(Math.trunc(depth), 1), HARD_MAX_DEPTH);
+}
+/**
+ * Bounded, cycle-safe BFS from `start` over `adjacency`. Returns the reached
+ * node set (discovery order), the predecessor map, whether `goal` was reached,
+ * and whether a cap truncated the walk.
+ */
+export function boundedBfs(adjacency, start, opts) {
+    const maxDepth = clampDepth(opts.depth);
+    const cap = opts.cap > 0 ? Math.trunc(opts.cap) : MAX_WALK_NODES;
+    const state = {
+        visited: new Set([start]),
+        parents: new Map(),
+        order: [],
+    };
+    let frontier = [start];
+    for (let d = 0; d < maxDepth && frontier.length > 0; d++) {
+        const step = expandFrontier(frontier, adjacency, state, cap, opts.goal);
+        if (step.halt !== undefined) {
+            return { order: state.order, parents: state.parents, ...step.halt };
+        }
+        frontier = step.next;
+    }
+    return { order: state.order, parents: state.parents, foundGoal: false, truncated: false };
+}
+/** Expand one BFS level: record newly-seen neighbors, halting on goal/cap. */
+function expandFrontier(frontier, adjacency, state, cap, goal) {
+    const next = [];
+    for (const node of frontier) {
+        for (const neighbor of adjacency.get(node) ?? []) {
+            if (state.visited.has(neighbor))
+                continue;
+            state.visited.add(neighbor);
+            state.parents.set(neighbor, node);
+            state.order.push(neighbor);
+            if (neighbor === goal)
+                return { next, halt: { foundGoal: true, truncated: false } };
+            if (state.order.length >= cap)
+                return { next, halt: { foundGoal: false, truncated: true } };
+            next.push(neighbor);
+        }
+    }
+    return { next };
+}
+/**
+ * Rebuild the path `start → … → goal` from a {@link BoundedBfsResult.parents}
+ * map. Only meaningful when the walk reached `goal` (`foundGoal`).
+ */
+export function reconstructPath(parents, start, goal) {
+    const path = [];
+    let cursor = goal;
+    while (cursor !== undefined) {
+        path.unshift(cursor);
+        if (cursor === start)
+            break;
+        cursor = parents.get(cursor);
+    }
+    return path;
+}
+//# sourceMappingURL=graph-walk.js.map

package/dist/tools/graph-walk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-walk.js","sourceRoot":"","sources":["../../src/tools/graph-walk.ts"],"names":[],"mappings":"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"}

package/dist/tools/list-runs.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `list_runs` — lean stored-run pointers (ADR-0084, Task 4.5).
+ *
+ * Reads `resultsPort.listRuns()` ONLY — replay of persisted sessions, never a
+ * re-run. Returns a menu of `RunSummary` rows, each with the `opensip sessions
+ * show …` command + MCP follow-up via `show_run` / `get_latest_findings`.
+ */
+import type { McpToolDeps } from './types.js';
+import type { McpStdioServer } from '../server.js';
+export declare function registerListRuns(server: McpStdioServer, deps: McpToolDeps): void;
+//# sourceMappingURL=list-runs.d.ts.map

package/dist/tools/list-runs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"list-runs.d.ts","sourceRoot":"","sources":["../../src/tools/list-runs.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAOH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEnD,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,cAAc,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CA6BhF"}

package/dist/tools/list-runs.js

@@ -0,0 +1,37 @@
+/**
+ * `list_runs` — lean stored-run pointers (ADR-0084, Task 4.5).
+ *
+ * Reads `resultsPort.listRuns()` ONLY — replay of persisted sessions, never a
+ * re-run. Returns a menu of `RunSummary` rows, each with the `opensip sessions
+ * show …` command + MCP follow-up via `show_run` / `get_latest_findings`.
+ */
+import { z } from 'zod';
+import { limit as limitSchema, toolId as toolIdSchema } from './schemas.js';
+import { errorResult, jsonResult, unknownToolError } from './tool-result.js';
+export function registerListRuns(server, deps) {
+    server.register('list_runs', {
+        title: 'List OpenSIP runs',
+        description: 'List recent stored OpenSIP runs (fit/graph/yagni/sim) as lean pointers — id, tool, ' +
+            'timing, score/passed, and the replay command. Drill into one with show_run, or jump to ' +
+            'a tool’s current findings with get_latest_findings. Replays persisted sessions; ' +
+            'never re-runs a tool. Filter by `tool`, cap with `limit`.',
+        inputSchema: {
+            tool: toolIdSchema().optional(),
+            limit: limitSchema(),
+            summaryOnly: z.boolean().optional(),
+        },
+    }, ({ tool, limit, summaryOnly }) => {
+        if (tool !== undefined && !deps.validToolIds.has(tool)) {
+            return unknownToolError(tool, deps.validToolIds);
+        }
+        const outcome = deps.results.listRuns({
+            ...(tool === undefined ? {} : { tool }),
+            ...(limit === undefined ? {} : { limit }),
+            ...(summaryOnly === undefined ? {} : { summaryOnly }),
+        });
+        if (!outcome.ok)
+            return errorResult(outcome.error);
+        return jsonResult({ runs: outcome.value });
+    });
+}
+//# sourceMappingURL=list-runs.js.map

package/dist/tools/list-runs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"list-runs.js","sourceRoot":"","sources":["../../src/tools/list-runs.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,KAAK,IAAI,WAAW,EAAE,MAAM,IAAI,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5E,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAK7E,MAAM,UAAU,gBAAgB,CAAC,MAAsB,EAAE,IAAiB;IACxE,MAAM,CAAC,QAAQ,CACb,WAAW,EACX;QACE,KAAK,EAAE,mBAAmB;QAC1B,WAAW,EACT,qFAAqF;YACrF,yFAAyF;YACzF,kFAAkF;YAClF,2DAA2D;QAC7D,WAAW,EAAE;YACX,IAAI,EAAE,YAAY,EAAE,CAAC,QAAQ,EAAE;YAC/B,KAAK,EAAE,WAAW,EAAE;YACpB,WAAW,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;SACpC;KACF,EACD,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,WAAW,EAAE,EAAE,EAAE;QAC/B,IAAI,IAAI,KAAK,SAAS,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YACvD,OAAO,gBAAgB,CAAC,IAAI,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC;QACnD,CAAC;QACD,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC;YACpC,GAAG,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC;YACvC,GAAG,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC;YACzC,GAAG,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC;SACtD,CAAC,CAAC;QACH,IAAI,CAAC,OAAO,CAAC,EAAE;YAAE,OAAO,WAAW,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QACnD,OAAO,UAAU,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;IAC7C,CAAC,CACF,CAAC;AACJ,CAAC"}

package/dist/tools/refresh-graph.d.ts

@@ -0,0 +1,22 @@
+/**
+ * `refresh_graph` — the single state-changing op (ADR-0084, Task 4.4).
+ *
+ * Rebuilds the call-graph catalog through the graph engine's programmatic build
+ * (`runGraph`, wired by the host into `graphPort.refresh()`), persists it to the
+ * shared datastore, and atomically swaps the in-memory generation. Concurrent
+ * calls are serialized to ONE rebuild inside the port. v1 uses the exact
+ * single-program build (no cloud egress, no live render).
+ *
+ * COST WARNING (also in the tool description): a rebuild parses the whole
+ * project — agents must NOT loop it per query. Call it once when the catalog is
+ * missing/stale (other tools report `freshness.fresh === false`), then read.
+ *
+ * Observability: emits `mcp.refresh.run[.ok|.error]` to the stderr logger and
+ * (fire-and-forget, no-op when telemetry is disabled) records rebuild latency on
+ * the `opensip-cli` meter with bounded labels `{ command, op, outcome }` — never
+ * a path/id/symbol.
+ */
+import type { McpToolDeps } from './types.js';
+import type { McpStdioServer } from '../server.js';
+export declare function registerRefreshGraph(server: McpStdioServer, deps: McpToolDeps): void;
+//# sourceMappingURL=refresh-graph.d.ts.map

package/dist/tools/refresh-graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"refresh-graph.d.ts","sourceRoot":"","sources":["../../src/tools/refresh-graph.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAMH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAenD,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,cAAc,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CA6CpF"}

package/dist/tools/refresh-graph.js

@@ -0,0 +1,75 @@
+/**
+ * `refresh_graph` — the single state-changing op (ADR-0084, Task 4.4).
+ *
+ * Rebuilds the call-graph catalog through the graph engine's programmatic build
+ * (`runGraph`, wired by the host into `graphPort.refresh()`), persists it to the
+ * shared datastore, and atomically swaps the in-memory generation. Concurrent
+ * calls are serialized to ONE rebuild inside the port. v1 uses the exact
+ * single-program build (no cloud egress, no live render).
+ *
+ * COST WARNING (also in the tool description): a rebuild parses the whole
+ * project — agents must NOT loop it per query. Call it once when the catalog is
+ * missing/stale (other tools report `freshness.fresh === false`), then read.
+ *
+ * Observability: emits `mcp.refresh.run[.ok|.error]` to the stderr logger and
+ * (fire-and-forget, no-op when telemetry is disabled) records rebuild latency on
+ * the `opensip-cli` meter with bounded labels `{ command, op, outcome }` — never
+ * a path/id/symbol.
+ */
+import { getMeter, logger } from '@opensip-cli/core';
+import { errorResult, jsonResult } from './tool-result.js';
+const LOG_MODULE = 'mcp:refresh';
+/** Record rebuild latency on the shared meter (no-op until an OTel SDK is registered). */
+function recordRefreshLatency(durationMs, outcome) {
+    try {
+        getMeter('opensip-cli')
+            .createHistogram('opensip_cli.mcp.refresh.duration_ms')
+            .record(durationMs, { command: 'mcp', op: 'refresh', outcome });
+    }
+    catch {
+        // Telemetry is best-effort; a meter failure must never fail a refresh.
+    }
+}
+export function registerRefreshGraph(server, deps) {
+    server.register('refresh_graph', {
+        title: 'Rebuild the call graph',
+        description: 'Rebuild the OpenSIP call-graph catalog from the current working tree (the only ' +
+            'state-changing tool). EXPENSIVE — it parses the whole project; do NOT loop it per ' +
+            'query. Call it once when other tools report a stale or missing catalog ' +
+            '(freshness.fresh === false), then read. Returns { builtAt, durationMs, freshness }.',
+    }, async () => {
+        const startedAt = Date.now();
+        try {
+            const outcome = await deps.graph.refresh();
+            const durationMs = Date.now() - startedAt;
+            if (!outcome.ok) {
+                logger.error({
+                    evt: 'mcp.refresh.run.error',
+                    module: LOG_MODULE,
+                    code: outcome.error.code,
+                    durationMs,
+                });
+                recordRefreshLatency(durationMs, 'error');
+                return errorResult(outcome.error);
+            }
+            const freshness = deps.graph.freshness();
+            logger.info({ evt: 'mcp.refresh.run.ok', module: LOG_MODULE, durationMs });
+            recordRefreshLatency(durationMs, 'ok');
+            return jsonResult({ builtAt: outcome.value.data.builtAt, durationMs, freshness });
+        }
+        catch (error) {
+            const durationMs = Date.now() - startedAt;
+            logger.error({
+                evt: 'mcp.refresh.run.error',
+                module: LOG_MODULE,
+                error: error instanceof Error ? error.message : String(error),
+                durationMs,
+            });
+            recordRefreshLatency(durationMs, 'error');
+            // A genuine build failure is an infra boundary: re-throw so the SDK emits
+            // a JSON-RPC error frame (the server's dispatch logs the decision point).
+            throw error;
+        }
+    });
+}
+//# sourceMappingURL=refresh-graph.js.map

package/dist/tools/refresh-graph.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"refresh-graph.js","sourceRoot":"","sources":["../../src/tools/refresh-graph.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAErD,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAK3D,MAAM,UAAU,GAAG,aAAa,CAAC;AAEjC,0FAA0F;AAC1F,SAAS,oBAAoB,CAAC,UAAkB,EAAE,OAAuB;IACvE,IAAI,CAAC;QACH,QAAQ,CAAC,aAAa,CAAC;aACpB,eAAe,CAAC,qCAAqC,CAAC;aACtD,MAAM,CAAC,UAAU,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC,CAAC;IACpE,CAAC;IAAC,MAAM,CAAC;QACP,uEAAuE;IACzE,CAAC;AACH,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,MAAsB,EAAE,IAAiB;IAC5E,MAAM,CAAC,QAAQ,CACb,eAAe,EACf;QACE,KAAK,EAAE,wBAAwB;QAC/B,WAAW,EACT,iFAAiF;YACjF,oFAAoF;YACpF,yEAAyE;YACzE,qFAAqF;KACxF,EACD,KAAK,IAAI,EAAE;QACT,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAC7B,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC;YAC3C,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;YAC1C,IAAI,CAAC,OAAO,CAAC,EAAE,EAAE,CAAC;gBAChB,MAAM,CAAC,KAAK,CAAC;oBACX,GAAG,EAAE,uBAAuB;oBAC5B,MAAM,EAAE,UAAU;oBAClB,IAAI,EAAE,OAAO,CAAC,KAAK,CAAC,IAAI;oBACxB,UAAU;iBACX,CAAC,CAAC;gBACH,oBAAoB,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;gBAC1C,OAAO,WAAW,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;YACpC,CAAC;YACD,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,EAAE,CAAC;YACzC,MAAM,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,oBAAoB,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,CAAC,CAAC;YAC3E,oBAAoB,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;YACvC,OAAO,UAAU,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,CAAC,CAAC;QACpF,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;YAC1C,MAAM,CAAC,KAAK,CAAC;gBACX,GAAG,EAAE,uBAAuB;gBAC5B,MAAM,EAAE,UAAU;gBAClB,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;gBAC7D,UAAU;aACX,CAAC,CAAC;YACH,oBAAoB,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;YAC1C,0EAA0E;YAC1E,0EAA0E;YAC1E,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC,CACF,CAAC;AACJ,CAAC"}

package/dist/tools/register.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Mount the MCP tool catalog onto the server (ADR-0084, Phase 4).
+ *
+ * One place that wires every graph + result tool through the server's
+ * scope-wrapping {@link McpStdioServer.register} seam. The host calls this once
+ * (in `command.ts`) after building the ports; each tool reads ONLY its injected
+ * port (never `currentScope()`, never a run-command entry point).
+ */
+import type { McpToolDeps } from './types.js';
+import type { McpStdioServer } from '../server.js';
+/** Register all 13 MCP tools (9 graph + 4 result) on `server`. */
+export declare function registerMcpTools(server: McpStdioServer, deps: McpToolDeps): void;
+//# sourceMappingURL=register.d.ts.map

package/dist/tools/register.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"register.d.ts","sourceRoot":"","sources":["../../src/tools/register.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAgBH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEnD,kEAAkE;AAClE,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,cAAc,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CAiBhF"}