@cognium/mcp-server 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+All notable changes to `@cognium/mcp-server` are documented in this file.
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-07-15
+
+### Added
+
+- Initial MVP of the Model Context Protocol server for circle-ir.
+- Stdio transport (default) for Claude Desktop / Claude Code / Cursor.
+- `ProjectCache` with mtime-based invalidation and LRU eviction (cap 3
+  concurrent project analyses).
+- 11 tools exposing SAST capabilities to LLM clients:
+  - `scan` — run full circle-ir analysis on a file or directory.
+  - `explain_finding` — CWE metadata + remediation guidance for a single
+    finding.
+  - `taint_paths` — list cross-file taint flows with optional filters.
+  - `list_entry_points` — enumerate Tier-1 attacker-reachable methods.
+  - `check_sanitizer` — verify a function is a known sanitizer for a
+    sink type.
+  - `describe_sink` — metadata about a sink category (CWE, severity,
+    remediation).
+  - `describe_source` — metadata about a taint source category.
+  - `attack_surface_summary` — one-shot codebase attack-surface report.
+  - `list_reachable_sinks` — BFS from an entry point to reachable sinks.
+  - `find_similar` — cluster findings by shape for bulk triage.
+  - `refresh` — invalidate the cache for specific files or the entire
+    project.
+- 5 read-only resources:
+  - `cognium://sast-finding-schema`
+  - `cognium://sink-catalog`
+  - `cognium://source-catalog`
+  - `cognium://sanitizer-catalog`
+  - `cognium://passes`
+- Size-bounded serialization (findings capped at 500 per response,
+  string fields truncated at 2 KB, IR graphs omitted).
+- No changes to circle-ir engine — MCP is a strictly additive wrapper.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Cognium Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,107 @@
+# @cognium/mcp-server
+
+Model Context Protocol (MCP) server exposing the [circle-ir](https://www.npmjs.com/package/circle-ir) SAST engine as a set of structured tools and reference resources for LLM agents (Claude Desktop, Claude Code, Cursor, cognium-ai).
+
+Ships every deterministic capability of circle-ir — polyglot taint analysis, cross-file taint paths, entry-point enumeration, CWE metadata, sanitizer lookups — as MCP tool calls that an LLM can chain without ever guessing at the SAST engine's internal state.
+
+- **Zero LLM in the analysis path.** Every finding this server returns comes from the deterministic circle-ir pipeline. LLM-side reasoning is fed by these tools; it does not decide them.
+- **Cache-first.** The server holds up to 3 recent project analyses in memory, keyed by option-set and invalidated by file `mtime`. Repeated tool calls on the same project are effectively free.
+- **Size-bounded output.** Findings, taint paths, and snippets are truncated at safe defaults so a single tool call cannot blow past a client context window.
+
+## Install
+
+```bash
+npm install -g @cognium/mcp-server
+```
+
+Or run in-place from this monorepo:
+
+```bash
+cd packages/mcp-server
+npm run build
+node dist/index.js
+```
+
+## Client configuration
+
+### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "cognium": {
+      "command": "npx",
+      "args": ["-y", "@cognium/mcp-server"]
+    }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add cognium -- npx -y @cognium/mcp-server
+```
+
+### Cursor
+
+Add to `~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "cognium": {
+      "command": "npx",
+      "args": ["-y", "@cognium/mcp-server"]
+    }
+  }
+}
+```
+
+## Tools
+
+| Tool | Purpose |
+| ---- | ------- |
+| `scan` | Run the full polyglot SAST pipeline on a file or directory. Returns SastFindings + per-file taint flows + cross-file taint paths. |
+| `explain_finding` | Enrich a single finding id with CWE metadata, remediation, CVSS-like score, and sanitizer suggestions. |
+| `taint_paths` | List cross-file taint flows filtered by source file, sink file, or sink type. |
+| `list_entry_points` | Enumerate every attacker-reachable handler (HTTP routes, middlewares, event listeners) grouped by framework. |
+| `list_reachable_sinks` | List every sink of a given category that has a real taint flow reaching it (excludes lexical-only matches). |
+| `attack_surface_summary` | Roll-up: entry points × sinks × cross-file taint paths + top files by finding count. |
+| `check_sanitizer` | Deterministic yes/no on whether a function is a recognized sanitizer for a sink category. |
+| `describe_sink` | CWE, remediation, CVSS-like severity, and sanitizer list for a sink category. |
+| `describe_source` | Every framework API pattern circle-ir treats as a source of a given category. |
+| `find_similar` | Given a finding id, return other findings sharing the same `rule_id` and/or `sink_type`. |
+| `refresh` | Manually invalidate the cache for one project or every project. |
+
+## Resources
+
+| URI | Content |
+| --- | ------- |
+| `cognium://sast-finding-schema` | JSON Schema for `SastFinding` |
+| `cognium://sink-catalog` | Every taint sink pattern known to circle-ir |
+| `cognium://source-catalog` | Every taint source pattern |
+| `cognium://sanitizer-catalog` | Every sanitizer entry, indexed by sink type |
+| `cognium://passes` | Contents of circle-ir `docs/PASSES.md` — canonical pass registry |
+
+## Suggested tool-call flow
+
+1. `scan` on the project root to prime the cache and get a summary.
+2. `attack_surface_summary` for a security-posture overview.
+3. Iterate over the highest-severity findings with `explain_finding` for CWE context.
+4. `find_similar` to catch the same pattern elsewhere.
+5. Before proposing a fix, `check_sanitizer` any proposed wrapper against the target sink type.
+
+## Development
+
+```bash
+npm run build       # tsc + chmod +x dist/index.js
+npm run typecheck   # tsc --noEmit
+npm test            # vitest run (unit + smoke)
+```
+
+## License
+
+MIT

package/dist/cache.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Project-scoped analysis cache.
+ *
+ * A long-lived MCP process holds one `ProjectAnalysis` per active project
+ * root. Invalidation is mtime-based: on each request we re-index file
+ * mtimes and re-run `analyzeProject` only if any file changed. LRU
+ * eviction keeps memory bounded when the LLM hops between projects.
+ */
+import { type ProjectAnalysis } from 'circle-ir';
+/**
+ * Per-project analysis options that participate in the cache key. Two
+ * scans with different profiles / disabled passes must not share a cache
+ * entry.
+ */
+export interface ProjectScanOptions {
+    /** Force analysis of a single language. */
+    language?: string;
+    /** Circle-IR disabled passes (e.g. ['naming-convention']). */
+    disabledPasses?: string[];
+    /** Cross-file phase wall-time budget in ms. 0 = unlimited. */
+    crossFileBudgetMs?: number;
+}
+export declare class ProjectCache {
+    private entries;
+    private readonly capacity;
+    constructor(capacity?: number);
+    private cacheKey;
+    /**
+     * Return a cached analysis if fresh, else run `analyzeProject`. The
+     * boolean `cacheHit` in the return value lets tools surface cache
+     * behaviour to callers.
+     */
+    getOrCompute(projectRoot: string, opts: ProjectScanOptions): Promise<{
+        analysis: ProjectAnalysis;
+        cacheHit: boolean;
+        analysisMs: number;
+        fileCount: number;
+    }>;
+    /** Invalidate one specific project (all option-keys) or one specific key. */
+    invalidate(projectRoot: string, opts?: ProjectScanOptions): number;
+    /** Invalidate every cached project. */
+    clear(): number;
+    size(): number;
+    private evictLRU;
+}
+//# sourceMappingURL=cache.d.ts.map

package/dist/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAkB,KAAK,eAAe,EAAE,MAAM,WAAW,CAAC;AAIjE;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,8DAA8D;IAC9D,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,8DAA8D;IAC9D,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAmBD,qBAAa,YAAY;IACvB,OAAO,CAAC,OAAO,CAAiC;IAChD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;gBAEtB,QAAQ,SAAI;IAIxB,OAAO,CAAC,QAAQ;IAIhB;;;;OAIG;IACG,YAAY,CAChB,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,kBAAkB,GACvB,OAAO,CAAC;QAAE,QAAQ,EAAE,eAAe,CAAC;QAAC,QAAQ,EAAE,OAAO,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IA6CnG,6EAA6E;IAC7E,UAAU,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,kBAAkB,GAAG,MAAM;IAgBlE,uCAAuC;IACvC,KAAK,IAAI,MAAM;IAMf,IAAI,IAAI,MAAM;IAId,OAAO,CAAC,QAAQ;CAOjB"}

package/dist/cache.js

@@ -0,0 +1,106 @@
+/**
+ * Project-scoped analysis cache.
+ *
+ * A long-lived MCP process holds one `ProjectAnalysis` per active project
+ * root. Invalidation is mtime-based: on each request we re-index file
+ * mtimes and re-run `analyzeProject` only if any file changed. LRU
+ * eviction keeps memory bounded when the LLM hops between projects.
+ */
+import { resolve } from 'path';
+import { analyzeProject } from 'circle-ir';
+import { collectFiles, indexMtimes, mtimesEqual } from './util/files.js';
+import { ensureAnalyzer } from './util/wasm.js';
+function optionsKey(opts) {
+    const parts = [
+        `lang=${opts.language ?? '*'}`,
+        `disabled=${(opts.disabledPasses ?? []).slice().sort().join(',')}`,
+        `budget=${opts.crossFileBudgetMs ?? 'default'}`,
+    ];
+    return parts.join('|');
+}
+export class ProjectCache {
+    entries = new Map();
+    capacity;
+    constructor(capacity = 3) {
+        this.capacity = capacity;
+    }
+    cacheKey(projectRoot, opts) {
+        return `${resolve(projectRoot)}::${optionsKey(opts)}`;
+    }
+    /**
+     * Return a cached analysis if fresh, else run `analyzeProject`. The
+     * boolean `cacheHit` in the return value lets tools surface cache
+     * behaviour to callers.
+     */
+    async getOrCompute(projectRoot, opts) {
+        await ensureAnalyzer();
+        const absRoot = resolve(projectRoot);
+        const key = this.cacheKey(absRoot, opts);
+        const existing = this.entries.get(key);
+        const langOpt = opts.language;
+        const currentMtimes = indexMtimes(absRoot, langOpt ? { language: langOpt } : {});
+        if (existing && mtimesEqual(existing.mtimes, currentMtimes)) {
+            // Touch for LRU: re-insert to move to the end of the Map's iteration order.
+            this.entries.delete(key);
+            this.entries.set(key, existing);
+            return {
+                analysis: existing.analysis,
+                cacheHit: true,
+                analysisMs: existing.analysisMs,
+                fileCount: currentMtimes.size,
+            };
+        }
+        const files = collectFiles(absRoot, langOpt ? { language: langOpt } : {});
+        const t0 = Date.now();
+        const analysis = await analyzeProject(files.map(f => ({ code: f.code, filePath: f.filePath, language: f.language })), {
+            ...(opts.disabledPasses ? { disabledPasses: opts.disabledPasses } : {}),
+            ...(opts.crossFileBudgetMs !== undefined ? { crossFileBudgetMs: opts.crossFileBudgetMs } : {}),
+        });
+        const analysisMs = Date.now() - t0;
+        const entry = {
+            key,
+            analysis,
+            mtimes: currentMtimes,
+            computedAt: Date.now(),
+            analysisMs,
+        };
+        this.entries.set(key, entry);
+        this.evictLRU();
+        return { analysis, cacheHit: false, analysisMs, fileCount: files.length };
+    }
+    /** Invalidate one specific project (all option-keys) or one specific key. */
+    invalidate(projectRoot, opts) {
+        const abs = resolve(projectRoot);
+        let removed = 0;
+        if (opts) {
+            if (this.entries.delete(this.cacheKey(abs, opts)))
+                removed++;
+            return removed;
+        }
+        for (const key of [...this.entries.keys()]) {
+            if (key.startsWith(abs + '::')) {
+                this.entries.delete(key);
+                removed++;
+            }
+        }
+        return removed;
+    }
+    /** Invalidate every cached project. */
+    clear() {
+        const n = this.entries.size;
+        this.entries.clear();
+        return n;
+    }
+    size() {
+        return this.entries.size;
+    }
+    evictLRU() {
+        while (this.entries.size > this.capacity) {
+            const oldestKey = this.entries.keys().next().value;
+            if (oldestKey === undefined)
+                break;
+            this.entries.delete(oldestKey);
+        }
+    }
+}
+//# sourceMappingURL=cache.js.map

package/dist/cache.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+/**
+ * Entry point for the `@cognium/mcp-server` binary. Wires the MCP
+ * server to stdio transport — the transport every MCP client (Claude
+ * Desktop, Claude Code, Cursor) speaks by default.
+ *
+ * WASM initialization is deferred to first tool invocation so that
+ * `mcp-server-cognium-dev --version` and the initial handshake do not
+ * pay the ~200ms tree-sitter cost.
+ */
+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;;;;;;;;GAQG"}

package/dist/index.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+/**
+ * Entry point for the `@cognium/mcp-server` binary. Wires the MCP
+ * server to stdio transport — the transport every MCP client (Claude
+ * Desktop, Claude Code, Cursor) speaks by default.
+ *
+ * WASM initialization is deferred to first tool invocation so that
+ * `mcp-server-cognium-dev --version` and the initial handshake do not
+ * pay the ~200ms tree-sitter cost.
+ */
+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) => {
+    // stderr is safe for stdio-transport servers (stdout is reserved for
+    // MCP messages).
+    process.stderr.write(`[mcp-server-cognium-dev] fatal: ${err.stack ?? err}\n`);
+    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;;;;;;;;GAQG;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,qEAAqE;IACrE,iBAAiB;IACjB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,mCAAoC,GAAa,CAAC,KAAK,IAAI,GAAG,IAAI,CAAC,CAAC;IACzF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/resources/catalogs.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Catalog loaders — expose circle-ir's embedded taint sources / sinks /
+ * sanitizers in a shape that MCP tools and resources can consume.
+ *
+ * We deliberately re-export the in-memory `DEFAULT_*` arrays from
+ * `circle-ir` rather than reading the YAML/JSON config files off disk.
+ * The defaults are the exact source of truth used at analysis time and
+ * are always in sync with the installed version of the analyzer.
+ */
+import { type SinkType, type SourceType } from 'circle-ir';
+/**
+ * Normalized sanitizer catalog entry consumed by `check_sanitizer` and
+ * `describe_sink` tools.
+ */
+export interface SanitizerCatalogEntry {
+    /** Function / method names or `Class.method` combos that neutralize taint. */
+    patterns: string[];
+    /**
+     * Restrict this entry to a specific sink category. `undefined` means the
+     * sanitizer applies to every sink type it covers (`removes` list).
+     */
+    sinkType?: string;
+    /** Optional language restriction (not currently distinguished in defaults). */
+    language?: string;
+    /** Provenance label — always `circle-ir:default` for embedded defaults. */
+    source: string;
+    /** Free-form note from the underlying pattern definition. */
+    note?: string;
+}
+export interface SinkCatalogEntry {
+    method: string;
+    class?: string;
+    type: SinkType;
+    cwe: string;
+    severity: string;
+    argPositions: number[];
+    languages?: string[];
+    note?: string;
+}
+export interface SourceCatalogEntry {
+    method?: string;
+    class?: string;
+    property?: string;
+    object?: string;
+    annotation?: string;
+    methodAnnotation?: string;
+    type: SourceType;
+    severity: string;
+    returnTainted?: boolean;
+    paramTainted?: boolean;
+    propertyTainted?: boolean;
+    languages?: string[];
+    note?: string;
+}
+/**
+ * Return the normalized sanitizer catalog. One catalog entry is produced
+ * per `<pattern, sink-type>` combination so downstream filters can match
+ * on `sinkType` cheaply.
+ */
+export declare function loadSanitizerCatalog(): SanitizerCatalogEntry[];
+export declare function loadSinkCatalog(): SinkCatalogEntry[];
+export declare function loadSourceCatalog(): SourceCatalogEntry[];
+//# sourceMappingURL=catalogs.d.ts.map

package/dist/resources/catalogs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalogs.d.ts","sourceRoot":"","sources":["../../src/resources/catalogs.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAIL,KAAK,QAAQ,EACb,KAAK,UAAU,EAChB,MAAM,WAAW,CAAC;AAEnB;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,8EAA8E;IAC9E,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,2EAA2E;IAC3E,MAAM,EAAE,MAAM,CAAC;IACf,6DAA6D;IAC7D,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,QAAQ,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAMD;;;;GAIG;AACH,wBAAgB,oBAAoB,IAAI,qBAAqB,EAAE,CAiC9D;AAED,wBAAgB,eAAe,IAAI,gBAAgB,EAAE,CAapD;AAED,wBAAgB,iBAAiB,IAAI,kBAAkB,EAAE,CAkBxD"}

package/dist/resources/catalogs.js

@@ -0,0 +1,92 @@
+/**
+ * Catalog loaders — expose circle-ir's embedded taint sources / sinks /
+ * sanitizers in a shape that MCP tools and resources can consume.
+ *
+ * We deliberately re-export the in-memory `DEFAULT_*` arrays from
+ * `circle-ir` rather than reading the YAML/JSON config files off disk.
+ * The defaults are the exact source of truth used at analysis time and
+ * are always in sync with the installed version of the analyzer.
+ */
+import { DEFAULT_SANITIZERS, DEFAULT_SOURCES, DEFAULT_SINKS, } from 'circle-ir';
+let sanitizerCache = null;
+let sinkCache = null;
+let sourceCache = null;
+/**
+ * Return the normalized sanitizer catalog. One catalog entry is produced
+ * per `<pattern, sink-type>` combination so downstream filters can match
+ * on `sinkType` cheaply.
+ */
+export function loadSanitizerCatalog() {
+    if (sanitizerCache)
+        return sanitizerCache;
+    const entries = [];
+    for (const s of DEFAULT_SANITIZERS) {
+        const patterns = [];
+        if (s.method && s.class)
+            patterns.push(`${s.class}.${s.method}`);
+        if (s.method)
+            patterns.push(s.method);
+        if (s.class && !s.method)
+            patterns.push(s.class);
+        if (s.annotation)
+            patterns.push(s.annotation);
+        if (patterns.length === 0)
+            continue;
+        const uniquePatterns = [...new Set(patterns)];
+        if (s.removes && s.removes.length > 0) {
+            for (const sinkType of s.removes) {
+                entries.push({
+                    patterns: uniquePatterns,
+                    sinkType,
+                    source: 'circle-ir:default',
+                    note: s.note,
+                });
+            }
+        }
+        else {
+            entries.push({
+                patterns: uniquePatterns,
+                source: 'circle-ir:default',
+                note: s.note,
+            });
+        }
+    }
+    sanitizerCache = entries;
+    return entries;
+}
+export function loadSinkCatalog() {
+    if (sinkCache)
+        return sinkCache;
+    sinkCache = DEFAULT_SINKS.map((s) => ({
+        method: s.method,
+        class: s.class,
+        type: s.type,
+        cwe: s.cwe,
+        severity: s.severity,
+        argPositions: s.arg_positions ?? [],
+        languages: s.languages,
+        note: s.note,
+    }));
+    return sinkCache;
+}
+export function loadSourceCatalog() {
+    if (sourceCache)
+        return sourceCache;
+    sourceCache = DEFAULT_SOURCES.map((s) => ({
+        method: s.method,
+        class: s.class,
+        property: s.property,
+        object: s.object,
+        annotation: s.annotation,
+        methodAnnotation: s.method_annotation,
+        type: s.type,
+        severity: s.severity,
+        returnTainted: s.return_tainted,
+        paramTainted: s.param_tainted,
+        propertyTainted: s.property_tainted,
+        languages: s.languages,
+        note: s.note,
+    }));
+    return sourceCache;
+}
+//# sourceMappingURL=catalogs.js.map

package/dist/resources/catalogs.js.map

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

package/dist/resources/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * MCP resource registration — read-only reference material an LLM can
+ * fetch by URI without invoking a tool.
+ *
+ *   cognium://sast-finding-schema  → JSON Schema for SastFinding
+ *   cognium://sink-catalog          → every sink pattern circle-ir knows
+ *   cognium://source-catalog        → every source pattern circle-ir knows
+ *   cognium://sanitizer-catalog     → every sanitizer entry
+ *   cognium://passes                → contents of circle-ir docs/PASSES.md
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerResources(server: McpServer): void;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/resources/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAsBzE,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CA+FzD"}

package/dist/resources/index.js

@@ -0,0 +1,94 @@
+/**
+ * MCP resource registration — read-only reference material an LLM can
+ * fetch by URI without invoking a tool.
+ *
+ *   cognium://sast-finding-schema  → JSON Schema for SastFinding
+ *   cognium://sink-catalog          → every sink pattern circle-ir knows
+ *   cognium://source-catalog        → every source pattern circle-ir knows
+ *   cognium://sanitizer-catalog     → every sanitizer entry
+ *   cognium://passes                → contents of circle-ir docs/PASSES.md
+ */
+import { createRequire } from 'module';
+import { dirname, join } from 'path';
+import { readFileSync } from 'fs';
+import { SAST_FINDING_SCHEMA } from './schema.js';
+import { loadSanitizerCatalog, loadSinkCatalog, loadSourceCatalog, } from './catalogs.js';
+function loadPassesMarkdown() {
+    try {
+        const require = createRequire(import.meta.url);
+        const circleIrPkg = require.resolve('circle-ir/package.json');
+        const passesPath = join(dirname(circleIrPkg), 'docs', 'PASSES.md');
+        return readFileSync(passesPath, 'utf8');
+    }
+    catch (err) {
+        return `# PASSES.md unavailable\n\nFailed to load from circle-ir install: ${err.message}`;
+    }
+}
+export function registerResources(server) {
+    server.registerResource('sast-finding-schema', 'cognium://sast-finding-schema', {
+        title: 'SastFinding JSON Schema',
+        description: 'Canonical JSON Schema for SastFinding objects emitted by circle-ir.',
+        mimeType: 'application/schema+json',
+    }, async (uri) => ({
+        contents: [
+            {
+                uri: uri.href,
+                mimeType: 'application/schema+json',
+                text: JSON.stringify(SAST_FINDING_SCHEMA, null, 2),
+            },
+        ],
+    }));
+    server.registerResource('sink-catalog', 'cognium://sink-catalog', {
+        title: 'Sink catalog',
+        description: 'Every taint sink pattern known to circle-ir (method / class / type / cwe / severity / dangerous arg positions).',
+        mimeType: 'application/json',
+    }, async (uri) => ({
+        contents: [
+            {
+                uri: uri.href,
+                mimeType: 'application/json',
+                text: JSON.stringify(loadSinkCatalog(), null, 2),
+            },
+        ],
+    }));
+    server.registerResource('source-catalog', 'cognium://source-catalog', {
+        title: 'Source catalog',
+        description: 'Every taint source pattern known to circle-ir (framework API, annotation, property, or DB result).',
+        mimeType: 'application/json',
+    }, async (uri) => ({
+        contents: [
+            {
+                uri: uri.href,
+                mimeType: 'application/json',
+                text: JSON.stringify(loadSourceCatalog(), null, 2),
+            },
+        ],
+    }));
+    server.registerResource('sanitizer-catalog', 'cognium://sanitizer-catalog', {
+        title: 'Sanitizer catalog',
+        description: 'Every sanitizer function circle-ir recognizes, indexed by sink type.',
+        mimeType: 'application/json',
+    }, async (uri) => ({
+        contents: [
+            {
+                uri: uri.href,
+                mimeType: 'application/json',
+                text: JSON.stringify(loadSanitizerCatalog(), null, 2),
+            },
+        ],
+    }));
+    server.registerResource('passes', 'cognium://passes', {
+        title: 'Pass + metric registry (PASSES.md)',
+        description: 'Canonical pass registry with rule_id, CWE, SARIF level, and status for every circle-ir analysis pass.',
+        mimeType: 'text/markdown',
+    }, async (uri) => ({
+        contents: [
+            {
+                uri: uri.href,
+                mimeType: 'text/markdown',
+                text: loadPassesMarkdown(),
+            },
+        ],
+    }));
+}
+//# sourceMappingURL=index.js.map