@cognium-ai/mcp-server 0.1.0

package/LICENSE

@@ -0,0 +1,120 @@
+PolyForm Noncommercial License 1.0.0
+
+<https://polyformproject.org/licenses/noncommercial/1.0.0>
+
+Required Notice: Copyright (c) 2025 Cognium Labs
+
+Acceptance
+
+To obtain any license under these terms, you must agree to them as both
+strict obligations and conditions to all your licenses.
+
+Copyright License
+
+The licensor grants you a copyright license for the software to do
+everything you might do with the software that would otherwise infringe
+the licensor's copyright in it for any permitted purpose. However, you
+may only distribute the software according to Distribution License and
+make changes or new works based on the software according to Changes and
+New Works License.
+
+Distribution License
+
+The licensor grants you an additional copyright license to distribute
+copies of the software. Your license to distribute covers distributing
+the software with changes and new works permitted by Changes and New
+Works License.
+
+Notices
+
+You must ensure that anyone who gets a copy of any part of the software
+from you also gets a copy of these terms or the URL for them above, as
+well as copies of any plain-text lines beginning with Required Notice:
+that the licensor provided with the software. For example:
+
+  Required Notice: Copyright (c) 2025 Cognium Labs
+
+Changes and New Works License
+
+The licensor grants you an additional copyright license to make changes
+and new works based on the software for any permitted purpose.
+
+Patent License
+
+The licensor grants you a patent license for the software that covers
+patent claims the licensor can license, or becomes able to license, that
+you would infringe by using the software.
+
+Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+Personal Uses
+
+Personal use for research, experiment, and testing for the benefit of
+public knowledge, personal study, private entertainment, hobby projects,
+amateur pursuits, or religious observance, without any anticipated
+commercial application, is use for a permitted purpose.
+
+Noncommercial Organizations
+
+Use by any charitable organization, educational institution, public
+research organization, public safety or health organization,
+environmental protection organization, or government institution is use
+for a permitted purpose regardless of the source of funding or
+obligations resulting from the funding.
+
+Fair Use
+
+You may have "fair use" rights for the software under the law. These
+terms do not limit them.
+
+No Other Rights
+
+These terms do not allow you to sublicense or transfer any of your
+licenses to anyone else, or prevent the licensor from granting licenses
+to anyone else. These terms do not imply any other licenses.
+
+Patent Defense
+
+If you make any written claim that the software infringes or contributes
+to infringement of any patent, your patent license for the software
+granted under these terms ends immediately. If your company makes such a
+claim, your patent license ends immediately for work on behalf of your
+company.
+
+Violations
+
+The first time you are notified in writing that you have violated any of
+these terms, or done anything with the software not covered by your
+licenses, your licenses can nonetheless continue if you come into full
+compliance with these terms, and take practical steps to correct past
+violations, within 32 days of receiving notice. Otherwise, all your
+licenses end immediately.
+
+No Liability
+
+As far as the law allows, the software comes as is, without any warranty
+or condition, and the licensor will not be liable to you for any damages
+arising out of these terms or the use or nature of the software, under
+any kind of legal claim.
+
+Definitions
+
+The licensor is the individual or entity offering these terms, and the
+software is the software the licensor makes available under these terms.
+
+You refers to the individual or entity agreeing to these terms.
+
+Your company is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control
+over, are under the control of, or are under common control with that
+organization. Control means ownership of substantially all the assets of
+an entity, or the power to direct its management and policies by vote,
+contract, or otherwise. Control can be direct or indirect.
+
+Your licenses are all the licenses granted to you for the software under
+these terms.
+
+Use means anything you do with the software requiring one of your
+licenses.

package/README.md

@@ -0,0 +1,154 @@
+# @cognium-ai/mcp-server
+
+An [MCP](https://modelcontextprotocol.io) server exposing Cognium's
+spec-conformance, spec-drift, and pattern-search tools over **stdio**. Backed
+by the [`circle-ir-ai`](https://www.npmjs.com/package/circle-ir-ai) engine's
+`analyzeSpecGap`.
+
+## Install & run
+
+```bash
+npm install -g @cognium-ai/mcp-server
+cognium-mcp          # speaks MCP JSON-RPC over stdin/stdout
+```
+
+Or wire it into an MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "cognium": {
+      "command": "npx",
+      "args": ["-y", "@cognium-ai/mcp-server"]
+    }
+  }
+}
+```
+
+Inspect it interactively:
+
+```bash
+npx @modelcontextprotocol/inspector cognium-mcp
+```
+
+## Tools
+
+### `verify_spec_conformance`
+
+Analyze how well code conforms to its [Specifica](https://www.npmjs.com/package/circle-ir-ai)
+spec.
+
+**Input**
+
+| field       | type   | description                                   |
+|-------------|--------|-----------------------------------------------|
+| `spec_dir`  | string | Path to the `.specifica/` directory (spec.md) |
+| `code_root` | string | Path to the code root to analyze              |
+
+**Output**
+
+```jsonc
+{
+  "alignment_score": 100,           // 0–100
+  "requirements": [
+    { "id": "REQ-001", "status": "covered",   "evidence": { "function": "calculateTotal" } },
+    { "id": "REQ-002", "status": "partial",   "evidence": { "function": "applyDiscount" } },
+    { "id": "REQ-003", "status": "uncovered", "evidence": {} }
+  ],
+  "summary": "2/3 requirements covered (67%); 0 undocumented behaviors"
+}
+```
+
+`status` is derived from the engine's match confidence:
+
+- `covered` — confidence **≥ 0.7**
+- `partial` — matched but confidence **< 0.7**
+- `uncovered` — no matching code behavior
+
+> The engine has no native "partial" state; it is a boundary heuristic at
+> confidence 0.7 over the engine's already-filtered match set
+> (min confidence 0.3).
+
+### `find_spec_drift`
+
+Report drift in both directions.
+
+**Input:** same as above (`spec_dir`, `code_root`).
+
+**Output**
+
+```jsonc
+{
+  "drifts": [
+    { "kind": "code_without_spec", "location": "deleteUser",  "suggested_action": "Document deleteUser: ..." },
+    { "kind": "spec_without_code", "location": "REQ-004",     "suggested_action": "Implement REQ-004: ..." }
+  ]
+}
+```
+
+- `code_without_spec` — an undocumented public behavior (engine
+  `undocumentedBehaviors`).
+- `spec_without_code` — a requirement with no matching code (engine
+  `uncoveredRequirements`).
+
+### `find_pattern`
+
+Search file contents under a code root with a JavaScript regular expression.
+
+**Input**
+
+| field       | type   | description                                       |
+|-------------|--------|---------------------------------------------------|
+| `pattern`   | string | JS `RegExp` source (applied with the global flag) |
+| `code_root` | string | Path to the code root to search                   |
+
+**Output**
+
+```jsonc
+{
+  "matches": [
+    { "file": "src/cart.ts", "span": [3, 3], "snippet": "return price * quantity;" }
+  ]
+}
+```
+
+> `span` is **line-based** `[startLine, endLine]` (1-based), **not** character
+> offsets. Binary/large files (> 1 MiB) and common build/vendor directories are
+> skipped; results are capped at 1000 matches.
+
+## Field mapping (engine → MCP boundary)
+
+The engine emits camelCase; this server renames to snake_case at the boundary.
+
+| MCP field                  | engine source (`SpecGapResult`)                         |
+|----------------------------|---------------------------------------------------------|
+| `alignment_score`          | `specAlignmentScore`                                    |
+| `requirements[].id`        | `coveredRequirements[].requirement.id` / `uncoveredRequirements[].requirement.id` |
+| `requirements[].status`    | derived from `coveredRequirements[].confidence` (≥0.7)  |
+| `requirements[].evidence.function` | `coveredRequirements[].matchedFunction`         |
+| `drifts` (code_without_spec) | `undocumentedBehaviors[]` → `{functionName, suggestion}` |
+| `drifts` (spec_without_code) | `uncoveredRequirements[]` → `{requirement.id, reason}`   |
+
+## Schema stability
+
+Tool input/output field names are **draft-stable through 2026-08-31**. Additive
+fields are non-breaking; renames or removals are breaking changes (major bump).
+
+## Runtime support
+
+Works under **Node** (≥18) and **Bun**. circle-ir's WASM is resolved via
+`createRequire(import.meta.url)` from `node_modules/circle-ir`, so no symlink is
+required under either runtime. Both are exercised by the CI stdio smoke matrix.
+
+## Development
+
+```bash
+npm install        # installs deps and builds (prepare → tsc)
+npm run typecheck
+npm test           # vitest: mapper unit tests
+npm run smoke      # spawn dist/index.js over stdio against the demo fixture
+```
+
+## License
+
+PolyForm Noncommercial License 1.0.0 — see [LICENSE](./LICENSE).

package/dist/analysis.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Circle-IR loading for the MCP server.
+ *
+ * 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/analysis.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analysis.d.ts","sourceRoot":"","sources":["../src/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/analysis.js

@@ -0,0 +1,45 @@
+/**
+ * Circle-IR loading for the MCP server.
+ *
+ * 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 'circle-ir-ai';
+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/analysis.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"analysis.js","sourceRoot":"","sources":["../src/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,cAAc,CAAC;AACzD,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/index.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+/**
+ * Entry point for the Cognium MCP server.
+ *
+ * Connects the server to stdio so MCP clients (e.g. cognium-code) can spawn
+ * it as a subprocess and communicate over stdin/stdout.
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;GAKG"}

package/dist/index.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+/**
+ * Entry point for the Cognium MCP server.
+ *
+ * Connects the server to stdio so MCP clients (e.g. cognium-code) can spawn
+ * it as a subprocess and communicate over stdin/stdout.
+ */
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { buildServer } from './server.js';
+async function main() {
+    const server = buildServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    // Logging to stderr keeps stdout clean for the JSON-RPC stream.
+    console.error('Fatal error in cognium-mcp:', err);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;GAKG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C,KAAK,UAAU,IAAI;IACjB,MAAM,MAAM,GAAG,WAAW,EAAE,CAAC;IAC7B,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;AAClC,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IACnB,gEAAgE;IAChE,OAAO,CAAC,KAAK,CAAC,6BAA6B,EAAE,GAAG,CAAC,CAAC;IAClD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/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 'circle-ir-ai';
+/** 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/mappers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mappers.d.ts","sourceRoot":"","sources":["../src/mappers.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD,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,CA6BlF;AAED,mEAAmE;AACnE,wBAAgB,WAAW,CAAC,MAAM,EAAE,aAAa,GAAG,mBAAmB,CAqBtE"}

package/dist/mappers.js

@@ -0,0 +1,57 @@
+/**
+ * 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) {
+    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/mappers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mappers.js","sourceRoot":"","sources":["../src/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,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/server.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Builds the Cognium MCP server and registers all tools.
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function buildServer(): McpServer;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAKpE,wBAAgB,WAAW,IAAI,SAAS,CAWvC"}

package/dist/server.js

@@ -0,0 +1,18 @@
+/**
+ * Builds the Cognium MCP server and registers all tools.
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { registerVerifySpecConformance } from './tools/verify-spec-conformance.js';
+import { registerFindSpecDrift } from './tools/find-spec-drift.js';
+import { registerFindPattern } from './tools/find-pattern.js';
+export function buildServer() {
+    const server = new McpServer({
+        name: 'cognium-mcp',
+        version: '0.1.0',
+    });
+    registerVerifySpecConformance(server);
+    registerFindSpecDrift(server);
+    registerFindPattern(server);
+    return server;
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,6BAA6B,EAAE,MAAM,oCAAoC,CAAC;AACnF,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AACnE,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAE9D,MAAM,UAAU,WAAW;IACzB,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;QAC3B,IAAI,EAAE,aAAa;QACnB,OAAO,EAAE,OAAO;KACjB,CAAC,CAAC;IAEH,6BAA6B,CAAC,MAAM,CAAC,CAAC;IACtC,qBAAqB,CAAC,MAAM,CAAC,CAAC;IAC9B,mBAAmB,CAAC,MAAM,CAAC,CAAC;IAE5B,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/tools/find-pattern.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `find_pattern` MCP tool (stretch).
+ *
+ * Runs a JavaScript regular expression over the text contents of files under
+ * a code root and returns the matches with a line-based span and a snippet.
+ *
+ * NOTE: `span` is `[startLine, endLine]` (1-based, line-based — NOT character
+ * offsets). Documented in README; adaptable to char offsets additively if a
+ * consumer needs them.
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerFindPattern(server: McpServer): void;
+//# sourceMappingURL=find-pattern.d.ts.map

package/dist/tools/find-pattern.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"find-pattern.d.ts","sourceRoot":"","sources":["../../src/tools/find-pattern.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAoCzE,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CA6D3D"}

package/dist/tools/find-pattern.js

@@ -0,0 +1,91 @@
+/**
+ * `find_pattern` MCP tool (stretch).
+ *
+ * Runs a JavaScript regular expression over the text contents of files under
+ * a code root and returns the matches with a line-based span and a snippet.
+ *
+ * NOTE: `span` is `[startLine, endLine]` (1-based, line-based — NOT character
+ * offsets). Documented in README; adaptable to char offsets additively if a
+ * consumer needs them.
+ */
+import * as fs from 'fs';
+import { z } from 'zod';
+import { walkFiles } from '../walk.js';
+/** Hard cap on total matches returned across all files. */
+const MAX_MATCHES = 1000;
+const inputSchema = {
+    pattern: z.string().describe('JavaScript regular expression (applied with the global flag)'),
+    code_root: z.string().describe('Path to the code root to search'),
+};
+const outputSchema = {
+    matches: z.array(z.object({
+        file: z.string(),
+        span: z.tuple([z.number(), z.number()]),
+        snippet: z.string(),
+    })),
+};
+/** Count newlines in `text` before byte index `end`. */
+function lineAt(text, end) {
+    let line = 1;
+    for (let i = 0; i < end && i < text.length; i++) {
+        if (text[i] === '\n')
+            line++;
+    }
+    return line;
+}
+export function registerFindPattern(server) {
+    server.registerTool('find_pattern', {
+        title: 'Find Pattern',
+        description: 'Search file contents under a code root with a JavaScript regular ' +
+            'expression. Returns matches with a 1-based line span [start, end] and ' +
+            'a trimmed snippet. Skips binary/large files and common excludes.',
+        inputSchema,
+        outputSchema,
+    }, async ({ pattern, code_root }) => {
+        const matches = [];
+        const files = walkFiles(code_root);
+        for (const file of files) {
+            if (matches.length >= MAX_MATCHES)
+                break;
+            let content;
+            try {
+                content = fs.readFileSync(file.absolutePath, 'utf-8');
+            }
+            catch {
+                continue;
+            }
+            // Fresh regex per file so lastIndex state never leaks across files.
+            let re;
+            try {
+                re = new RegExp(pattern, 'g');
+            }
+            catch (err) {
+                throw new Error(`Invalid regular expression: ${err.message}`);
+            }
+            let m;
+            while ((m = re.exec(content)) !== null) {
+                const startLine = lineAt(content, m.index);
+                const matched = m[0];
+                const newlines = (matched.match(/\n/g) ?? []).length;
+                const endLine = startLine + newlines;
+                const snippet = matched.split('\n')[0].trim();
+                matches.push({
+                    file: file.relativePath,
+                    span: [startLine, endLine],
+                    snippet,
+                });
+                if (matches.length >= MAX_MATCHES)
+                    break;
+                // Guard against zero-width matches looping forever.
+                if (m.index === re.lastIndex)
+                    re.lastIndex++;
+            }
+        }
+        const payload = { matches };
+        return {
+            content: [{ type: 'text', text: JSON.stringify(payload) }],
+            structuredContent: payload,
+        };
+    });
+}
+//# sourceMappingURL=find-pattern.js.map

package/dist/tools/find-pattern.js.map

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

package/dist/tools/find-spec-drift.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `find_spec_drift` MCP tool.
+ *
+ * Reports drift between code and spec: code paths with no matching
+ * requirement (code_without_spec) and requirements with no matching code
+ * (spec_without_code), each with a suggested remediation.
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerFindSpecDrift(server: McpServer): void;
+//# sourceMappingURL=find-spec-drift.d.ts.map

package/dist/tools/find-spec-drift.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"find-spec-drift.d.ts","sourceRoot":"","sources":["../../src/tools/find-spec-drift.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAoBzE,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAsB7D"}

package/dist/tools/find-spec-drift.js

@@ -0,0 +1,41 @@
+/**
+ * `find_spec_drift` MCP tool.
+ *
+ * Reports drift between code and spec: code paths with no matching
+ * requirement (code_without_spec) and requirements with no matching code
+ * (spec_without_code), each with a suggested remediation.
+ */
+import { z } from 'zod';
+import { analyzeSpecGap } from 'circle-ir-ai';
+import { loadCircleIR } from '../analysis.js';
+import { toSpecDrift } from '../mappers.js';
+const inputSchema = {
+    spec_dir: z.string().describe('Path to the .specifica/ directory containing spec.md'),
+    code_root: z.string().describe('Path to the code root to analyze'),
+};
+const outputSchema = {
+    drifts: z.array(z.object({
+        kind: z.enum(['code_without_spec', 'spec_without_code']),
+        location: z.string(),
+        suggested_action: z.string(),
+    })),
+};
+export function registerFindSpecDrift(server) {
+    server.registerTool('find_spec_drift', {
+        title: 'Find Spec Drift',
+        description: 'Find drift between code and spec: undocumented behaviors ' +
+            '(code_without_spec) and unimplemented requirements ' +
+            '(spec_without_code), each with a suggested action.',
+        inputSchema,
+        outputSchema,
+    }, async ({ spec_dir, code_root }) => {
+        const { codePath, results } = await loadCircleIR(code_root);
+        const specGap = await analyzeSpecGap(codePath, results, { specDir: spec_dir });
+        const payload = toSpecDrift(specGap);
+        return {
+            content: [{ type: 'text', text: JSON.stringify(payload) }],
+            structuredContent: payload,
+        };
+    });
+}
+//# sourceMappingURL=find-spec-drift.js.map

package/dist/tools/find-spec-drift.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"find-spec-drift.js","sourceRoot":"","sources":["../../src/tools/find-spec-drift.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAE5C,MAAM,WAAW,GAAG;IAClB,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,sDAAsD,CAAC;IACrF,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,kCAAkC,CAAC;CACnE,CAAC;AAEF,MAAM,YAAY,GAAG;IACnB,MAAM,EAAE,CAAC,CAAC,KAAK,CACb,CAAC,CAAC,MAAM,CAAC;QACP,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,mBAAmB,EAAE,mBAAmB,CAAC,CAAC;QACxD,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;QACpB,gBAAgB,EAAE,CAAC,CAAC,MAAM,EAAE;KAC7B,CAAC,CACH;CACF,CAAC;AAEF,MAAM,UAAU,qBAAqB,CAAC,MAAiB;IACrD,MAAM,CAAC,YAAY,CACjB,iBAAiB,EACjB;QACE,KAAK,EAAE,iBAAiB;QACxB,WAAW,EACT,2DAA2D;YAC3D,qDAAqD;YACrD,oDAAoD;QACtD,WAAW;QACX,YAAY;KACb,EACD,KAAK,EAAE,EAAE,QAAQ,EAAE,SAAS,EAAE,EAAE,EAAE;QAChC,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,MAAM,YAAY,CAAC,SAAS,CAAC,CAAC;QAC5D,MAAM,OAAO,GAAG,MAAM,cAAc,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,CAAC;QAC/E,MAAM,OAAO,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC;QACrC,OAAO;YACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC;YAC1D,iBAAiB,EAAE,OAA6C;SACjE,CAAC;IACJ,CAAC,CACF,CAAC;AACJ,CAAC"}

package/dist/tools/verify-spec-conformance.d.ts

@@ -0,0 +1,9 @@
+/**
+ * `verify_spec_conformance` MCP tool.
+ *
+ * Runs spec-gap analysis over a code root against a Specifica spec directory
+ * and reports an alignment score plus per-requirement coverage status.
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerVerifySpecConformance(server: McpServer): void;
+//# sourceMappingURL=verify-spec-conformance.d.ts.map

package/dist/tools/verify-spec-conformance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify-spec-conformance.d.ts","sourceRoot":"","sources":["../../src/tools/verify-spec-conformance.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AA8BzE,wBAAgB,6BAA6B,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAsBrE"}

package/dist/tools/verify-spec-conformance.js

@@ -0,0 +1,49 @@
+/**
+ * `verify_spec_conformance` MCP tool.
+ *
+ * Runs spec-gap analysis over a code root against a Specifica spec directory
+ * and reports an alignment score plus per-requirement coverage status.
+ */
+import { z } from 'zod';
+import { analyzeSpecGap } from 'circle-ir-ai';
+import { loadCircleIR } from '../analysis.js';
+import { toVerifyConformance } from '../mappers.js';
+const inputSchema = {
+    spec_dir: z.string().describe('Path to the .specifica/ directory containing spec.md'),
+    code_root: z.string().describe('Path to the code root to analyze'),
+};
+const evidenceSchema = z
+    .object({
+    function: z.string().optional(),
+    file: z.string().optional(),
+    span: z.tuple([z.number(), z.number()]).optional(),
+})
+    .passthrough();
+const outputSchema = {
+    alignment_score: z.number(),
+    requirements: z.array(z.object({
+        id: z.string(),
+        status: z.enum(['covered', 'partial', 'uncovered']),
+        evidence: evidenceSchema,
+    })),
+    summary: z.string(),
+};
+export function registerVerifySpecConformance(server) {
+    server.registerTool('verify_spec_conformance', {
+        title: 'Verify Spec Conformance',
+        description: 'Analyze how well code conforms to its Specifica spec. Returns an ' +
+            'alignment score (0-100) and per-requirement coverage status ' +
+            '(covered/partial/uncovered). "partial" = matched with confidence < 0.7.',
+        inputSchema,
+        outputSchema,
+    }, async ({ spec_dir, code_root }) => {
+        const { codePath, results } = await loadCircleIR(code_root);
+        const specGap = await analyzeSpecGap(codePath, results, { specDir: spec_dir });
+        const payload = toVerifyConformance(specGap);
+        return {
+            content: [{ type: 'text', text: JSON.stringify(payload) }],
+            structuredContent: payload,
+        };
+    });
+}
+//# sourceMappingURL=verify-spec-conformance.js.map

package/dist/tools/verify-spec-conformance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify-spec-conformance.js","sourceRoot":"","sources":["../../src/tools/verify-spec-conformance.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAEpD,MAAM,WAAW,GAAG;IAClB,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,sDAAsD,CAAC;IACrF,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,kCAAkC,CAAC;CACnE,CAAC;AAEF,MAAM,cAAc,GAAG,CAAC;KACrB,MAAM,CAAC;IACN,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC/B,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC3B,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,QAAQ,EAAE;CACnD,CAAC;KACD,WAAW,EAAE,CAAC;AAEjB,MAAM,YAAY,GAAG;IACnB,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE;IAC3B,YAAY,EAAE,CAAC,CAAC,KAAK,CACnB,CAAC,CAAC,MAAM,CAAC;QACP,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE;QACd,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,SAAS,EAAE,WAAW,CAAC,CAAC;QACnD,QAAQ,EAAE,cAAc;KACzB,CAAC,CACH;IACD,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;CACpB,CAAC;AAEF,MAAM,UAAU,6BAA6B,CAAC,MAAiB;IAC7D,MAAM,CAAC,YAAY,CACjB,yBAAyB,EACzB;QACE,KAAK,EAAE,yBAAyB;QAChC,WAAW,EACT,mEAAmE;YACnE,8DAA8D;YAC9D,yEAAyE;QAC3E,WAAW;QACX,YAAY;KACb,EACD,KAAK,EAAE,EAAE,QAAQ,EAAE,SAAS,EAAE,EAAE,EAAE;QAChC,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,MAAM,YAAY,CAAC,SAAS,CAAC,CAAC;QAC5D,MAAM,OAAO,GAAG,MAAM,cAAc,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,CAAC;QAC/E,MAAM,OAAO,GAAG,mBAAmB,CAAC,OAAO,CAAC,CAAC;QAC7C,OAAO;YACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC;YAC1D,iBAAiB,EAAE,OAA6C;SACjE,CAAC;IACJ,CAAC,CACF,CAAC;AACJ,CAAC"}

package/dist/walk.d.ts

@@ -0,0 +1,33 @@
+/**
+ * File walker for the MCP server.
+ *
+ * Recursively collects files under a root directory, applying default and
+ * caller-supplied exclude globs via `minimatch` (per the repo convention of
+ * never hand-rolling glob translation). Language detection is delegated to
+ * circle-ir's `detectLanguage`.
+ */
+import { type SupportedLanguage } from 'circle-ir';
+/** Directories/patterns excluded by default for every walk. */
+export declare const DEFAULT_EXCLUDES: string[];
+export interface WalkOptions {
+    /** Additional exclude globs (matched against the path relative to root). */
+    exclude?: string[];
+    /** Hard cap on number of files returned. Default 5000. */
+    maxFiles?: number;
+    /** Skip files larger than this many bytes. Default 1 MiB. */
+    maxFileBytes?: number;
+}
+export interface WalkedFile {
+    /** Absolute path. */
+    absolutePath: string;
+    /** Path relative to the walk root (used for matching/snippets). */
+    relativePath: string;
+}
+export interface SourceFile extends WalkedFile {
+    language: SupportedLanguage;
+}
+/** Walk all (non-excluded, size-bounded) files under `root`. */
+export declare function walkFiles(root: string, options?: WalkOptions): WalkedFile[];
+/** Walk and keep only files whose language circle-ir can detect. */
+export declare function collectSourceFiles(root: string, options?: WalkOptions): SourceFile[];
+//# sourceMappingURL=walk.d.ts.map

package/dist/walk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"walk.d.ts","sourceRoot":"","sources":["../src/walk.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,OAAO,EAAkB,KAAK,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAEnE,+DAA+D;AAC/D,eAAO,MAAM,gBAAgB,UAS5B,CAAC;AAEF,MAAM,WAAW,WAAW;IAC1B,4EAA4E;IAC5E,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,0DAA0D;IAC1D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6DAA6D;IAC7D,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,UAAU;IACzB,qBAAqB;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,mEAAmE;IACnE,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,UAAW,SAAQ,UAAU;IAC5C,QAAQ,EAAE,iBAAiB,CAAC;CAC7B;AAED,gEAAgE;AAChE,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,UAAU,EAAE,CA6C/E;AAED,oEAAoE;AACpE,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,UAAU,EAAE,CAUxF"}

package/dist/walk.js

@@ -0,0 +1,83 @@
+/**
+ * File walker for the MCP server.
+ *
+ * Recursively collects files under a root directory, applying default and
+ * caller-supplied exclude globs via `minimatch` (per the repo convention of
+ * never hand-rolling glob translation). Language detection is delegated to
+ * circle-ir's `detectLanguage`.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { minimatch } from 'minimatch';
+import { detectLanguage } from 'circle-ir';
+/** Directories/patterns excluded by default for every walk. */
+export const DEFAULT_EXCLUDES = [
+    '**/node_modules/**',
+    '**/dist/**',
+    '**/build/**',
+    '**/.git/**',
+    '**/coverage/**',
+    '**/*.min.js',
+    '**/*.min.css',
+    '**/.specifica/**',
+];
+/** Walk all (non-excluded, size-bounded) files under `root`. */
+export function walkFiles(root, options = {}) {
+    const excludes = [...DEFAULT_EXCLUDES, ...(options.exclude ?? [])];
+    const maxFiles = options.maxFiles ?? 5000;
+    const maxFileBytes = options.maxFileBytes ?? 1024 * 1024;
+    const out = [];
+    const rootStat = fs.statSync(root);
+    if (rootStat.isFile()) {
+        return [{ absolutePath: path.resolve(root), relativePath: path.basename(root) }];
+    }
+    const stack = [root];
+    while (stack.length > 0 && out.length < maxFiles) {
+        const dir = stack.pop();
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            const absolutePath = path.join(dir, entry.name);
+            const relativePath = path.relative(root, absolutePath);
+            const isExcluded = excludes.some((p) => minimatch(relativePath, p, { dot: true }));
+            if (isExcluded)
+                continue;
+            if (entry.isDirectory()) {
+                stack.push(absolutePath);
+            }
+            else if (entry.isFile()) {
+                let size = 0;
+                try {
+                    size = fs.statSync(absolutePath).size;
+                }
+                catch {
+                    continue;
+                }
+                if (size > maxFileBytes)
+                    continue;
+                out.push({ absolutePath, relativePath });
+                if (out.length >= maxFiles)
+                    break;
+            }
+        }
+    }
+    return out;
+}
+/** Walk and keep only files whose language circle-ir can detect. */
+export function collectSourceFiles(root, options = {}) {
+    const files = walkFiles(root, options);
+    const sources = [];
+    for (const f of files) {
+        const language = detectLanguage(f.absolutePath);
+        if (language) {
+            sources.push({ ...f, language });
+        }
+    }
+    return sources;
+}
+//# sourceMappingURL=walk.js.map

package/dist/walk.js.map

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

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@cognium-ai/mcp-server",
+  "version": "0.1.0",
+  "description": "MCP server exposing Cognium spec-conformance, spec-drift, and pattern-search tools over stdio",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "cognium-mcp": "dist/index.js"
+  },
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm run build",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "smoke": "node test/smoke-stdio.mjs",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "sast",
+    "specifica",
+    "spec-conformance",
+    "cognium"
+  ],
+  "author": {
+    "name": "Cognium Labs",
+    "url": "https://cognium.net"
+  },
+  "license": "PolyForm-Noncommercial-1.0.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "circle-ir": "^3.23.3",
+    "circle-ir-ai": "^2.7.19",
+    "minimatch": "^10.2.5",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "tsx": "^4.21.0",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.3"
+  }
+}