@orygn/opa-mcp 0.0.0 → 0.1.1

package/dist/tools/evaluation/_shared.js

@@ -0,0 +1,102 @@
+/**
+ * Shared helpers for the evaluation tool category.
+ *
+ * `rego_eval` and its three trace/profile/coverage variants all share
+ * the same input/output shape and error handling — only the OPA flags
+ * differ. The shared `runEval` helper takes the resolved EvalInput and
+ * returns an envelope; each tool's handler is a thin adapter that
+ * preps inputs and forwards.
+ */
+import { z } from 'zod';
+import { err, ok } from '../../lib/errors.js';
+import { mapSubprocessFailure, tryParseJson, validatePaths } from '../../lib/tool-helpers.js';
+/** Common input fields shared across rego_eval and its variants. */
+export const SharedEvalInput = {
+    query: z.string().min(1).describe('Rego query to evaluate, e.g. "data.example.allow".'),
+    source: z
+        .string()
+        .optional()
+        .describe('Inline Rego policy source. Mutually exclusive with `paths`.'),
+    paths: z
+        .array(z.string())
+        .optional()
+        .describe('Policy / data file or directory paths. Each must be inside an allowed root.'),
+    input: z.unknown().optional().describe('Inline input document.'),
+    inputPath: z
+        .string()
+        .optional()
+        .describe('Path to a JSON input file. Mutually exclusive with `input`.'),
+    unknowns: z
+        .array(z.string())
+        .optional()
+        .describe('Refs to treat as unknown during partial evaluation.'),
+    partial: z.boolean().optional().describe('Run partial evaluation rather than full evaluation.'),
+    strictBuiltinErrors: z
+        .boolean()
+        .optional()
+        .describe('Treat builtin errors as fatal instead of returning undefined.'),
+};
+/**
+ * Validate inputs (paths, input/inputPath conflict), call `opa eval`,
+ * and return the structured envelope.
+ */
+export async function runEval(opa, config, args, flags) {
+    if (!args.source && !args.paths?.length) {
+        return err('INVALID_INPUT', 'rego_eval requires either `source` or at least one entry in `paths`.');
+    }
+    if (args.input !== undefined && args.inputPath) {
+        return err('INVALID_INPUT', 'rego_eval accepts either `input` or `inputPath`, not both.');
+    }
+    const evalInput = { query: args.query };
+    if (args.source !== undefined)
+        evalInput.source = args.source;
+    if (args.paths?.length) {
+        const validation = validatePaths(args.paths, config, { mustExist: true });
+        if (!validation.ok)
+            return validation.error;
+        evalInput.paths = validation.resolved;
+    }
+    if (args.input !== undefined) {
+        evalInput.input = args.input;
+    }
+    else if (args.inputPath) {
+        const inputPathValidation = validatePaths([args.inputPath], config, { mustExist: true });
+        if (!inputPathValidation.ok)
+            return inputPathValidation.error;
+        evalInput.inputPath = inputPathValidation.resolved[0];
+    }
+    if (args.partial)
+        evalInput.partial = true;
+    if (args.unknowns?.length)
+        evalInput.unknowns = args.unknowns;
+    if (args.strictBuiltinErrors)
+        evalInput.strictBuiltinErrors = true;
+    if (flags.explain)
+        evalInput.explain = flags.explain;
+    if (flags.profile)
+        evalInput.profile = true;
+    if (flags.coverage)
+        evalInput.coverage = true;
+    if (flags.metrics)
+        evalInput.metrics = true;
+    const result = await opa.eval(evalInput);
+    const subprocessFailure = mapSubprocessFailure(result, 'opa');
+    if (subprocessFailure)
+        return subprocessFailure;
+    // `opa eval` returns exit code 0 even when the query produces no
+    // results or partial results. A non-zero exit means a hard error
+    // (parse, type, runtime). Output JSON is on stdout.
+    const parsed = tryParseJson(result.stdout);
+    if (result.exitCode !== 0) {
+        return err('EVAL_ERROR', 'opa eval exited with an error.', {
+            details: parsed ?? { stderr: result.stderr.trim(), stdout: result.stdout.trim() },
+        });
+    }
+    if (parsed === undefined) {
+        return err('UNKNOWN_ERROR', 'opa eval produced no parseable JSON output.', {
+            details: { stdout: result.stdout.trim() },
+        });
+    }
+    return ok(parsed);
+}
+//# sourceMappingURL=_shared.js.map

package/dist/tools/evaluation/_shared.js.map

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

package/dist/tools/evaluation/bench.d.ts

@@ -0,0 +1,9 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { Config } from '../../config.js';
+export interface RegoBenchOutput {
+    iterations?: number;
+    metrics?: Record<string, unknown>;
+    raw?: unknown;
+}
+export declare function registerRegoBench(server: McpServer, config: Config): void;
+//# sourceMappingURL=bench.d.ts.map

package/dist/tools/evaluation/bench.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bench.d.ts","sourceRoot":"","sources":["../../../src/tools/evaluation/bench.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AA0B9C,MAAM,WAAW,eAAe;IAC9B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CA0DzE"}

package/dist/tools/evaluation/bench.js

@@ -0,0 +1,76 @@
+/**
+ * `rego_bench` — benchmark a query via `opa bench`.
+ *
+ * Returns iteration count plus statistical timing data (ns/op,
+ * allocations, etc.).
+ */
+import { z } from 'zod';
+import { OpaCli } from '../../lib/opa-cli.js';
+import { err, ok } from '../../lib/errors.js';
+import { mapSubprocessFailure, tryParseJson, validatePaths, withToolEnvelope, } from '../../lib/tool-helpers.js';
+const RegoBenchInput = {
+    query: z.string().min(1).describe('Rego query to benchmark.'),
+    paths: z
+        .array(z.string())
+        .optional()
+        .describe('Policy / data paths to load. Each must be in an allowed root.'),
+    input: z.unknown().optional().describe('Inline input document.'),
+    inputPath: z.string().optional().describe('Path to a JSON input file.'),
+    count: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe("Number of benchmark iterations. Defaults to OPA's built-in default."),
+};
+export function registerRegoBench(server, config) {
+    const opa = new OpaCli(config);
+    server.registerTool('rego_bench', {
+        title: 'Benchmark Rego query',
+        description: 'Benchmark a Rego query against a policy + input with `opa bench`. Returns statistical timing data: iterations, ns/op, and allocation counts. Use this to spot slow rules.',
+        inputSchema: RegoBenchInput,
+    }, async ({ query, paths, input, inputPath, count }) => {
+        return withToolEnvelope(config, async () => {
+            if (input !== undefined && inputPath) {
+                return err('INVALID_INPUT', 'rego_bench accepts either `input` or `inputPath`, not both.');
+            }
+            let resolvedPaths;
+            if (paths?.length) {
+                const validation = validatePaths(paths, config, { mustExist: true });
+                if (!validation.ok)
+                    return validation.error;
+                resolvedPaths = validation.resolved;
+            }
+            let resolvedInputPath;
+            if (inputPath) {
+                const validation = validatePaths([inputPath], config, { mustExist: true });
+                if (!validation.ok)
+                    return validation.error;
+                resolvedInputPath = validation.resolved[0];
+            }
+            const result = await opa.bench({
+                query,
+                paths: resolvedPaths,
+                input,
+                inputPath: resolvedInputPath,
+                count,
+            });
+            const subprocessFailure = mapSubprocessFailure(result, 'opa');
+            if (subprocessFailure)
+                return subprocessFailure;
+            if (result.exitCode !== 0) {
+                return err('EVAL_ERROR', 'opa bench exited with an error.', {
+                    details: { stderr: result.stderr.trim() },
+                });
+            }
+            const parsed = tryParseJson(result.stdout);
+            if (parsed === undefined) {
+                return err('UNKNOWN_ERROR', 'opa bench produced no parseable JSON output.', {
+                    details: { stdout: result.stdout.trim() },
+                });
+            }
+            return ok(parsed);
+        });
+    });
+}
+//# sourceMappingURL=bench.js.map

package/dist/tools/evaluation/bench.js.map

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

package/dist/tools/evaluation/compile.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `rego_compile_query` — partially evaluate a query.
+ *
+ * Wraps `opa eval --partial` with a defaulted `unknowns` set. The
+ * result is a residual query — what remains after substituting in
+ * everything that's known. Useful for offline policy slicing.
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { Config } from '../../config.js';
+export declare function registerRegoCompileQuery(server: McpServer, config: Config): void;
+//# sourceMappingURL=compile.d.ts.map

package/dist/tools/evaluation/compile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compile.d.ts","sourceRoot":"","sources":["../../../src/tools/evaluation/compile.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAO9C,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CA0BhF"}

package/dist/tools/evaluation/compile.js

@@ -0,0 +1,19 @@
+import { OpaCli } from '../../lib/opa-cli.js';
+import { withToolEnvelope } from '../../lib/tool-helpers.js';
+import { runEval, SharedEvalInput } from './_shared.js';
+const RegoCompileQueryInput = SharedEvalInput;
+export function registerRegoCompileQuery(server, config) {
+    const opa = new OpaCli(config);
+    server.registerTool('rego_compile_query', {
+        title: 'Partially evaluate a Rego query',
+        description: 'Run partial evaluation on a query — substitute known values and return the residual policy. Defaults `unknowns` to `["input"]` (treat input as unknown), so the residual encodes "given input X, this is what would have to be true." Use this for offline policy slicing or pre-computing decision sets.',
+        inputSchema: RegoCompileQueryInput,
+    }, async (args) => {
+        return withToolEnvelope(config, () => runEval(opa, config, {
+            ...args,
+            partial: true,
+            unknowns: args.unknowns?.length ? args.unknowns : ['input'],
+        }, {}));
+    });
+}
+//# sourceMappingURL=compile.js.map

package/dist/tools/evaluation/compile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compile.js","sourceRoot":"","sources":["../../../src/tools/evaluation/compile.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAC9C,OAAO,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAC7D,OAAO,EAAE,OAAO,EAAE,eAAe,EAAuB,MAAM,cAAc,CAAC;AAE7E,MAAM,qBAAqB,GAAG,eAAe,CAAC;AAE9C,MAAM,UAAU,wBAAwB,CAAC,MAAiB,EAAE,MAAc;IACxE,MAAM,GAAG,GAAG,IAAI,MAAM,CAAC,MAAM,CAAC,CAAC;IAE/B,MAAM,CAAC,YAAY,CACjB,oBAAoB,EACpB;QACE,KAAK,EAAE,iCAAiC;QACxC,WAAW,EACT,2SAA2S;QAC7S,WAAW,EAAE,qBAAqB;KACnC,EACD,KAAK,EAAE,IAAI,EAAE,EAAE;QACb,OAAO,gBAAgB,CAAiB,MAAM,EAAE,GAAG,EAAE,CACnD,OAAO,CACL,GAAG,EACH,MAAM,EACN;YACE,GAAG,IAAI;YACP,OAAO,EAAE,IAAI;YACb,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;SAC5D,EACD,EAAE,CACH,CACF,CAAC;IACJ,CAAC,CACF,CAAC;AACJ,CAAC"}

package/dist/tools/evaluation/eval.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `rego_eval` and the three flag-extended variants.
+ *
+ * Each variant is a thin adapter — same input shape, different OPA
+ * flags — built on the shared `runEval` helper.
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { Config } from '../../config.js';
+export declare function registerRegoEval(server: McpServer, config: Config): void;
+//# sourceMappingURL=eval.d.ts.map

package/dist/tools/evaluation/eval.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"eval.d.ts","sourceRoot":"","sources":["../../../src/tools/evaluation/eval.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAK9C,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CA4DxE"}

package/dist/tools/evaluation/eval.js

@@ -0,0 +1,35 @@
+import { OpaCli } from '../../lib/opa-cli.js';
+import { withToolEnvelope } from '../../lib/tool-helpers.js';
+import { runEval, SharedEvalInput } from './_shared.js';
+export function registerRegoEval(server, config) {
+    const opa = new OpaCli(config);
+    server.registerTool('rego_eval', {
+        title: 'Evaluate Rego query',
+        description: 'Evaluate a Rego query against a policy and an input document using `opa eval`. Returns the standard `{result: [...]}` shape. The bread-and-butter authoring tool.',
+        inputSchema: SharedEvalInput,
+    }, async (args) => {
+        return withToolEnvelope(config, () => runEval(opa, config, args, {}));
+    });
+    server.registerTool('rego_eval_with_explain', {
+        title: 'Evaluate Rego with execution trace',
+        description: "Evaluate with `--explain=full` and return a structured trace alongside the result. Use this when an agent needs to see why a rule fired (or didn't) — the trace is the basis for `rego_explain_decision`.",
+        inputSchema: SharedEvalInput,
+    }, async (args) => {
+        return withToolEnvelope(config, () => runEval(opa, config, args, { explain: 'full' }));
+    });
+    server.registerTool('rego_eval_with_profile', {
+        title: 'Evaluate Rego with profiling',
+        description: 'Evaluate with `--profile` and return per-rule timing and evaluation counts. Use this to find hot rules in slow policies.',
+        inputSchema: SharedEvalInput,
+    }, async (args) => {
+        return withToolEnvelope(config, () => runEval(opa, config, args, { profile: true, metrics: true }));
+    });
+    server.registerTool('rego_eval_with_coverage', {
+        title: 'Evaluate Rego with coverage',
+        description: "Evaluate with `--coverage` and return per-line coverage data. Useful for verifying that tests actually exercise the rules they're meant to.",
+        inputSchema: SharedEvalInput,
+    }, async (args) => {
+        return withToolEnvelope(config, () => runEval(opa, config, args, { coverage: true }));
+    });
+}
+//# sourceMappingURL=eval.js.map

package/dist/tools/evaluation/eval.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"eval.js","sourceRoot":"","sources":["../../../src/tools/evaluation/eval.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAC9C,OAAO,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAC7D,OAAO,EAAE,OAAO,EAAE,eAAe,EAAuB,MAAM,cAAc,CAAC;AAE7E,MAAM,UAAU,gBAAgB,CAAC,MAAiB,EAAE,MAAc;IAChE,MAAM,GAAG,GAAG,IAAI,MAAM,CAAC,MAAM,CAAC,CAAC;IAE/B,MAAM,CAAC,YAAY,CACjB,WAAW,EACX;QACE,KAAK,EAAE,qBAAqB;QAC5B,WAAW,EACT,mKAAmK;QACrK,WAAW,EAAE,eAAe;KAC7B,EACD,KAAK,EAAE,IAAI,EAAE,EAAE;QACb,OAAO,gBAAgB,CAAiB,MAAM,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC;IACxF,CAAC,CACF,CAAC;IAEF,MAAM,CAAC,YAAY,CACjB,wBAAwB,EACxB;QACE,KAAK,EAAE,oCAAoC;QAC3C,WAAW,EACT,2MAA2M;QAC7M,WAAW,EAAE,eAAe;KAC7B,EACD,KAAK,EAAE,IAAI,EAAE,EAAE;QACb,OAAO,gBAAgB,CAAiB,MAAM,EAAE,GAAG,EAAE,CACnD,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAChD,CAAC;IACJ,CAAC,CACF,CAAC;IAEF,MAAM,CAAC,YAAY,CACjB,wBAAwB,EACxB;QACE,KAAK,EAAE,8BAA8B;QACrC,WAAW,EACT,0HAA0H;QAC5H,WAAW,EAAE,eAAe;KAC7B,EACD,KAAK,EAAE,IAAI,EAAE,EAAE;QACb,OAAO,gBAAgB,CAAiB,MAAM,EAAE,GAAG,EAAE,CACnD,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAC7D,CAAC;IACJ,CAAC,CACF,CAAC;IAEF,MAAM,CAAC,YAAY,CACjB,yBAAyB,EACzB;QACE,KAAK,EAAE,6BAA6B;QACpC,WAAW,EACT,6IAA6I;QAC/I,WAAW,EAAE,eAAe;KAC7B,EACD,KAAK,EAAE,IAAI,EAAE,EAAE;QACb,OAAO,gBAAgB,CAAiB,MAAM,EAAE,GAAG,EAAE,CACnD,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAC/C,CAAC;IACJ,CAAC,CACF,CAAC;AACJ,CAAC"}

package/dist/tools/evaluation/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Category B — Evaluation & testing.
+ *
+ * Tools in this category run Rego queries against policies + input,
+ * with optional trace/profile/coverage output. They wrap `opa eval`,
+ * `opa test`, and `opa bench`.
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { Config } from '../../config.js';
+export declare function registerEvaluationTools(server: McpServer, config: Config): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/tools/evaluation/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/tools/evaluation/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAM9C,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAK/E"}

package/dist/tools/evaluation/index.js

@@ -0,0 +1,11 @@
+import { registerRegoBench } from './bench.js';
+import { registerRegoCompileQuery } from './compile.js';
+import { registerRegoEval } from './eval.js';
+import { registerRegoTest } from './test.js';
+export function registerEvaluationTools(server, config) {
+    registerRegoEval(server, config); // registers rego_eval + 3 variants
+    registerRegoTest(server, config);
+    registerRegoBench(server, config);
+    registerRegoCompileQuery(server, config);
+}
+//# sourceMappingURL=index.js.map

package/dist/tools/evaluation/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/tools/evaluation/index.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC;AACxD,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAE7C,MAAM,UAAU,uBAAuB,CAAC,MAAiB,EAAE,MAAc;IACvE,gBAAgB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,mCAAmC;IACrE,gBAAgB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,iBAAiB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,wBAAwB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAC3C,CAAC"}

package/dist/tools/evaluation/test.d.ts

@@ -0,0 +1,28 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { Config } from '../../config.js';
+interface TestRecord {
+    location?: {
+        file?: string;
+        row?: number;
+        col?: number;
+    };
+    package?: string;
+    name?: string;
+    pass?: boolean;
+    fail?: boolean;
+    skip?: boolean;
+    duration?: number;
+    trace?: unknown;
+    output?: string;
+}
+export interface RegoTestOutput {
+    passed: number;
+    failed: number;
+    skipped: number;
+    total: number;
+    results: TestRecord[];
+    coverage?: unknown;
+}
+export declare function registerRegoTest(server: McpServer, config: Config): void;
+export {};
+//# sourceMappingURL=test.d.ts.map

package/dist/tools/evaluation/test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test.d.ts","sourceRoot":"","sources":["../../../src/tools/evaluation/test.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAsB9C,UAAU,UAAU;IAClB,QAAQ,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACzD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,UAAU,EAAE,CAAC;IACtB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CA+DxE"}

package/dist/tools/evaluation/test.js

@@ -0,0 +1,74 @@
+/**
+ * `rego_test` — run Rego unit tests via `opa test`.
+ *
+ * Returns per-test pass/fail records. With `coverage: true`, returns
+ * per-line coverage data alongside the test results.
+ */
+import { z } from 'zod';
+import { OpaCli } from '../../lib/opa-cli.js';
+import { err, ok } from '../../lib/errors.js';
+import { mapSubprocessFailure, tryParseJson, validatePaths, withToolEnvelope, } from '../../lib/tool-helpers.js';
+const RegoTestInput = {
+    paths: z
+        .array(z.string())
+        .min(1)
+        .describe('Test directories or files. `opa test` looks for `*_test.rego` siblings of source files.'),
+    verbose: z.boolean().optional().describe('Emit per-test pass/fail details.'),
+    coverage: z.boolean().optional().describe('Include per-line coverage data in the output.'),
+    runPattern: z.string().optional().describe('Run only tests whose names match this regex.'),
+};
+export function registerRegoTest(server, config) {
+    const opa = new OpaCli(config);
+    server.registerTool('rego_test', {
+        title: 'Run Rego tests',
+        description: 'Run Rego unit tests with `opa test`. Returns aggregate pass/fail counts plus per-test records. Tests live in `*_test.rego` files; rule names beginning with `test_` are picked up.',
+        inputSchema: RegoTestInput,
+    }, async ({ paths, verbose, coverage, runPattern }) => {
+        return withToolEnvelope(config, async () => {
+            const validation = validatePaths(paths, config, { mustExist: true });
+            if (!validation.ok)
+                return validation.error;
+            const result = await opa.test({
+                paths: validation.resolved,
+                verbose,
+                coverage,
+                runPattern,
+            });
+            const subprocessFailure = mapSubprocessFailure(result, 'opa');
+            if (subprocessFailure)
+                return subprocessFailure;
+            // `opa test --format=json` emits a JSON array (or sometimes
+            // newline-delimited objects depending on OPA version). Try the
+            // array form first; fall back to NDJSON.
+            let records = [];
+            const arrayParsed = tryParseJson(result.stdout);
+            if (Array.isArray(arrayParsed)) {
+                records = arrayParsed;
+            }
+            else {
+                for (const line of result.stdout.split(/\r?\n/)) {
+                    const trimmed = line.trim();
+                    if (trimmed.length === 0)
+                        continue;
+                    const parsed = tryParseJson(trimmed);
+                    if (parsed)
+                        records.push(parsed);
+                }
+            }
+            if (records.length === 0 && result.exitCode === 0) {
+                return err('NO_TESTS_FOUND', 'opa test did not discover any test rules in the provided paths.', { hint: 'Tests live in *_test.rego files with rules named test_*.' });
+            }
+            const passed = records.filter((r) => r.pass).length;
+            const failed = records.filter((r) => r.fail).length;
+            const skipped = records.filter((r) => r.skip).length;
+            return ok({
+                passed,
+                failed,
+                skipped,
+                total: records.length,
+                results: records,
+            });
+        });
+    });
+}
+//# sourceMappingURL=test.js.map

package/dist/tools/evaluation/test.js.map

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

package/dist/tools/helpers/describe-policy.d.ts

@@ -0,0 +1,26 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { Config } from '../../config.js';
+interface AstAnnotations {
+    title?: string;
+    description?: string;
+    related_resources?: unknown[];
+    authors?: unknown[];
+    organizations?: unknown[];
+}
+interface DescribedRule {
+    name: string;
+    isDefault: boolean;
+    hasArgs: boolean;
+    bodyLength: number;
+    annotations?: AstAnnotations;
+}
+export interface RegoDescribePolicyOutput {
+    package: string;
+    imports: string[];
+    ruleCount: number;
+    rules: DescribedRule[];
+    packageAnnotations?: AstAnnotations[];
+}
+export declare function registerRegoDescribePolicy(server: McpServer, config: Config): void;
+export {};
+//# sourceMappingURL=describe-policy.d.ts.map

package/dist/tools/helpers/describe-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"describe-policy.d.ts","sourceRoot":"","sources":["../../../src/tools/helpers/describe-policy.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAc9C,UAAU,cAAc;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iBAAiB,CAAC,EAAE,OAAO,EAAE,CAAC;IAC9B,OAAO,CAAC,EAAE,OAAO,EAAE,CAAC;IACpB,aAAa,CAAC,EAAE,OAAO,EAAE,CAAC;CAC3B;AAqBD,UAAU,aAAa;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,cAAc,CAAC;CAC9B;AAED,MAAM,WAAW,wBAAwB;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,aAAa,EAAE,CAAC;IACvB,kBAAkB,CAAC,EAAE,cAAc,EAAE,CAAC;CACvC;AAUD,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CA+DlF"}

package/dist/tools/helpers/describe-policy.js

@@ -0,0 +1,76 @@
+/**
+ * `rego_describe_policy` — parse a policy and return a structured
+ * summary an agent can read without re-implementing AST traversal.
+ */
+import { z } from 'zod';
+import { OpaCli } from '../../lib/opa-cli.js';
+import { err, ok } from '../../lib/errors.js';
+import { mapSubprocessFailure, tryParseJson, withToolEnvelope } from '../../lib/tool-helpers.js';
+const RegoDescribePolicyInput = {
+    source: z.string().min(1).describe('Rego source to describe.'),
+};
+function refToString(parts) {
+    if (!parts)
+        return '';
+    return parts
+        .map((p) => (typeof p.value === 'string' ? p.value : ''))
+        .filter(Boolean)
+        .join('.');
+}
+export function registerRegoDescribePolicy(server, config) {
+    const opa = new OpaCli(config);
+    server.registerTool('rego_describe_policy', {
+        title: 'Describe Rego policy',
+        description: 'Parse a Rego policy and return a structured summary: package, imports, rules (with default/args/body-length flags), and inline annotations. Useful as the first step in any "what does this policy do" workflow.',
+        inputSchema: RegoDescribePolicyInput,
+    }, async ({ source }) => {
+        return withToolEnvelope(config, async () => {
+            const result = await opa.parse({ source });
+            const subprocessFailure = mapSubprocessFailure(result, 'opa');
+            if (subprocessFailure)
+                return subprocessFailure;
+            if (result.exitCode !== 0) {
+                return err('INVALID_REGO', 'opa parse rejected the source.', {
+                    details: { stderr: result.stderr.trim() },
+                });
+            }
+            const ast = tryParseJson(result.stdout);
+            if (ast === undefined) {
+                return err('UNKNOWN_ERROR', 'opa parse produced no parseable JSON.');
+            }
+            const packageParts = ast.package?.path?.slice(1) ?? [];
+            const packageName = refToString(packageParts);
+            const imports = (ast.imports ?? []).map((imp) => {
+                const path = refToString(imp.path?.value);
+                return imp.alias ? `${path} as ${imp.alias}` : path;
+            });
+            const seen = new Map();
+            for (const rule of ast.rules ?? []) {
+                const name = rule.head?.name ?? refToString(rule.head?.ref);
+                if (!name)
+                    continue;
+                const existing = seen.get(name);
+                if (existing) {
+                    existing.bodyLength += rule.body?.length ?? 0;
+                    continue;
+                }
+                seen.set(name, {
+                    name,
+                    isDefault: rule.default === true,
+                    hasArgs: Array.isArray(rule.head?.args) && (rule.head?.args.length ?? 0) > 0,
+                    bodyLength: rule.body?.length ?? 0,
+                    annotations: rule.annotations,
+                });
+            }
+            const rules = [...seen.values()];
+            return ok({
+                package: packageName,
+                imports,
+                ruleCount: rules.length,
+                rules,
+                packageAnnotations: ast.annotations,
+            });
+        });
+    });
+}
+//# sourceMappingURL=describe-policy.js.map

package/dist/tools/helpers/describe-policy.js.map

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

package/dist/tools/helpers/explain-decision.d.ts

@@ -0,0 +1,41 @@
+/**
+ * `rego_explain_decision` — run a query with `--explain=full` and
+ * return a structured trace plus a per-rule summary an agent can
+ * narrate.
+ *
+ * The actual rego_eval_with_explain returns OPA's raw trace; this
+ * tool digests it slightly: counts the events per rule, surfaces the
+ * final result, and lists the rules that fired vs the rules that
+ * matched but evaluated to false.
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { Config } from '../../config.js';
+interface TraceEvent {
+    op?: string;
+    type?: string;
+    query_id?: number;
+    parent_id?: number;
+    message?: string;
+    location?: {
+        file?: string;
+        row?: number;
+        col?: number;
+    };
+    node?: unknown;
+}
+export interface RegoExplainDecisionOutput {
+    result: unknown;
+    errors?: unknown[];
+    rulesFired: string[];
+    rulesEvaluated: string[];
+    trace: TraceEvent[];
+    summary: {
+        totalEvents: number;
+        enterEvents: number;
+        exitEvents: number;
+        failEvents: number;
+    };
+}
+export declare function registerRegoExplainDecision(server: McpServer, config: Config): void;
+export {};
+//# sourceMappingURL=explain-decision.d.ts.map

package/dist/tools/helpers/explain-decision.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"explain-decision.d.ts","sourceRoot":"","sources":["../../../src/tools/helpers/explain-decision.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAM9C,UAAU,UAAU;IAClB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACzD,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,yBAAyB;IACxC,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,EAAE,CAAC;IACnB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,OAAO,EAAE;QACP,WAAW,EAAE,MAAM,CAAC;QACpB,WAAW,EAAE,MAAM,CAAC;QACpB,UAAU,EAAE,MAAM,CAAC;QACnB,UAAU,EAAE,MAAM,CAAC;KACpB,CAAC;CACH;AAkCD,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CA8CnF"}