@cognium/mcp-server 0.1.0

package/dist/resources/index.js.map

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

package/dist/resources/schema.d.ts

@@ -0,0 +1,81 @@
+/**
+ * `cognium://sast-finding-schema` resource — the canonical shape of a
+ * `SastFinding` object as produced by circle-ir. Callers can consume
+ * this at prompt-construction time to know which fields to expect.
+ *
+ * We hand-write the schema here (rather than reflecting one from the
+ * TypeScript type) so it remains stable and hand-tuned for LLM
+ * consumption.
+ */
+export declare const SAST_FINDING_SCHEMA: {
+    readonly $schema: "http://json-schema.org/draft-07/schema#";
+    readonly $id: "cognium://sast-finding-schema";
+    readonly title: "SastFinding";
+    readonly description: string;
+    readonly type: "object";
+    readonly required: readonly ["id", "pass", "category", "rule_id", "cwe", "severity", "level", "message", "file", "line"];
+    readonly properties: {
+        readonly id: {
+            readonly type: "string";
+            readonly description: "Stable per-run id, formed as `<pass>-<file>-<line>` (or with a discriminator suffix when multiple findings collide).";
+        };
+        readonly pass: {
+            readonly type: "string";
+            readonly description: "Name of the AnalysisPass that emitted the finding.";
+        };
+        readonly category: {
+            readonly type: "string";
+            readonly enum: readonly ["security", "reliability", "performance", "maintainability", "architecture"];
+            readonly description: "High-level PassCategory. Filters use this axis first.";
+        };
+        readonly rule_id: {
+            readonly type: "string";
+            readonly description: "Canonical rule identifier — matches `docs/PASSES.md rule_id` column.";
+        };
+        readonly cwe: {
+            readonly type: "string";
+            readonly description: "CWE identifier (e.g. `CWE-89`) for security findings; empty for quality findings.";
+        };
+        readonly severity: {
+            readonly type: "string";
+            readonly enum: readonly ["critical", "high", "medium", "low"];
+            readonly description: "Coarse severity bucket. Not linear — critical is >2x high in practice.";
+        };
+        readonly level: {
+            readonly type: "string";
+            readonly enum: readonly ["error", "warning", "note", "none"];
+            readonly description: "SARIF level for the finding. Maps into SARIF `result.level`.";
+        };
+        readonly message: {
+            readonly type: "string";
+            readonly description: "Human-readable one-line description.";
+        };
+        readonly file: {
+            readonly type: "string";
+            readonly description: "Repository-relative path (may be absolute when scanned outside a repo).";
+        };
+        readonly line: {
+            readonly type: "integer";
+            readonly description: "1-indexed line number.";
+        };
+        readonly column: {
+            readonly type: "integer";
+            readonly description: "1-indexed column, when available.";
+        };
+        readonly snippet: {
+            readonly type: "string";
+            readonly description: "Short source excerpt (may be truncated to 2KB by this server).";
+        };
+        readonly fix: {
+            readonly type: "string";
+            readonly description: "Suggested remediation code / instruction.";
+        };
+        readonly metadata: {
+            readonly type: "object";
+            readonly description: "Free-form per-rule metadata (e.g. sink type, confidence, taint path id).";
+            readonly additionalProperties: true;
+        };
+    };
+    readonly additionalProperties: true;
+};
+//# sourceMappingURL=schema.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/resources/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqDtB,CAAC"}

package/dist/resources/schema.js

@@ -0,0 +1,63 @@
+/**
+ * `cognium://sast-finding-schema` resource — the canonical shape of a
+ * `SastFinding` object as produced by circle-ir. Callers can consume
+ * this at prompt-construction time to know which fields to expect.
+ *
+ * We hand-write the schema here (rather than reflecting one from the
+ * TypeScript type) so it remains stable and hand-tuned for LLM
+ * consumption.
+ */
+export const SAST_FINDING_SCHEMA = {
+    $schema: 'http://json-schema.org/draft-07/schema#',
+    $id: 'cognium://sast-finding-schema',
+    title: 'SastFinding',
+    description: 'Deterministic security or quality finding emitted by circle-ir. Every field is populated by ' +
+        'static analysis; there is no LLM in the emission path.',
+    type: 'object',
+    required: [
+        'id',
+        'pass',
+        'category',
+        'rule_id',
+        'cwe',
+        'severity',
+        'level',
+        'message',
+        'file',
+        'line',
+    ],
+    properties: {
+        id: { type: 'string', description: 'Stable per-run id, formed as `<pass>-<file>-<line>` (or with a discriminator suffix when multiple findings collide).' },
+        pass: { type: 'string', description: 'Name of the AnalysisPass that emitted the finding.' },
+        category: {
+            type: 'string',
+            enum: ['security', 'reliability', 'performance', 'maintainability', 'architecture'],
+            description: 'High-level PassCategory. Filters use this axis first.',
+        },
+        rule_id: { type: 'string', description: 'Canonical rule identifier — matches `docs/PASSES.md rule_id` column.' },
+        cwe: { type: 'string', description: 'CWE identifier (e.g. `CWE-89`) for security findings; empty for quality findings.' },
+        severity: {
+            type: 'string',
+            enum: ['critical', 'high', 'medium', 'low'],
+            description: 'Coarse severity bucket. Not linear — critical is >2x high in practice.',
+        },
+        level: {
+            type: 'string',
+            enum: ['error', 'warning', 'note', 'none'],
+            description: 'SARIF level for the finding. Maps into SARIF `result.level`.',
+        },
+        message: { type: 'string', description: 'Human-readable one-line description.' },
+        file: { type: 'string', description: 'Repository-relative path (may be absolute when scanned outside a repo).' },
+        line: { type: 'integer', description: '1-indexed line number.' },
+        column: { type: 'integer', description: '1-indexed column, when available.' },
+        snippet: { type: 'string', description: 'Short source excerpt (may be truncated to 2KB by this server).' },
+        fix: { type: 'string', description: 'Suggested remediation code / instruction.' },
+        metadata: {
+            type: 'object',
+            description: 'Free-form per-rule metadata (e.g. sink type, confidence, taint path id).',
+            additionalProperties: true,
+        },
+    },
+    additionalProperties: true,
+};
+//# sourceMappingURL=schema.js.map

package/dist/resources/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/resources/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,OAAO,EAAE,yCAAyC;IAClD,GAAG,EAAE,+BAA+B;IACpC,KAAK,EAAE,aAAa;IACpB,WAAW,EACT,8FAA8F;QAC9F,wDAAwD;IAC1D,IAAI,EAAE,QAAQ;IACd,QAAQ,EAAE;QACR,IAAI;QACJ,MAAM;QACN,UAAU;QACV,SAAS;QACT,KAAK;QACL,UAAU;QACV,OAAO;QACP,SAAS;QACT,MAAM;QACN,MAAM;KACP;IACD,UAAU,EAAE;QACV,EAAE,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,sHAAsH,EAAE;QAC3J,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,oDAAoD,EAAE;QAC3F,QAAQ,EAAE;YACR,IAAI,EAAE,QAAQ;YACd,IAAI,EAAE,CAAC,UAAU,EAAE,aAAa,EAAE,aAAa,EAAE,iBAAiB,EAAE,cAAc,CAAC;YACnF,WAAW,EAAE,uDAAuD;SACrE;QACD,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,sEAAsE,EAAE;QAChH,GAAG,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,mFAAmF,EAAE;QACzH,QAAQ,EAAE;YACR,IAAI,EAAE,QAAQ;YACd,IAAI,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,CAAC;YAC3C,WAAW,EAAE,wEAAwE;SACtF;QACD,KAAK,EAAE;YACL,IAAI,EAAE,QAAQ;YACd,IAAI,EAAE,CAAC,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC;YAC1C,WAAW,EAAE,8DAA8D;SAC5E;QACD,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,sCAAsC,EAAE;QAChF,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,yEAAyE,EAAE;QAChH,IAAI,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,WAAW,EAAE,wBAAwB,EAAE;QAChE,MAAM,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,WAAW,EAAE,mCAAmC,EAAE;QAC7E,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,gEAAgE,EAAE;QAC1G,GAAG,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,2CAA2C,EAAE;QACjF,QAAQ,EAAE;YACR,IAAI,EAAE,QAAQ;YACd,WAAW,EAAE,0EAA0E;YACvF,oBAAoB,EAAE,IAAI;SAC3B;KACF;IACD,oBAAoB,EAAE,IAAI;CAClB,CAAC"}

package/dist/server.d.ts

@@ -0,0 +1,12 @@
+/**
+ * MCP server assembly — register every tool + resource on a fresh
+ * `McpServer` instance. Transport wiring lives in `index.ts` so this
+ * module stays transport-agnostic and testable.
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export interface BuildServerOptions {
+    /** Override the default cache capacity (3 projects). */
+    cacheCapacity?: number;
+}
+export declare function buildServer(opts?: BuildServerOptions): 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;;;;GAIG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAiBpE,MAAM,WAAW,kBAAkB;IACjC,wDAAwD;IACxD,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,wBAAgB,WAAW,CAAC,IAAI,GAAE,kBAAuB,GAAG,SAAS,CAwBpE"}

package/dist/server.js

@@ -0,0 +1,41 @@
+/**
+ * MCP server assembly — register every tool + resource on a fresh
+ * `McpServer` instance. Transport wiring lives in `index.ts` so this
+ * module stays transport-agnostic and testable.
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { ProjectCache } from './cache.js';
+import { registerResources } from './resources/index.js';
+import { scanConfig, makeScanHandler } from './tools/scan.js';
+import { explainFindingConfig, makeExplainFindingHandler } from './tools/explain-finding.js';
+import { taintPathsConfig, makeTaintPathsHandler } from './tools/taint-paths.js';
+import { listEntryPointsConfig, makeListEntryPointsHandler } from './tools/list-entry-points.js';
+import { checkSanitizerConfig, makeCheckSanitizerHandler } from './tools/check-sanitizer.js';
+import { describeSinkConfig, makeDescribeSinkHandler } from './tools/describe-sink.js';
+import { describeSourceConfig, makeDescribeSourceHandler } from './tools/describe-source.js';
+import { attackSurfaceSummaryConfig, makeAttackSurfaceSummaryHandler } from './tools/attack-surface-summary.js';
+import { listReachableSinksConfig, makeListReachableSinksHandler } from './tools/list-reachable-sinks.js';
+import { findSimilarConfig, makeFindSimilarHandler } from './tools/find-similar.js';
+import { refreshConfig, makeRefreshHandler } from './tools/refresh.js';
+export function buildServer(opts = {}) {
+    const cache = new ProjectCache(opts.cacheCapacity ?? 3);
+    const ctx = { cache };
+    const server = new McpServer({
+        name: 'cognium-mcp-server',
+        version: '0.1.0',
+    });
+    server.registerTool('scan', scanConfig, makeScanHandler(ctx));
+    server.registerTool('explain_finding', explainFindingConfig, makeExplainFindingHandler(ctx));
+    server.registerTool('taint_paths', taintPathsConfig, makeTaintPathsHandler(ctx));
+    server.registerTool('list_entry_points', listEntryPointsConfig, makeListEntryPointsHandler(ctx));
+    server.registerTool('check_sanitizer', checkSanitizerConfig, makeCheckSanitizerHandler(ctx));
+    server.registerTool('describe_sink', describeSinkConfig, makeDescribeSinkHandler(ctx));
+    server.registerTool('describe_source', describeSourceConfig, makeDescribeSourceHandler(ctx));
+    server.registerTool('attack_surface_summary', attackSurfaceSummaryConfig, makeAttackSurfaceSummaryHandler(ctx));
+    server.registerTool('list_reachable_sinks', listReachableSinksConfig, makeListReachableSinksHandler(ctx));
+    server.registerTool('find_similar', findSimilarConfig, makeFindSimilarHandler(ctx));
+    server.registerTool('refresh', refreshConfig, makeRefreshHandler(ctx));
+    registerResources(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;;;;GAIG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE1C,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAEzD,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAC9D,OAAO,EAAE,oBAAoB,EAAE,yBAAyB,EAAE,MAAM,4BAA4B,CAAC;AAC7F,OAAO,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AACjF,OAAO,EAAE,qBAAqB,EAAE,0BAA0B,EAAE,MAAM,8BAA8B,CAAC;AACjG,OAAO,EAAE,oBAAoB,EAAE,yBAAyB,EAAE,MAAM,4BAA4B,CAAC;AAC7F,OAAO,EAAE,kBAAkB,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AACvF,OAAO,EAAE,oBAAoB,EAAE,yBAAyB,EAAE,MAAM,4BAA4B,CAAC;AAC7F,OAAO,EAAE,0BAA0B,EAAE,+BAA+B,EAAE,MAAM,mCAAmC,CAAC;AAChH,OAAO,EAAE,wBAAwB,EAAE,6BAA6B,EAAE,MAAM,iCAAiC,CAAC;AAC1G,OAAO,EAAE,iBAAiB,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AACpF,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAOvE,MAAM,UAAU,WAAW,CAAC,OAA2B,EAAE;IACvD,MAAM,KAAK,GAAG,IAAI,YAAY,CAAC,IAAI,CAAC,aAAa,IAAI,CAAC,CAAC,CAAC;IACxD,MAAM,GAAG,GAAgB,EAAE,KAAK,EAAE,CAAC;IAEnC,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;QAC3B,IAAI,EAAE,oBAAoB;QAC1B,OAAO,EAAE,OAAO;KACjB,CAAC,CAAC;IAEH,MAAM,CAAC,YAAY,CAAC,MAAM,EAAE,UAAU,EAAE,eAAe,CAAC,GAAG,CAAU,CAAC,CAAC;IACvE,MAAM,CAAC,YAAY,CAAC,iBAAiB,EAAE,oBAAoB,EAAE,yBAAyB,CAAC,GAAG,CAAU,CAAC,CAAC;IACtG,MAAM,CAAC,YAAY,CAAC,aAAa,EAAE,gBAAgB,EAAE,qBAAqB,CAAC,GAAG,CAAU,CAAC,CAAC;IAC1F,MAAM,CAAC,YAAY,CAAC,mBAAmB,EAAE,qBAAqB,EAAE,0BAA0B,CAAC,GAAG,CAAU,CAAC,CAAC;IAC1G,MAAM,CAAC,YAAY,CAAC,iBAAiB,EAAE,oBAAoB,EAAE,yBAAyB,CAAC,GAAG,CAAU,CAAC,CAAC;IACtG,MAAM,CAAC,YAAY,CAAC,eAAe,EAAE,kBAAkB,EAAE,uBAAuB,CAAC,GAAG,CAAU,CAAC,CAAC;IAChG,MAAM,CAAC,YAAY,CAAC,iBAAiB,EAAE,oBAAoB,EAAE,yBAAyB,CAAC,GAAG,CAAU,CAAC,CAAC;IACtG,MAAM,CAAC,YAAY,CAAC,wBAAwB,EAAE,0BAA0B,EAAE,+BAA+B,CAAC,GAAG,CAAU,CAAC,CAAC;IACzH,MAAM,CAAC,YAAY,CAAC,sBAAsB,EAAE,wBAAwB,EAAE,6BAA6B,CAAC,GAAG,CAAU,CAAC,CAAC;IACnH,MAAM,CAAC,YAAY,CAAC,cAAc,EAAE,iBAAiB,EAAE,sBAAsB,CAAC,GAAG,CAAU,CAAC,CAAC;IAC7F,MAAM,CAAC,YAAY,CAAC,SAAS,EAAE,aAAa,EAAE,kBAAkB,CAAC,GAAG,CAAU,CAAC,CAAC;IAEhF,iBAAiB,CAAC,MAAM,CAAC,CAAC;IAE1B,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/tools/attack-surface-summary.d.ts

@@ -0,0 +1,24 @@
+/**
+ * `attack_surface_summary` tool — high-level roll-up of a project's
+ * attack surface: entry points × sinks × cross-file taint paths, grouped
+ * by language / framework / vulnerability category.
+ *
+ * Designed as the first tool an LLM calls when a user asks
+ * "give me a security posture summary of this codebase".
+ */
+import { z } from 'zod';
+import type { ToolContext, ToolResult } from './types.js';
+export declare const attackSurfaceSummaryInputShape: {
+    readonly project_root: z.ZodString;
+};
+export declare const attackSurfaceSummaryConfig: {
+    readonly title: "Attack surface summary";
+    readonly description: string;
+    readonly inputSchema: {
+        readonly project_root: z.ZodString;
+    };
+};
+export declare function makeAttackSurfaceSummaryHandler(ctx: ToolContext): (args: {
+    project_root: string;
+}) => Promise<ToolResult>;
+//# sourceMappingURL=attack-surface-summary.d.ts.map

package/dist/tools/attack-surface-summary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attack-surface-summary.d.ts","sourceRoot":"","sources":["../../src/tools/attack-surface-summary.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAG1D,eAAO,MAAM,8BAA8B;;CAEjC,CAAC;AAEX,eAAO,MAAM,0BAA0B;;;;;;CAO7B,CAAC;AAEX,wBAAgB,+BAA+B,CAAC,GAAG,EAAE,WAAW,IAChD,MAAM;IAAE,YAAY,EAAE,MAAM,CAAA;CAAE,KAAG,OAAO,CAAC,UAAU,CAAC,CAkGnE"}

package/dist/tools/attack-surface-summary.js

@@ -0,0 +1,116 @@
+/**
+ * `attack_surface_summary` tool — high-level roll-up of a project's
+ * attack surface: entry points × sinks × cross-file taint paths, grouped
+ * by language / framework / vulnerability category.
+ *
+ * Designed as the first tool an LLM calls when a user asks
+ * "give me a security posture summary of this codebase".
+ */
+import { z } from 'zod';
+import { resolve } from 'path';
+import { RULE_DEFINITIONS } from 'circle-ir';
+import { textResult } from './types.js';
+export const attackSurfaceSummaryInputShape = {
+    project_root: z.string().describe('Absolute path to the project root.'),
+};
+export const attackSurfaceSummaryConfig = {
+    title: 'Attack surface summary',
+    description: 'Compute a security-posture roll-up for a previously-scanned project: total entry points by framework, ' +
+        'total sinks by category, cross-file taint-path totals per sink type, and the top 10 files by finding ' +
+        'count. Use as the entry-level tool for "what does this codebase look like from a security angle?"',
+    inputSchema: attackSurfaceSummaryInputShape,
+};
+export function makeAttackSurfaceSummaryHandler(ctx) {
+    return async (args) => {
+        const root = resolve(args.project_root);
+        const { analysis, cacheHit } = await ctx.cache.getOrCompute(root, {});
+        const entryPointsByFramework = {};
+        const entryPointsByLanguage = {};
+        const entryPointsByKind = {};
+        const sinksByType = {};
+        const sinksByLanguage = {};
+        const findingsBySeverity = {};
+        const findingsByCategory = {};
+        const findingsByRule = {};
+        const findingsPerFile = {};
+        let totalEntryPoints = 0;
+        let totalSinks = 0;
+        let totalSources = 0;
+        let totalFindings = 0;
+        for (const fa of analysis.files) {
+            const lang = fa.analysis.meta.language;
+            for (const reg of fa.analysis.runtime_registrations ?? []) {
+                totalEntryPoints++;
+                const fw = reg.framework ?? 'unknown';
+                entryPointsByFramework[fw] = (entryPointsByFramework[fw] ?? 0) + 1;
+                entryPointsByLanguage[lang] = (entryPointsByLanguage[lang] ?? 0) + 1;
+                entryPointsByKind[reg.kind] = (entryPointsByKind[reg.kind] ?? 0) + 1;
+            }
+            for (const s of fa.analysis.taint?.sinks ?? []) {
+                totalSinks++;
+                sinksByType[s.type] = (sinksByType[s.type] ?? 0) + 1;
+                sinksByLanguage[lang] = (sinksByLanguage[lang] ?? 0) + 1;
+            }
+            totalSources += fa.analysis.taint?.sources?.length ?? 0;
+            for (const f of fa.analysis.findings ?? []) {
+                totalFindings++;
+                findingsBySeverity[f.severity] = (findingsBySeverity[f.severity] ?? 0) + 1;
+                findingsByCategory[f.category] = (findingsByCategory[f.category] ?? 0) + 1;
+                findingsByRule[f.rule_id] = (findingsByRule[f.rule_id] ?? 0) + 1;
+                findingsPerFile[fa.file] = (findingsPerFile[fa.file] ?? 0) + 1;
+            }
+        }
+        const crossFilePathsBySinkType = {};
+        for (const p of analysis.taint_paths) {
+            const t = p.sink.type ?? 'unknown';
+            crossFilePathsBySinkType[t] = (crossFilePathsBySinkType[t] ?? 0) + 1;
+        }
+        const topFiles = Object.entries(findingsPerFile)
+            .sort((a, b) => b[1] - a[1])
+            .slice(0, 10)
+            .map(([file, count]) => ({ file, findings: count }));
+        const criticalCategories = Object.entries(sinksByType)
+            .map(([type, count]) => ({
+            type,
+            count,
+            cwe: RULE_DEFINITIONS[type]?.cwe,
+            severity: RULE_DEFINITIONS[type]?.severityLevel,
+        }))
+            .sort((a, b) => b.count - a.count);
+        return textResult({
+            projectRoot: root,
+            cacheHit,
+            totals: {
+                files: analysis.files.length,
+                entryPoints: totalEntryPoints,
+                sources: totalSources,
+                sinks: totalSinks,
+                findings: totalFindings,
+                crossFileTaintPaths: analysis.taint_paths.length,
+            },
+            entryPoints: {
+                byFramework: entryPointsByFramework,
+                byLanguage: entryPointsByLanguage,
+                byKind: entryPointsByKind,
+            },
+            sinks: {
+                byLanguage: sinksByLanguage,
+                byCategory: criticalCategories,
+            },
+            findings: {
+                bySeverity: findingsBySeverity,
+                byCategory: findingsByCategory,
+                topRules: Object.entries(findingsByRule)
+                    .sort((a, b) => b[1] - a[1])
+                    .slice(0, 10)
+                    .map(([rule_id, count]) => ({ rule_id, count })),
+            },
+            crossFileTaintPaths: {
+                bySinkType: crossFilePathsBySinkType,
+                budgetExceeded: analysis.cross_file_budget_exceeded === true,
+            },
+            topFiles,
+        });
+    };
+}
+//# sourceMappingURL=attack-surface-summary.js.map

package/dist/tools/attack-surface-summary.js.map

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

package/dist/tools/check-sanitizer.d.ts

@@ -0,0 +1,29 @@
+/**
+ * `check_sanitizer` tool — deterministic yes/no on whether a function
+ * qualifies as a sanitizer for a given sink type.
+ *
+ * Grounds LLM claims like "this is escaped by DOMPurify.sanitize" —
+ * replaces guesswork with a lookup against circle-ir's YAML catalog.
+ */
+import { z } from 'zod';
+import type { ToolContext, ToolResult } from './types.js';
+export declare const checkSanitizerInputShape: {
+    readonly function_qualified_name: z.ZodString;
+    readonly sink_type: z.ZodString;
+    readonly language: z.ZodOptional<z.ZodEnum<["java", "javascript", "typescript", "python", "go", "rust", "bash", "html"]>>;
+};
+export declare const checkSanitizerConfig: {
+    readonly title: "Check sanitizer validity";
+    readonly description: string;
+    readonly inputSchema: {
+        readonly function_qualified_name: z.ZodString;
+        readonly sink_type: z.ZodString;
+        readonly language: z.ZodOptional<z.ZodEnum<["java", "javascript", "typescript", "python", "go", "rust", "bash", "html"]>>;
+    };
+};
+export declare function makeCheckSanitizerHandler(_ctx: ToolContext): (args: {
+    function_qualified_name: string;
+    sink_type: string;
+    language?: string;
+}) => Promise<ToolResult>;
+//# sourceMappingURL=check-sanitizer.d.ts.map

package/dist/tools/check-sanitizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"check-sanitizer.d.ts","sourceRoot":"","sources":["../../src/tools/check-sanitizer.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAI1D,eAAO,MAAM,wBAAwB;;;;CAQ3B,CAAC;AAEX,eAAO,MAAM,oBAAoB;;;;;;;;CAOvB,CAAC;AAEX,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,WAAW,IAC3C,MAAM;IAClB,uBAAuB,EAAE,MAAM,CAAC;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,KAAG,OAAO,CAAC,UAAU,CAAC,CA0DxB"}

package/dist/tools/check-sanitizer.js

@@ -0,0 +1,82 @@
+/**
+ * `check_sanitizer` tool — deterministic yes/no on whether a function
+ * qualifies as a sanitizer for a given sink type.
+ *
+ * Grounds LLM claims like "this is escaped by DOMPurify.sanitize" —
+ * replaces guesswork with a lookup against circle-ir's YAML catalog.
+ */
+import { z } from 'zod';
+import { textResult } from './types.js';
+import { loadSanitizerCatalog } from '../resources/catalogs.js';
+export const checkSanitizerInputShape = {
+    function_qualified_name: z.string()
+        .describe('Fully-qualified function name to check, e.g. "org.owasp.esapi.Encoder.encodeForHTML" or "DOMPurify.sanitize".'),
+    sink_type: z.string()
+        .describe('Sink category to check against, e.g. "xss", "sql_injection", "command_injection".'),
+    language: z.enum(['java', 'javascript', 'typescript', 'python', 'go', 'rust', 'bash', 'html'])
+        .optional()
+        .describe('Language of the function under check. When omitted, all languages are searched.'),
+};
+export const checkSanitizerConfig = {
+    title: 'Check sanitizer validity',
+    description: 'Verify that a function is a recognized sanitizer for a specific sink type in circle-ir\'s YAML ' +
+        'catalog. Returns { isValidSanitizer, matchedRule, notes, alternatives } so an LLM can ground its ' +
+        '"this input is safe because it was escaped" reasoning.',
+    inputSchema: checkSanitizerInputShape,
+};
+export function makeCheckSanitizerHandler(_ctx) {
+    return async (args) => {
+        const catalog = loadSanitizerCatalog();
+        const fq = args.function_qualified_name;
+        const fqLower = fq.toLowerCase();
+        const fqLast = fq.split(/[.:]/).pop() ?? fq;
+        const sinkType = args.sink_type;
+        const matches = catalog.filter(entry => {
+            // Sink type must match or entry must be typeless (applies to all).
+            if (entry.sinkType && entry.sinkType !== sinkType)
+                return false;
+            if (args.language && entry.language && entry.language !== args.language)
+                return false;
+            const patternMatches = entry.patterns.some(pat => {
+                const p = pat.toLowerCase();
+                return p === fqLower
+                    || fqLower.endsWith('.' + p)
+                    || fqLower.endsWith(':' + p)
+                    || fqLast.toLowerCase() === p;
+            });
+            return patternMatches;
+        });
+        if (matches.length === 0) {
+            // Suggest alternatives from the catalog for this sink.
+            const alternatives = catalog
+                .filter(e => (!args.language || !e.language || e.language === args.language) && (!e.sinkType || e.sinkType === sinkType))
+                .flatMap(e => e.patterns)
+                .slice(0, 20);
+            return textResult({
+                isValidSanitizer: false,
+                function: fq,
+                sink_type: sinkType,
+                language: args.language ?? 'any',
+                notes: `No sanitizer entry matches "${fq}" for sink_type "${sinkType}". This does NOT mean the function ` +
+                    `is unsafe — it may be a project-specific wrapper. But circle-ir will not treat it as a sanitizer ` +
+                    `during taint analysis, so a source→sink flow through it will be flagged.`,
+                alternatives,
+            });
+        }
+        return textResult({
+            isValidSanitizer: true,
+            function: fq,
+            sink_type: sinkType,
+            language: args.language ?? 'any',
+            matchedRules: matches.map(m => ({
+                pattern: m.patterns,
+                sinkType: m.sinkType ?? 'any',
+                language: m.language ?? 'any',
+                source: m.source,
+            })),
+            notes: 'circle-ir will treat any taint flowing through this function as sanitized for the given sink ' +
+                'type. A downstream sink call will not fire.',
+        });
+    };
+}
+//# sourceMappingURL=check-sanitizer.js.map

package/dist/tools/check-sanitizer.js.map

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

package/dist/tools/describe-sink.d.ts

@@ -0,0 +1,22 @@
+/**
+ * `describe_sink` tool — sink category metadata (CWE, remediation, sanitizers).
+ */
+import { z } from 'zod';
+import type { ToolContext, ToolResult } from './types.js';
+export declare const describeSinkInputShape: {
+    readonly sink_type: z.ZodString;
+    readonly language: z.ZodOptional<z.ZodEnum<["java", "javascript", "typescript", "python", "go", "rust", "bash", "html"]>>;
+};
+export declare const describeSinkConfig: {
+    readonly title: "Describe sink category";
+    readonly description: string;
+    readonly inputSchema: {
+        readonly sink_type: z.ZodString;
+        readonly language: z.ZodOptional<z.ZodEnum<["java", "javascript", "typescript", "python", "go", "rust", "bash", "html"]>>;
+    };
+};
+export declare function makeDescribeSinkHandler(_ctx: ToolContext): (args: {
+    sink_type: string;
+    language?: string;
+}) => Promise<ToolResult>;
+//# sourceMappingURL=describe-sink.d.ts.map

package/dist/tools/describe-sink.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"describe-sink.d.ts","sourceRoot":"","sources":["../../src/tools/describe-sink.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAI1D,eAAO,MAAM,sBAAsB;;;CAMzB,CAAC;AAEX,eAAO,MAAM,kBAAkB;;;;;;;CAOrB,CAAC;AAEX,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,WAAW,IACzC,MAAM;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,KAAG,OAAO,CAAC,UAAU,CAAC,CA0BnF"}

package/dist/tools/describe-sink.js

@@ -0,0 +1,47 @@
+/**
+ * `describe_sink` tool — sink category metadata (CWE, remediation, sanitizers).
+ */
+import { z } from 'zod';
+import { RULE_DEFINITIONS } from 'circle-ir';
+import { textResult, errorResult } from './types.js';
+import { loadSanitizerCatalog } from '../resources/catalogs.js';
+export const describeSinkInputShape = {
+    sink_type: z.string()
+        .describe('Sink category, e.g. "sql_injection", "command_injection", "xss", "path_traversal".'),
+    language: z.enum(['java', 'javascript', 'typescript', 'python', 'go', 'rust', 'bash', 'html'])
+        .optional()
+        .describe('Restrict sanitizer suggestions to this language.'),
+};
+export const describeSinkConfig = {
+    title: 'Describe sink category',
+    description: 'Return canonical metadata for a taint sink category: CWE identifier, short + full description, ' +
+        'recommended remediation, CVSS-like severity score, and the list of sanitizer functions that would ' +
+        'neutralize the sink. Use when the LLM needs authoritative information about a vulnerability class.',
+    inputSchema: describeSinkInputShape,
+};
+export function makeDescribeSinkHandler(_ctx) {
+    return async (args) => {
+        const rule = RULE_DEFINITIONS[args.sink_type];
+        if (!rule) {
+            return errorResult(`Unknown sink_type "${args.sink_type}". Known types: ${Object.keys(RULE_DEFINITIONS).join(', ')}`);
+        }
+        const sanitizers = loadSanitizerCatalog()
+            .filter(e => (!e.sinkType || e.sinkType === args.sink_type)
+            && (!args.language || !e.language || e.language === args.language))
+            .flatMap(e => e.patterns);
+        return textResult({
+            sink_type: args.sink_type,
+            cwe: rule.cwe,
+            name: rule.name,
+            shortDescription: rule.shortDescription,
+            fullDescription: rule.fullDescription,
+            remediation: rule.remediation,
+            cvssScore: rule.cvssScore,
+            severityLevel: rule.severityLevel,
+            language: args.language ?? 'any',
+            sanitizers: [...new Set(sanitizers)].slice(0, 50),
+            sanitizerCount: sanitizers.length,
+        });
+    };
+}
+//# sourceMappingURL=describe-sink.js.map

package/dist/tools/describe-sink.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"describe-sink.js","sourceRoot":"","sources":["../../src/tools/describe-sink.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,gBAAgB,EAAiB,MAAM,WAAW,CAAC;AAE5D,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACrD,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAEhE,MAAM,CAAC,MAAM,sBAAsB,GAAG;IACpC,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;SAClB,QAAQ,CAAC,oFAAoF,CAAC;IACjG,QAAQ,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,YAAY,EAAE,YAAY,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;SAC3F,QAAQ,EAAE;SACV,QAAQ,CAAC,kDAAkD,CAAC;CACvD,CAAC;AAEX,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,KAAK,EAAE,wBAAwB;IAC/B,WAAW,EACT,iGAAiG;QACjG,oGAAoG;QACpG,oGAAoG;IACtG,WAAW,EAAE,sBAAsB;CAC3B,CAAC;AAEX,MAAM,UAAU,uBAAuB,CAAC,IAAiB;IACvD,OAAO,KAAK,EAAE,IAA8C,EAAuB,EAAE;QACnF,MAAM,IAAI,GAAG,gBAAgB,CAAC,IAAI,CAAC,SAAqB,CAAC,CAAC;QAC1D,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,OAAO,WAAW,CAChB,sBAAsB,IAAI,CAAC,SAAS,mBAAmB,MAAM,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAClG,CAAC;QACJ,CAAC;QACD,MAAM,UAAU,GAAG,oBAAoB,EAAE;aACtC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,IAAI,CAAC,CAAC,QAAQ,KAAK,IAAI,CAAC,SAAS,CAAC;eACtD,CAAC,CAAC,IAAI,CAAC,QAAQ,IAAI,CAAC,CAAC,CAAC,QAAQ,IAAI,CAAC,CAAC,QAAQ,KAAK,IAAI,CAAC,QAAQ,CAAC,CAAC;aACpE,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;QAE5B,OAAO,UAAU,CAAC;YAChB,SAAS,EAAE,IAAI,CAAC,SAAS;YACzB,GAAG,EAAE,IAAI,CAAC,GAAG;YACb,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,gBAAgB,EAAE,IAAI,CAAC,gBAAgB;YACvC,eAAe,EAAE,IAAI,CAAC,eAAe;YACrC,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,SAAS,EAAE,IAAI,CAAC,SAAS;YACzB,aAAa,EAAE,IAAI,CAAC,aAAa;YACjC,QAAQ,EAAE,IAAI,CAAC,QAAQ,IAAI,KAAK;YAChC,UAAU,EAAE,CAAC,GAAG,IAAI,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC;YACjD,cAAc,EAAE,UAAU,CAAC,MAAM;SAClC,CAAC,CAAC;IACL,CAAC,CAAC;AACJ,CAAC"}

package/dist/tools/describe-source.d.ts

@@ -0,0 +1,27 @@
+/**
+ * `describe_source` tool — enumerate taint-source patterns known to
+ * circle-ir for a given source category (e.g. `http_param`, `http_header`,
+ * `db_result`, `env`, `file`).
+ *
+ * Used by an LLM to answer "where would attacker-controlled data enter
+ * this codebase from `http_body`?" without guessing framework APIs.
+ */
+import { z } from 'zod';
+import type { ToolContext, ToolResult } from './types.js';
+export declare const describeSourceInputShape: {
+    readonly source_type: z.ZodString;
+    readonly language: z.ZodOptional<z.ZodEnum<["java", "javascript", "typescript", "python", "go", "rust", "bash", "html"]>>;
+};
+export declare const describeSourceConfig: {
+    readonly title: "Describe taint source category";
+    readonly description: string;
+    readonly inputSchema: {
+        readonly source_type: z.ZodString;
+        readonly language: z.ZodOptional<z.ZodEnum<["java", "javascript", "typescript", "python", "go", "rust", "bash", "html"]>>;
+    };
+};
+export declare function makeDescribeSourceHandler(_ctx: ToolContext): (args: {
+    source_type: string;
+    language?: string;
+}) => Promise<ToolResult>;
+//# sourceMappingURL=describe-source.d.ts.map

package/dist/tools/describe-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"describe-source.d.ts","sourceRoot":"","sources":["../../src/tools/describe-source.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAI1D,eAAO,MAAM,wBAAwB;;;CAM3B,CAAC;AAEX,eAAO,MAAM,oBAAoB;;;;;;;CAOvB,CAAC;AAEX,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,WAAW,IAC3C,MAAM;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,KAAG,OAAO,CAAC,UAAU,CAAC,CAsCrF"}