circle-ir-ai 4.16.5 → 4.18.0

package/CHANGELOG.md

@@ -7,6 +7,64 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- **The ten MCP tools declare annotations** (4.18.0), each measured before it was written down.
+  All ten are `readOnlyHint: true`, `destructiveHint: false`, `idempotentHint: true`: none writes,
+  changes or deletes a file in the project, the working directory, the home directory or the temp
+  directory. Seven are `openWorldHint: false` and open no connection at all. Three are
+  `openWorldHint: true`, because they can leave the machine: `find_stale_dependencies` (the npm
+  registry, and the OSV database unless `check_vulnerabilities` is off), `find_typosquats` (npm
+  download counts, only with `check_popularity`) and `find_credential_exposure` (a model endpoint,
+  only with `llm_verify`). The hint is per tool, so it is declared even where one argument causes
+  it. `tests/mcp/annotations.test.ts` fails if a tool starts writing a file or a local tool opens
+  a connection. Additive in `tools/list`; no name, argument or response changes.
+- **`circle-ir-ai/mcp` is built on the v2 MCP SDK** (4.18.0), the line that speaks protocol
+  revision 2026-07-28. The optional peer is now `@modelcontextprotocol/server` ^2.2.0, in place of
+  `@modelcontextprotocol/sdk` ^1.30.1, and each tool hands the SDK schema objects rather than
+  bare shapes. The tools, their arguments and their output schemas are unchanged: under one
+  server the ten schemas are identical to 4.17.0's. Loads into `@cognium/mcp-server` 0.2.x (1.x
+  SDK) and 0.4.x (v2 SDK) alike; checked in all four pairings of old and new.
+
+  **Type-level only:** a host that type-checks this module against `@cognium/mcp-server`'s
+  `ToolModule` needs the server on 0.4.0 or later, where that type is on the v2 SDK too.
+- **`circle-ir-ai/mcp` — this library's ten MCP tools as a module for `@cognium/mcp-server`**
+  (4.17.0). The server looks for this entry at startup and, when the package is installed and
+  built against the same `circle-ir` minor, registers the tools after its own eleven. Built
+  against `circle-ir` 4.9.29 and tested with `@cognium/mcp-server` 0.2.0 and MCP SDK ^1.30.1.
+  The tools are the ones `@cognium-ai/mcp-server` served, with the same names and arguments:
+  `verify_spec_conformance`, `find_spec_drift`, `find_pattern`, `find_credential_exposure`,
+  `check_license_compliance`, `find_stale_dependencies`, `find_install_script_risk`,
+  `find_typosquats`, `find_excessive_permissions`, `layer_bom`.
+
+  The server is not a dependency. `@modelcontextprotocol/sdk` is an optional peer, needed only
+  by a host that loads this entry; `zod` (^4) is now a direct dependency, where it was already
+  present transitively.
+
+  - **Every response carries `provenance`**: `deterministic`, or `llm: <model>` when a model
+    judged something in that call. It is in each tool's output schema, as a required field.
+  - **Nine of the ten tools are deterministic.** The only model path is `llm_verify` on
+    `find_credential_exposure`, which is off by default, marked `LLM-backed` in the tool and
+    argument descriptions, and runs only when the call asks for it.
+  - **`llm_verify` is refused on an install that is not enabled for it** — no configured
+    endpoint (`COGNIUM_ENDPOINT`) and no licence token. The call returns one line as an error
+    result. Before, the engine skipped verification and returned the unverified findings with
+    nothing to say so.
+  - **The configured endpoint is where the model is.** With an endpoint, verification goes to
+    it; with a licence token and no endpoint, the `LLM_*` environment applies as before.
+- `SecretScanOptions.llmConfig` — overrides merged over the environment-derived LLM
+  configuration for the verifier, so a caller that was handed an endpoint can use it without
+  writing to `process.env`. Unset, behaviour is unchanged.
+
+#### Consumer Impact
+- **`find_credential_exposure` with `llm_verify: true` and no enablement now returns an error
+  result (`isError: true`) instead of findings.** A client that does not check `isError` and
+  reads `structuredContent` will find it absent. Call without `llm_verify`, or configure
+  `COGNIUM_ENDPOINT` or a licence token. Applies only through this module; the
+  `scanForSecrets` API itself is unchanged.
+- **Tool input schemas are now generated by zod 4.** Names, types and required arguments are
+  the same; incidental JSON Schema details (`$schema`, how defaults are expressed) can differ
+  from what `@cognium-ai/mcp-server` published.
+
 ### Changed
 - **`circle-ir` 4.9.27 → 4.9.29.** All four packages re-pinned; suites pass unchanged
   (circle-ir-ai 2340, cognium-ai 363, mcp-server 11, circle-pack 182) and each resolves exactly
@@ -36,15 +94,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   **cognium-dev#503 landed:** CWE-81 went 0.0% → 88.9% and CWE-94 0.0% → 100%, the two families
   that were at exactly zero and that ticket's two missing sinks.
 
-  **Precision regressed sharply, and only where cognium-dev#508 applies.** CWE-89 sqli and
-  CWE-643 xpath now fire on **100% of their files including every `Good*()` safe control** (27/27
-  and 10/10), and CWE-94 on 90%. The other six families hold **0.0% FPR** at 88.9–90% recall.
-  More bound sources produce proportionally more bogus source×sink pairings: CWE-89 cross-method
-  leaks went 3 → 12 → 27 across the same three releases. #508 is now the top C# precision item,
-  reported there with this evidence.
+  **cognium-dev#508 and #509 are fixed in 4.9.29.** Verified on the published build: the probes
+  where a tainted parameter never reaches the query (`D2_NoSibling`, `D4_TaintUnused`) are now
+  clean, and one SQLi emits one finding rather than two. They still reproduced on 4.9.28.
+
+  **Precision regressed sharply anyway, via a different mechanism.** CWE-89 sqli and CWE-643
+  xpath now fire on **100% of their files including every `Good*()` safe control** (27/27 and
+  10/10), and CWE-94 on 90%, while the other six families hold **0.0% FPR** at 88.9–90% recall.
+  All 27 CWE-89 false-positive files are **cross-method leaks** (`xLeak` 27 of 27) — taint
+  associated across a `Bad()`→`Good*()` boundary by variable name, the cognium-dev#316 family,
+  not #508's source×sink pairing. Leaks went 3 → 12 → 27 as more sources bound, so the recall
+  work and that leak multiply.
 
-  **Not fixed in either release:** cognium-dev#520 (`HtmlEncoder` still uncredited, so
-  `xss_htmlencode_safe` remains the sole FP on both C# synthetic gates), #508, #509.
+  **Not fixed:** cognium-dev#520 (`HtmlEncoder` still uncredited, so `xss_htmlencode_safe`
+  remains the sole FP on both C# synthetic gates).
 
   **Carried-over regression:** `rmp_serde::from_slice` is still not a deserialization sink, so
   MessagePack over a `TcpStream` is undetected — Rust synthetic 97.3% TPR, down from 100%.

package/README.md

@@ -213,9 +213,33 @@ Top findings: Jenkins (9), HuggingFace (4), Tauri (6-7), TiKV (3), Deno (3), Car
 | Bash | Shell script command-injection / code-injection detection |
 | HTML | XSS detection in templates |
 
+## MCP tools
+
+`circle-ir-ai/mcp` exports this library's ten MCP tools as a module for
+[`@cognium/mcp-server`](https://www.npmjs.com/package/@cognium/mcp-server). Install both and the
+server finds the module at startup and lists the tools after its own:
+
+```bash
+npm install @cognium/mcp-server circle-ir-ai
+npx mcp-server-cognium-dev
+```
+
+The module is refused, on one line of stderr, if it was built against a different `circle-ir`
+minor than the server has; the server's own tools keep serving.
+
+Each tool declares annotations in `tools/list`. All ten are read-only. Seven never leave the
+machine; `find_stale_dependencies`, `find_typosquats` and `find_credential_exposure` can, and say
+so (`openWorldHint: true`).
+
+Every response carries `provenance`: `deterministic`, or `llm: <model>` when a model judged
+something in that call. Nine of the ten tools are deterministic. The one model path is
+`llm_verify` on `find_credential_exposure`: off by default, and refused with one line unless
+the install has a configured endpoint (`COGNIUM_ENDPOINT`) or a licence token.
+
 ## Related Packages
 
 - **[circle-ir](https://github.com/cogniumhq/circle-ir)**: Core SAST library (open source, MIT)
+- **[@cognium/mcp-server](https://www.npmjs.com/package/@cognium/mcp-server)**: The MCP server that loads `circle-ir-ai/mcp` (MIT)
 
 ## License
 

package/dist/mcp/analysis.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Circle-IR loading for the MCP tools.
+ *
+ * Wraps circle-ir-ai's analyzer lifecycle: initialize the WASM-backed
+ * analyzer once, walk the code root for supported source files, and run
+ * circle-ir's `analyze` per file. The resulting `CircleIR[]` is the input to
+ * `analyzeSpecGap` (used by the verify/drift tools).
+ *
+ * Mirrors the wiring recipe in cognium-ai's `spec-diff` command, but depends
+ * only on `circle-ir` + `circle-ir-ai` (not the cognium-ai CLI).
+ */
+import { type CircleIR } from 'circle-ir';
+import { type WalkOptions } from './walk.js';
+export interface LoadedCircleIR {
+    /** Absolute path to the analyzed code root. */
+    codePath: string;
+    /** Per-file circle-ir analysis results. */
+    results: CircleIR[];
+}
+/**
+ * Walk `codeRoot`, analyze each supported source file, and return the
+ * collected `CircleIR[]` alongside the resolved code path.
+ */
+export declare function loadCircleIR(codeRoot: string, options?: WalkOptions): Promise<LoadedCircleIR>;
+//# sourceMappingURL=analysis.d.ts.map

package/dist/mcp/analysis.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analysis.d.ts","sourceRoot":"","sources":["../../src/mcp/analysis.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,OAAO,EAAW,KAAK,QAAQ,EAAE,MAAM,WAAW,CAAC;AAEnD,OAAO,EAAsB,KAAK,WAAW,EAAE,MAAM,WAAW,CAAC;AAEjE,MAAM,WAAW,cAAc;IAC7B,+CAA+C;IAC/C,QAAQ,EAAE,MAAM,CAAC;IACjB,2CAA2C;IAC3C,OAAO,EAAE,QAAQ,EAAE,CAAC;CACrB;AAED;;;GAGG;AACH,wBAAsB,YAAY,CAChC,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,WAAgB,GACxB,OAAO,CAAC,cAAc,CAAC,CAwBzB"}

package/dist/mcp/analysis.js

@@ -0,0 +1,45 @@
+/**
+ * Circle-IR loading for the MCP tools.
+ *
+ * Wraps circle-ir-ai's analyzer lifecycle: initialize the WASM-backed
+ * analyzer once, walk the code root for supported source files, and run
+ * circle-ir's `analyze` per file. The resulting `CircleIR[]` is the input to
+ * `analyzeSpecGap` (used by the verify/drift tools).
+ *
+ * Mirrors the wiring recipe in cognium-ai's `spec-diff` command, but depends
+ * only on `circle-ir` + `circle-ir-ai` (not the cognium-ai CLI).
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { analyze } from 'circle-ir';
+import { ensureAnalyzerInitialized } from '../utils/analyzer-init.js';
+import { collectSourceFiles } from './walk.js';
+/**
+ * Walk `codeRoot`, analyze each supported source file, and return the
+ * collected `CircleIR[]` alongside the resolved code path.
+ */
+export async function loadCircleIR(codeRoot, options = {}) {
+    await ensureAnalyzerInitialized();
+    const codePath = path.resolve(codeRoot);
+    const files = collectSourceFiles(codePath, options);
+    const results = [];
+    for (const file of files) {
+        let content;
+        try {
+            content = fs.readFileSync(file.absolutePath, 'utf-8');
+        }
+        catch {
+            continue;
+        }
+        try {
+            const ir = await analyze(content, path.basename(file.absolutePath), file.language);
+            results.push(ir);
+        }
+        catch {
+            // Skip files circle-ir can't parse; spec-gap tolerates a partial corpus.
+            continue;
+        }
+    }
+    return { codePath, results };
+}
+//# sourceMappingURL=analysis.js.map

package/dist/mcp/analysis.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"analysis.js","sourceRoot":"","sources":["../../src/mcp/analysis.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AACzB,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAC7B,OAAO,EAAE,OAAO,EAAiB,MAAM,WAAW,CAAC;AACnD,OAAO,EAAE,yBAAyB,EAAE,MAAM,2BAA2B,CAAC;AACtE,OAAO,EAAE,kBAAkB,EAAoB,MAAM,WAAW,CAAC;AASjE;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,QAAgB,EAChB,UAAuB,EAAE;IAEzB,MAAM,yBAAyB,EAAE,CAAC;IAElC,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IACxC,MAAM,KAAK,GAAG,kBAAkB,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IAEpD,MAAM,OAAO,GAAe,EAAE,CAAC;IAC/B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,OAAe,CAAC;QACpB,IAAI,CAAC;YACH,OAAO,GAAG,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;QACxD,CAAC;QAAC,MAAM,CAAC;YACP,SAAS;QACX,CAAC;QACD,IAAI,CAAC;YACH,MAAM,EAAE,GAAG,MAAM,OAAO,CAAC,OAAO,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,YAAY,CAAC,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;YACnF,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACnB,CAAC;QAAC,MAAM,CAAC;YACP,yEAAyE;YACzE,SAAS;QACX,CAAC;IACH,CAAC;IAED,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC;AAC/B,CAAC"}

package/dist/mcp/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * `circle-ir-ai/mcp` — this library's tools as a module for the one MCP
+ * server.
+ *
+ * `@cognium/mcp-server` looks for this entry when it starts and, if the
+ * package is installed and built against the same `circle-ir` minor,
+ * registers these tools after its own. The server is not a dependency of
+ * this package and is never bundled with it: the module only describes
+ * itself and registers handlers over this library's own functions.
+ *
+ * Nine of the ten tools are deterministic. `find_credential_exposure` is
+ * deterministic unless it is called with `llm_verify`, which asks a model to
+ * re-check the candidates; that path runs only when asked for by name, only
+ * on an install that is enabled for it, and refuses otherwise.
+ */
+import type { CircleIrAiToolModule } from './types.js';
+/** The tools this module registers, in registration order. */
+export declare const TOOL_NAMES: readonly ["verify_spec_conformance", "find_spec_drift", "find_pattern", "find_credential_exposure", "check_license_compliance", "find_stale_dependencies", "find_install_script_risk", "find_typosquats", "find_excessive_permissions", "layer_bom"];
+export declare const toolModule: CircleIrAiToolModule;
+export default toolModule;
+export { DETERMINISTIC, llmProvenance } from './result.js';
+export { llmEnabled } from './types.js';
+export type { CircleIrAiToolModule, ModuleContext, ModuleEnablement } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/mcp/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/mcp/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,OAAO,KAAK,EAAE,oBAAoB,EAAiB,MAAM,YAAY,CAAC;AAsBtE,8DAA8D;AAC9D,eAAO,MAAM,UAAU,sPAWb,CAAC;AAEX,eAAO,MAAM,UAAU,EAAE,oBAuBxB,CAAC;AAEF,eAAe,UAAU,CAAC;AAE1B,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC3D,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxC,YAAY,EAAE,oBAAoB,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC"}

package/dist/mcp/index.js

@@ -0,0 +1,67 @@
+/**
+ * `circle-ir-ai/mcp` — this library's tools as a module for the one MCP
+ * server.
+ *
+ * `@cognium/mcp-server` looks for this entry when it starts and, if the
+ * package is installed and built against the same `circle-ir` minor,
+ * registers these tools after its own. The server is not a dependency of
+ * this package and is never bundled with it: the module only describes
+ * itself and registers handlers over this library's own functions.
+ *
+ * Nine of the ten tools are deterministic. `find_credential_exposure` is
+ * deterministic unless it is called with `llm_verify`, which asks a model to
+ * re-check the candidates; that path runs only when asked for by name, only
+ * on an install that is enabled for it, and refuses otherwise.
+ */
+import { createRequire } from 'node:module';
+import { registerVerifySpecConformance } from './tools/verify-spec-conformance.js';
+import { registerFindSpecDrift } from './tools/find-spec-drift.js';
+import { registerFindPattern } from './tools/find-pattern.js';
+import { registerFindCredentialExposure } from './tools/find-credential-exposure.js';
+import { registerCheckLicenseCompliance } from './tools/check-license-compliance.js';
+import { registerFindStaleDependencies } from './tools/find-stale-dependencies.js';
+import { registerFindInstallScriptRisk } from './tools/find-install-script-risk.js';
+import { registerFindTyposquats } from './tools/find-typosquats.js';
+import { registerFindExcessivePermissions } from './tools/find-excessive-permissions.js';
+import { registerLayerBom } from './tools/layer-bom.js';
+// From the manifest, so the module can never announce a version or a
+// `circle-ir` pin other than the one it was published with.
+const manifest = createRequire(import.meta.url)('../../package.json');
+/** The tools this module registers, in registration order. */
+export const TOOL_NAMES = [
+    'verify_spec_conformance',
+    'find_spec_drift',
+    'find_pattern',
+    'find_credential_exposure',
+    'check_license_compliance',
+    'find_stale_dependencies',
+    'find_install_script_risk',
+    'find_typosquats',
+    'find_excessive_permissions',
+    'layer_bom',
+];
+export const toolModule = {
+    id: 'circle-ir-ai/mcp',
+    version: manifest.version,
+    licence: manifest.license,
+    circleIrRange: manifest.dependencies['circle-ir'],
+    register(server, ctx) {
+        // Spec tools
+        registerVerifySpecConformance(server);
+        registerFindSpecDrift(server);
+        registerFindPattern(server);
+        // Supply chain and credentials
+        registerFindCredentialExposure(server, ctx);
+        registerCheckLicenseCompliance(server);
+        registerFindStaleDependencies(server);
+        registerFindInstallScriptRisk(server);
+        registerFindTyposquats(server);
+        registerFindExcessivePermissions(server);
+        // Inventory
+        registerLayerBom(server);
+    },
+};
+export default toolModule;
+export { DETERMINISTIC, llmProvenance } from './result.js';
+export { llmEnabled } from './types.js';
+//# sourceMappingURL=index.js.map

package/dist/mcp/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/mcp/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAG5C,OAAO,EAAE,6BAA6B,EAAE,MAAM,oCAAoC,CAAC;AACnF,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AACnE,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EAAE,8BAA8B,EAAE,MAAM,qCAAqC,CAAC;AACrF,OAAO,EAAE,8BAA8B,EAAE,MAAM,qCAAqC,CAAC;AACrF,OAAO,EAAE,6BAA6B,EAAE,MAAM,oCAAoC,CAAC;AACnF,OAAO,EAAE,6BAA6B,EAAE,MAAM,qCAAqC,CAAC;AACpF,OAAO,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAC;AACpE,OAAO,EAAE,gCAAgC,EAAE,MAAM,uCAAuC,CAAC;AACzF,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAQxD,qEAAqE;AACrE,4DAA4D;AAC5D,MAAM,QAAQ,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,oBAAoB,CAAa,CAAC;AAElF,8DAA8D;AAC9D,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,yBAAyB;IACzB,iBAAiB;IACjB,cAAc;IACd,0BAA0B;IAC1B,0BAA0B;IAC1B,yBAAyB;IACzB,0BAA0B;IAC1B,iBAAiB;IACjB,4BAA4B;IAC5B,WAAW;CACH,CAAC;AAEX,MAAM,CAAC,MAAM,UAAU,GAAyB;IAC9C,EAAE,EAAE,kBAAkB;IACtB,OAAO,EAAE,QAAQ,CAAC,OAAO;IACzB,OAAO,EAAE,QAAQ,CAAC,OAAO;IACzB,aAAa,EAAE,QAAQ,CAAC,YAAY,CAAC,WAAW,CAAC;IAEjD,QAAQ,CAAC,MAAiB,EAAE,GAAkB;QAC5C,aAAa;QACb,6BAA6B,CAAC,MAAM,CAAC,CAAC;QACtC,qBAAqB,CAAC,MAAM,CAAC,CAAC;QAC9B,mBAAmB,CAAC,MAAM,CAAC,CAAC;QAE5B,+BAA+B;QAC/B,8BAA8B,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QAC5C,8BAA8B,CAAC,MAAM,CAAC,CAAC;QACvC,6BAA6B,CAAC,MAAM,CAAC,CAAC;QACtC,6BAA6B,CAAC,MAAM,CAAC,CAAC;QACtC,sBAAsB,CAAC,MAAM,CAAC,CAAC;QAC/B,gCAAgC,CAAC,MAAM,CAAC,CAAC;QAEzC,YAAY;QACZ,gBAAgB,CAAC,MAAM,CAAC,CAAC;IAC3B,CAAC;CACF,CAAC;AAEF,eAAe,UAAU,CAAC;AAE1B,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC3D,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC"}

package/dist/mcp/mappers.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Pure mappers from the engine's `SpecGapResult` (camelCase) to the MCP
+ * boundary shapes (snake_case). Kept side-effect-free so they can be unit
+ * tested without spinning up the analyzer.
+ *
+ * Schema stability: field names here are draft-stable through 2026-08-31.
+ * Additive changes are safe; renames/removals are breaking (bump major).
+ */
+import type { SpecGapResult } from '../spec-gap/index.js';
+/** Confidence at/above which a covered match is "covered" vs "partial". */
+export declare const PARTIAL_CONFIDENCE_THRESHOLD = 0.7;
+export type RequirementStatus = 'covered' | 'partial' | 'uncovered';
+export interface RequirementEvidence {
+    function?: string;
+    file?: string;
+    span?: [number, number];
+}
+export interface VerifyRequirement {
+    id: string;
+    status: RequirementStatus;
+    evidence: RequirementEvidence;
+}
+export interface VerifyConformanceResult {
+    alignment_score: number;
+    requirements: VerifyRequirement[];
+    summary: string;
+}
+export type DriftKind = 'code_without_spec' | 'spec_without_code';
+export interface Drift {
+    kind: DriftKind;
+    location: string;
+    suggested_action: string;
+}
+export interface FindSpecDriftResult {
+    drifts: Drift[];
+}
+/** Map a `SpecGapResult` to the `verify_spec_conformance` output shape. */
+export declare function toVerifyConformance(result: SpecGapResult): VerifyConformanceResult;
+/** Map a `SpecGapResult` to the `find_spec_drift` output shape. */
+export declare function toSpecDrift(result: SpecGapResult): FindSpecDriftResult;
+//# sourceMappingURL=mappers.d.ts.map

package/dist/mcp/mappers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mappers.d.ts","sourceRoot":"","sources":["../../src/mcp/mappers.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAE1D,2EAA2E;AAC3E,eAAO,MAAM,4BAA4B,MAAM,CAAC;AAEhD,MAAM,MAAM,iBAAiB,GAAG,SAAS,GAAG,SAAS,GAAG,WAAW,CAAC;AAEpE,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACzB;AAED,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,iBAAiB,CAAC;IAC1B,QAAQ,EAAE,mBAAmB,CAAC;CAC/B;AAED,MAAM,WAAW,uBAAuB;IACtC,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,iBAAiB,EAAE,CAAC;IAClC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,SAAS,GAAG,mBAAmB,GAAG,mBAAmB,CAAC;AAElE,MAAM,WAAW,KAAK;IACpB,IAAI,EAAE,SAAS,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,KAAK,EAAE,CAAC;CACjB;AAED,2EAA2E;AAC3E,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,aAAa,GAAG,uBAAuB,CA2ClF;AAED,mEAAmE;AACnE,wBAAgB,WAAW,CAAC,MAAM,EAAE,aAAa,GAAG,mBAAmB,CAqBtE"}

package/dist/mcp/mappers.js

@@ -0,0 +1,69 @@
+/**
+ * Pure mappers from the engine's `SpecGapResult` (camelCase) to the MCP
+ * boundary shapes (snake_case). Kept side-effect-free so they can be unit
+ * tested without spinning up the analyzer.
+ *
+ * Schema stability: field names here are draft-stable through 2026-08-31.
+ * Additive changes are safe; renames/removals are breaking (bump major).
+ */
+/** Confidence at/above which a covered match is "covered" vs "partial". */
+export const PARTIAL_CONFIDENCE_THRESHOLD = 0.7;
+/** Map a `SpecGapResult` to the `verify_spec_conformance` output shape. */
+export function toVerifyConformance(result) {
+    // Empty-spec guard: the engine returns specAlignmentScore=100 when zero
+    // requirements parse from spec_dir (a missing/empty/malformed spec). A
+    // consumer gating on `alignment_score >= N` would treat that as a pass.
+    // Surface it as a non-passing 0 with an explicit summary instead.
+    if (result.summary.totalRequirements === 0) {
+        return {
+            alignment_score: 0,
+            requirements: [],
+            summary: 'No requirements parsed from spec_dir — check the path and that ' +
+                'spec.md uses "- REQ-NNN: ..." bullets.',
+        };
+    }
+    const requirements = [];
+    for (const match of result.coveredRequirements) {
+        requirements.push({
+            id: match.requirement.id,
+            status: match.confidence >= PARTIAL_CONFIDENCE_THRESHOLD ? 'covered' : 'partial',
+            evidence: { function: match.matchedFunction },
+        });
+    }
+    for (const uncovered of result.uncoveredRequirements) {
+        requirements.push({
+            id: uncovered.requirement.id,
+            status: 'uncovered',
+            evidence: {},
+        });
+    }
+    const { covered, totalRequirements, coveragePercent, undocumented } = result.summary;
+    const summary = `${covered}/${totalRequirements} requirements covered (${coveragePercent}%); ` +
+        `${undocumented} undocumented behaviors`;
+    return {
+        alignment_score: result.specAlignmentScore,
+        requirements,
+        summary,
+    };
+}
+/** Map a `SpecGapResult` to the `find_spec_drift` output shape. */
+export function toSpecDrift(result) {
+    const drifts = [];
+    for (const behavior of result.undocumentedBehaviors) {
+        drifts.push({
+            kind: 'code_without_spec',
+            location: behavior.functionName,
+            suggested_action: behavior.suggestion,
+        });
+    }
+    for (const uncovered of result.uncoveredRequirements) {
+        const { id, description } = uncovered.requirement;
+        drifts.push({
+            kind: 'spec_without_code',
+            location: id,
+            suggested_action: uncovered.reason || `Implement ${id}: ${description}`,
+        });
+    }
+    return { drifts };
+}
+//# sourceMappingURL=mappers.js.map

package/dist/mcp/mappers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mappers.js","sourceRoot":"","sources":["../../src/mcp/mappers.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,2EAA2E;AAC3E,MAAM,CAAC,MAAM,4BAA4B,GAAG,GAAG,CAAC;AAkChD,2EAA2E;AAC3E,MAAM,UAAU,mBAAmB,CAAC,MAAqB;IACvD,wEAAwE;IACxE,uEAAuE;IACvE,wEAAwE;IACxE,kEAAkE;IAClE,IAAI,MAAM,CAAC,OAAO,CAAC,iBAAiB,KAAK,CAAC,EAAE,CAAC;QAC3C,OAAO;YACL,eAAe,EAAE,CAAC;YAClB,YAAY,EAAE,EAAE;YAChB,OAAO,EACL,iEAAiE;gBACjE,wCAAwC;SAC3C,CAAC;IACJ,CAAC;IAED,MAAM,YAAY,GAAwB,EAAE,CAAC;IAE7C,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,mBAAmB,EAAE,CAAC;QAC/C,YAAY,CAAC,IAAI,CAAC;YAChB,EAAE,EAAE,KAAK,CAAC,WAAW,CAAC,EAAE;YACxB,MAAM,EAAE,KAAK,CAAC,UAAU,IAAI,4BAA4B,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS;YAChF,QAAQ,EAAE,EAAE,QAAQ,EAAE,KAAK,CAAC,eAAe,EAAE;SAC9C,CAAC,CAAC;IACL,CAAC;IAED,KAAK,MAAM,SAAS,IAAI,MAAM,CAAC,qBAAqB,EAAE,CAAC;QACrD,YAAY,CAAC,IAAI,CAAC;YAChB,EAAE,EAAE,SAAS,CAAC,WAAW,CAAC,EAAE;YAC5B,MAAM,EAAE,WAAW;YACnB,QAAQ,EAAE,EAAE;SACb,CAAC,CAAC;IACL,CAAC;IAED,MAAM,EAAE,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,YAAY,EAAE,GAAG,MAAM,CAAC,OAAO,CAAC;IACrF,MAAM,OAAO,GACX,GAAG,OAAO,IAAI,iBAAiB,0BAA0B,eAAe,MAAM;QAC9E,GAAG,YAAY,yBAAyB,CAAC;IAE3C,OAAO;QACL,eAAe,EAAE,MAAM,CAAC,kBAAkB;QAC1C,YAAY;QACZ,OAAO;KACR,CAAC;AACJ,CAAC;AAED,mEAAmE;AACnE,MAAM,UAAU,WAAW,CAAC,MAAqB;IAC/C,MAAM,MAAM,GAAY,EAAE,CAAC;IAE3B,KAAK,MAAM,QAAQ,IAAI,MAAM,CAAC,qBAAqB,EAAE,CAAC;QACpD,MAAM,CAAC,IAAI,CAAC;YACV,IAAI,EAAE,mBAAmB;YACzB,QAAQ,EAAE,QAAQ,CAAC,YAAY;YAC/B,gBAAgB,EAAE,QAAQ,CAAC,UAAU;SACtC,CAAC,CAAC;IACL,CAAC;IAED,KAAK,MAAM,SAAS,IAAI,MAAM,CAAC,qBAAqB,EAAE,CAAC;QACrD,MAAM,EAAE,EAAE,EAAE,WAAW,EAAE,GAAG,SAAS,CAAC,WAAW,CAAC;QAClD,MAAM,CAAC,IAAI,CAAC;YACV,IAAI,EAAE,mBAAmB;YACzB,QAAQ,EAAE,EAAE;YACZ,gBAAgB,EAAE,SAAS,CAAC,MAAM,IAAI,aAAa,EAAE,KAAK,WAAW,EAAE;SACxE,CAAC,CAAC;IACL,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,CAAC;AACpB,CAAC"}

package/dist/mcp/result.d.ts

@@ -0,0 +1,59 @@
+/**
+ * The one result shape every tool in this module returns.
+ *
+ * Each response says how it was produced: `deterministic`, or
+ * `llm: <model>` when a model contributed to it. The field is in the output
+ * schema of every tool, so a client can rely on it rather than infer it from
+ * which tool it called.
+ */
+import { z } from 'zod';
+/** No model was involved in producing the response. */
+export declare const DETERMINISTIC = "deterministic";
+/** The provenance of a response a model contributed to. */
+export declare function llmProvenance(model: string): string;
+export declare const provenanceSchema: z.ZodString;
+export interface ToolResult {
+    [key: string]: unknown;
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+    structuredContent?: Record<string, unknown>;
+    isError?: boolean;
+}
+/** A successful result: the payload plus its provenance, as text and as structured content. */
+export declare function toolResult(payload: object, provenance: string): ToolResult;
+/**
+ * A refusal: the tool was asked for something this install is not enabled
+ * for. One line, as an error result, so the caller sees why — never a quiet
+ * fall back to a different behaviour than the one requested.
+ */
+export declare function refusal(message: string): ToolResult;
+/**
+ * What a tool declares about itself in `tools/list`. A client may use these
+ * to decide whether a call needs confirmation, so they are claims to keep
+ * true: measured, per tool, before they were written down.
+ *
+ * No tool in this module writes, changes or deletes a file — in the project
+ * it is pointed at, the working directory, the home directory or the temp
+ * directory.
+ */
+export declare const READ_ONLY_LOCAL: {
+    readonly readOnlyHint: true;
+    readonly destructiveHint: false;
+    readonly idempotentHint: true;
+    /** Reads the local project and nothing else; no connection leaves the machine. */
+    readonly openWorldHint: false;
+};
+/**
+ * Read-only, but it can reach beyond the machine: a package registry, a
+ * vulnerability database, or — when asked for by name — a model endpoint.
+ * Declared for the tool as a whole even where only one argument causes it.
+ */
+export declare const READ_ONLY_NETWORK: {
+    readonly openWorldHint: true;
+    readonly readOnlyHint: true;
+    readonly destructiveHint: false;
+    readonly idempotentHint: true;
+};
+//# sourceMappingURL=result.d.ts.map

package/dist/mcp/result.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"result.d.ts","sourceRoot":"","sources":["../../src/mcp/result.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,uDAAuD;AACvD,eAAO,MAAM,aAAa,kBAAkB,CAAC;AAE7C,2DAA2D;AAC3D,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED,eAAO,MAAM,gBAAgB,aAE6E,CAAC;AAE3G,MAAM,WAAW,UAAU;IACzB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IACvB,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC5C,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,+FAA+F;AAC/F,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,UAAU,CAM1E;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,CAEnD;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,eAAe;;;;IAI1B,kFAAkF;;CAE1E,CAAC;AAEX;;;;GAIG;AACH,eAAO,MAAM,iBAAiB;;;;;CAGpB,CAAC"}

package/dist/mcp/result.js

@@ -0,0 +1,60 @@
+/**
+ * The one result shape every tool in this module returns.
+ *
+ * Each response says how it was produced: `deterministic`, or
+ * `llm: <model>` when a model contributed to it. The field is in the output
+ * schema of every tool, so a client can rely on it rather than infer it from
+ * which tool it called.
+ */
+import { z } from 'zod';
+/** No model was involved in producing the response. */
+export const DETERMINISTIC = 'deterministic';
+/** The provenance of a response a model contributed to. */
+export function llmProvenance(model) {
+    return `llm: ${model}`;
+}
+export const provenanceSchema = z
+    .string()
+    .describe('How this response was produced: "deterministic", or "llm: <model>" when a model contributed');
+/** A successful result: the payload plus its provenance, as text and as structured content. */
+export function toolResult(payload, provenance) {
+    const body = { ...payload, provenance };
+    return {
+        content: [{ type: 'text', text: JSON.stringify(body) }],
+        structuredContent: body,
+    };
+}
+/**
+ * A refusal: the tool was asked for something this install is not enabled
+ * for. One line, as an error result, so the caller sees why — never a quiet
+ * fall back to a different behaviour than the one requested.
+ */
+export function refusal(message) {
+    return { content: [{ type: 'text', text: message }], isError: true };
+}
+/**
+ * What a tool declares about itself in `tools/list`. A client may use these
+ * to decide whether a call needs confirmation, so they are claims to keep
+ * true: measured, per tool, before they were written down.
+ *
+ * No tool in this module writes, changes or deletes a file — in the project
+ * it is pointed at, the working directory, the home directory or the temp
+ * directory.
+ */
+export const READ_ONLY_LOCAL = {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    /** Reads the local project and nothing else; no connection leaves the machine. */
+    openWorldHint: false,
+};
+/**
+ * Read-only, but it can reach beyond the machine: a package registry, a
+ * vulnerability database, or — when asked for by name — a model endpoint.
+ * Declared for the tool as a whole even where only one argument causes it.
+ */
+export const READ_ONLY_NETWORK = {
+    ...READ_ONLY_LOCAL,
+    openWorldHint: true,
+};
+//# sourceMappingURL=result.js.map

package/dist/mcp/result.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"result.js","sourceRoot":"","sources":["../../src/mcp/result.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,uDAAuD;AACvD,MAAM,CAAC,MAAM,aAAa,GAAG,eAAe,CAAC;AAE7C,2DAA2D;AAC3D,MAAM,UAAU,aAAa,CAAC,KAAa;IACzC,OAAO,QAAQ,KAAK,EAAE,CAAC;AACzB,CAAC;AAED,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC;KAC9B,MAAM,EAAE;KACR,QAAQ,CAAC,6FAA6F,CAAC,CAAC;AAS3G,+FAA+F;AAC/F,MAAM,UAAU,UAAU,CAAC,OAAe,EAAE,UAAkB;IAC5D,MAAM,IAAI,GAAG,EAAE,GAAG,OAAO,EAAE,UAAU,EAAE,CAAC;IACxC,OAAO;QACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC;QACvD,iBAAiB,EAAE,IAAI;KACxB,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,OAAO,CAAC,OAAe;IACrC,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;AACvE,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,YAAY,EAAE,IAAI;IAClB,eAAe,EAAE,KAAK;IACtB,cAAc,EAAE,IAAI;IACpB,kFAAkF;IAClF,aAAa,EAAE,KAAK;CACZ,CAAC;AAEX;;;;GAIG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,GAAG,eAAe;IAClB,aAAa,EAAE,IAAI;CACX,CAAC"}

package/dist/mcp/tools/check-license-compliance.d.ts

@@ -0,0 +1,11 @@
+/**
+ * check_license_compliance MCP tool (Pillar I, Workflow #2).
+ *
+ * Scans a code root for copyleft/restrictive license issues in dependencies.
+ * Supports Node.js (package.json) and Rust (Cargo.toml) ecosystems.
+ *
+ * @see https://github.com/cogniumhq/cognium-ai/issues/79
+ */
+import type { McpServer } from "@modelcontextprotocol/server";
+export declare function registerCheckLicenseCompliance(server: McpServer): void;
+//# sourceMappingURL=check-license-compliance.d.ts.map

package/dist/mcp/tools/check-license-compliance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"check-license-compliance.d.ts","sourceRoot":"","sources":["../../../src/mcp/tools/check-license-compliance.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AA4H9D,wBAAgB,8BAA8B,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAqDtE"}