OPA MCP

Format Rego source code using `opa fmt`. Returns the formatted source and a `changed` flag indicating whether the input was already canonical. When the source uses string interpolation ($"..." or $`...` syntax) and OPA v1.12.0 or v1.12.1 is detected, the tool warns about or blocks formatting due to a known OPA bug that corrupts \{ escape sequences (fixed in OPA v1.12.2).

Type-check Rego with `opa check`. Returns `{ valid: true, errors: [] }` on success, or a list of structured diagnostics with file/line locations on failure. Provide either `source` for inline checking or `paths` for file/directory checking.

Validate that a Rego policy's input.* field references are consistent with a JSON Schema using `opa check --schema`. Every field the policy reads from `input` must exist in the schema; mismatches surface as rego_type_error diagnostics with file/line locations. Returns `{ valid: true, errors: [] }` when all references match the schema, or `{ valid: false, errors: [...] }` with structured diagnostics when they do not. Accepts the schema inline (pass the `schema` output of `rego_infer_input_schema` directly as `inlineSchema`) or as a path to a JSON Schema file on disk, or to a schema directory when the policy declares `schemas:` annotations (`schemaPath`). Provide `source` for inline Rego or `paths` for file/directory checking.

Lint Rego source with the Regal linter. Returns categorized violations (style, bugs, idiomatic, performance) with file/line locations. Requires `regal` on PATH or `REGAL_BINARY` set; returns REGAL_NOT_FOUND otherwise. When called with inline `source`, location-bound rules whose verdict depends on the on-disk path (`directory-package-mismatch`) are auto-disabled to avoid temp-file false positives, and `location.file` is reported as `<inline>` instead of the randomized temp path. Re-enable those rules via `enable` if your workflow actually needs them.

Parse Rego source to a JSON AST using `opa parse`. Returns the AST as a tree of nodes (package, imports, rules, expressions, terms). Use this when you need to introspect policy structure programmatically.

Inspect an OPA bundle, policy directory, or single Rego file with `opa inspect`. Returns manifest data, namespaces, rule annotations, and (if signed) signature metadata.

Return OPA capabilities -- the available builtins, future keywords, features, and WASM ABI versions. With `current: true`, returns the running OPA's capabilities. With `version: "v1.19.0"`, returns those of a specific version. With neither, lists available named versions. By default (`names_only: true`), returns only builtin names and count to stay within response size limits. Pass `builtins: [...]` for the full type signatures and documentation of a few named builtins; `names_only: false` returns every full record, which needs OPA_MCP_MAX_RESPONSE_BYTES raised above its default.

Static dependency analysis for a Rego reference. Given a target ref like "data.example.allow", returns the base document references (input/data leaves) and virtual document references (rules) it depends on, transitively.

Migrate Rego v0 source to Rego v1. First renames what v1 reserves (a rule called `contains`, `every`, `if` or `in`, and every reference to it in the module) and replaces built-ins v1 removed: `re_match` and `net.cidr_overlap` by their v1 names, and `all`, `any`, `set_diff` and the `cast_*` family by a helper function appended to the module that returns exactly what the built-in did, so behaviour does not change. `re_match` and `net.cidr_overlap` get such a helper too where the rename would change behaviour: the module mocks one spelling with `with` while calling both, or binds `regex` or `net` itself. Then `opa fmt --rego-v1` converts the syntax (`if`, `contains`, `import rego.v1`) and `opa check` validates the result. `rewrites` lists each change by line and `notes` says why; a renamed rule must also be renamed in any other module that uses it. Pass `inputs` to evaluate the original as v0 and the result as v1 against each and compare every rule of the package, and `queries` to compare expressions too, such as calls to its functions; `equivalence` reports any difference. Evaluating runs the policy, `http.send` included. Returns the migrated source even when check finds remaining errors. A source that parses only as Rego v1 is returned unchanged; one that parses as both, such as v1 that imports `rego.v1`, is reformatted like any other. If the source parses as neither, returns `INVALID_REGO` with opa's own message.

Evaluate a Rego query against a policy and an input document using `opa eval`. Returns the standard `{result: [...]}` shape plus `defined`, which is false when the query produced no value (undefined is not `false`), and `printed`, the lines the policy wrote with `print()`. The bread-and-butter authoring tool. The policy is optional, so a query alone tries out a built-in or an expression. Pass `inputs` to evaluate one query against many input documents in one call, and `v0Compatible` for a policy still written in pre-1.0 Rego.

Evaluate with `--explain=full` and return OPA's raw trace events (with their AST nodes) alongside the result. For a readable trace use `rego_explain_decision`, which renders the same events as lines. Raw events are large: over the response cap the bound-variable values are dropped first, then trailing events (`explanationTruncated`), and the result is kept.

Evaluate with `--profile` and return per-rule timing and evaluation counts. Use this to find hot rules in slow policies.

Evaluate with `--coverage` and return per-line coverage data. Useful for verifying that tests actually exercise the rules they're meant to.

Run Rego unit tests with `opa test`. Returns aggregate pass/fail/skip/error counts plus per-test records. `errored` counts tests OPA could not evaluate (a rule conflict, a raising built-in); such a test is neither a pass nor a failure, and a suite with any is not passing. Tests live in `*_test.rego` files; rule names beginning with `test_` are picked up automatically. Use `runPattern` to filter by name regex; when no tests match, the error hint includes the pattern you supplied. Use `threshold` to gate on minimum coverage (returns COVERAGE_BELOW_THRESHOLD on failure). Use `varValues: true` with `verbose: true` to include local variable bindings in the trace -- essential for debugging table-driven tests written with `every tc in cases { ... }` to identify which case caused a failure. When tests use the `test_x[case]` parameterized form, OPA reports the rule as a single test whatever the number of cases; `parameterizedGroups` maps the rule name to a record per case and `caseCounts` totals them, so a failing rule says which case failed. Use `ignorePatterns` to exclude generated or fixture files. Use `bundle: true` when testing bundle-structured policy directories. Use `timeout` to raise the per-test limit beyond OPA's default 5s. Note: enabling `coverage` or `threshold` switches OPA to coverage-report output mode -- per-test counts are unavailable but `coverage` and `coveragePct` fields are populated.

Run `opa test` once per root and aggregate results. Solves the package-conflict problem that occurs when `opa test .` is run on a repo with multiple independent package namespaces (OPA issue #4724). Two modes: `explicit` (supply root list with optional per-root `include` paths for shared libraries) and `scan` (auto-discover leaf test roots using the leaf rule -- a directory is a root only if it directly contains `*_test.rego` files and none of its eligible subdirectories do, preventing OPA's automatic recursion from double-running tests). Use `sharedPaths` in scan mode to add shared library directories to every root's invocation without including them in discovery. Coverage and threshold work per-root; `overallCoveragePct` is the mean across roots that have coverage data.

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.

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.

Evaluate a policy decision against one or more input files using `opa exec --format=json`. Unlike `rego_eval` (single input), `opa exec` processes every file independently and returns a per-file result -- ideal for CI pipelines that check many config files against a policy in one call. Supply `bundle` for a bundle, or `dataPaths` for plain `.rego`, JSON and YAML files and directories, which are loaded as `opa eval --data` loads them; the two are mutually exclusive. Each file that fails evaluation appears in `results` with an `error` field rather than a `result` field. Set one of `fail`/`failDefined`/`failNonEmpty` to turn the call into a CI gate: the result then reports `failed: true` (instead of erroring) when the gate condition is met.

Build a deployable bundle from policy / data paths using `opa build`. Output is a `.tar.gz` archive with optional inline signing. Supports optimization, custom revision strings, and the WASM target.

Sign a bundle directory with `opa sign`. A directory is signed in place: `.signatures.json` is written into it and files are recorded as `<directory name>/<file>`, so the signed directory verifies wherever it is placed as long as its name is unchanged, with `opa_bundle_verify` or with `opa build` or `opa run --bundle <name>` from its parent. An archive is refused: OPA reads the signature from inside it, so a signed archive comes from `opa_bundle_build` with `signingKey`. The key is a PEM private key (RSA or ECDSA); for HMAC algorithms pass a file holding the secret. Extra claims such as `keyid` and `scope` come from `claimsFile`. Returns the path written, the algorithm, and the number of files covered.

Verify the signature of a signed bundle directory or `.tar.gz` archive with the public key. OPA has no standalone verify command, so this runs `opa build --verification-key` into a private temp file that is discarded. A directory is verified by name from its parent, matching how `opa_bundle_sign` signs it. OPA reads the key, checks the JWT in `.signatures.json`, compares the scope claim, then checks every file: Rego files by digest before parsing, data files and `.manifest` by parsed value, so an unparseable data file fails before its digest is compared. Failures return `INVALID_BUNDLE` with `details.reason` set to one of signature_invalid, scope_mismatch, file_modified, file_added, file_missing, file_unparseable, unsigned, signatures_malformed, not_a_bundle, bundle_load_error, or unknown when the message is not recognised; the raw output is in `details`. A key or algorithm OPA cannot use returns `INVALID_INPUT`. Pass `scope` exactly as the bundle was signed with. With a single key OPA does not check `verificationKeyId` against the signature keyid claim. `verified: true` is returned only when OPA loaded the bundle with its signature intact.

List policies registered on the running OPA server. Returns the policy IDs and a count. Set `includeSource` for the Rego text of every policy, or `includeAst` for the parsed AST of every policy; both are off by default because either one pushes a list of any real size past the response cap.

Fetch a single policy by ID from the running OPA server. Returns the Rego source; the parsed AST is omitted unless asked for, since it is roughly forty times the size of the source it came from. Use `rego_parse_ast` on the source when an AST is what's wanted.

Upload a Rego policy under the given ID. Replaces any existing policy with that ID; `replaced` says whether one existed. The policy is uploaded as raw text/plain and OPA compiles it on the server, so a policy that does not compile comes back as INVALID_REGO with OPA's errors, and nothing is stored.

Delete a policy by ID from the running OPA server.

Read a path from OPA's data hierarchy. A `path` is read as dotted (`users.alice`) unless it contains a slash, in which case slash is the only separator (`users/alice`), so a key such as `example.com` is addressable as `hosts/example.com`. Pass `segments` instead when a key contains both.

Write or replace a value at the given data path. Body is sent as JSON. A `path` is read as dotted (`users.alice`) unless it contains a slash, in which case slash is the only separator (`users/alice`), so a key such as `example.com` is addressable as `hosts/example.com`. Pass `segments` instead when a key contains both.

Apply a JSON Patch (RFC 6902) to the data document. Each operation is `{ op, path, value? }`. Omit both `path` and `segments` to patch the root of the data hierarchy, which is how a whole new top-level document is added.

Remove a document from OPA's data store at the given path. A `path` is read as dotted (`users.alice`) unless it contains a slash, in which case slash is the only separator (`users/alice`), so a key such as `example.com` is addressable as `hosts/example.com`. Pass `segments` instead when a key contains both. OPA responds with 204 No Content on success; if no document exists at the path, OPA returns 404 which is mapped to `DATA_NOT_FOUND`. Root-path deletion (`/v1/data/` itself) is intentionally excluded -- supply at least one path segment.

Evaluate a decision against the running OPA server. POSTs to the data path with `{input}` and returns whatever the rule produces, plus `defined`: false when the path produced no value, which OPA reports by leaving `result` out. Undefined is not `false`; a caller that treats it as false or as allow decides on something the policy never said. Use this to ask the server "given this input, what does data.X.allow say?"

Send a query to the OPA server's `/v1/compile` endpoint for partial evaluation. Returns the residual query -- what remains after substituting in everything that's known.

Hit the OPA `/health` endpoint. A server that answers reports `{ healthy: true }` on 200 and `{ healthy: false }` with OPA's own reason otherwise, so an unactivated bundle is a health result rather than a tool error. `OPA_UNREACHABLE` means the server could not be reached at all. Supports `bundles` and `plugins` query flags to require those subsystems to also be healthy.

Return the running OPA server configuration via `GET /v1/config`. Returns the same underlying document as `opa_config` but presented under a `status` key as a convenience for agents that want to check "what is running" rather than "what was the server configured with". The response includes bundle settings, decision-log settings, and plugin configuration as OPA reported them at startup. Service header values are redacted, since OPA returns them verbatim and a header is the ordinary place to put an API key.

无需输入参数。

Return the running OPA server configuration from `GET /v1/config`. OPA drops the `credentials` block but returns `services.*.headers` verbatim, which is the ordinary place to put an API key or a bearer token, so those values are redacted here and the header names kept.

无需输入参数。

Evaluate a Rego query with full tracing and return the result, the rules entered (`rulesEvaluated`) and those that produced a value (`rulesFired`), and the trace as readable lines: location, nesting, operation, the expression in Rego syntax, and the values of the variables it names. Backtracking (Redo) events are left out. Use it to answer "why was this denied?" or "why did this rule not match?": the `Fail` lines name the condition that stopped a rule. A trace too long for the response cap is cut from the end (`traceTruncated`); narrow the query or the input to see the rest.

Diagnose why a fully-qualified Rego query (e.g. "data.authz.allow") produces no value, or falls back to its default. Combines a plain eval, a full-trace eval, and per-condition AST analysis to identify the exact body expression blocking each rule. Handles both runtime failures (trace-based) and indexer elimination (standalone condition eval). A rule written with `default allow := false` always has a value, so `queryResult` reports `default` for it and the same per-rule breakdown follows: the question "why is allow false" is the question this answers. A multi-value rule such as `deny contains msg if ...` that holds no element reports `empty` with the same breakdown, which answers "why was this not denied". Returns a structured breakdown of which conditions blocked each rule plus a human-readable summary. `paths` may name directories, which are searched for the modules that declare the queried package.

Generate a `*_test.rego` skeleton from a policy. Parses the AST, finds each non-test rule, and emits one stub test per rule. Existing `test_*` and `todo_test_*` rules are skipped automatically -- only production rules get stubs. Every stub is a `todo_test_` rule, which `opa test` reports as skipped (and exits non-zero for) until a realistic input and the expected value are filled in and it is renamed `test_`: a placeholder input against a placeholder expectation would otherwise pass while testing nothing. The AST is walked to infer which `input.*` fields the policy accesses; the inferred shape is used as the placeholder `with input as {...}` in each stub, so the developer only needs to fill in realistic values rather than guess the structure. With `tableStyle: true`, each stub uses an `every tc in cases { ... }` loop so you can add multiple input/expected pairs without duplicating assertion code. The `inferredInputShape` field in the response shows the detected shape for reference.

Parse a Rego policy and return a structured summary: package, imports, and rules. Each rule reports clauseCount (how many definitions share the name), isDefault (true if any clause is a default), hasArgs, bodyLength (total body expressions across all clauses), and inline annotations. Useful as the first step in any "what does this policy do" workflow.

Map common Rego compile errors and Regal lint findings to fix suggestions. Pass `errors` from `rego_check` or `violations` from `rego_lint` unchanged. Returns one suggestion per diagnostic; confidence is `high` for well-known patterns, `medium` where the answer is the rule's documentation (`docs`), `low` for everything else.

Run opa test --coverage and return a per-file breakdown of uncovered line ranges. Identifies which rules or branches are not yet exercised by tests. Files are sorted by coverage ascending so the worst-covered files appear first. Use threshold to limit the report to files below a target coverage percentage.

Run regal lint restricted to its `bugs` category plus any custom rules placed in a `security` category, across one or more policy directories, and return the findings grouped by severity (high/medium) with remediation guidance and a link to each rule. Use it for a periodic fleet-wide sweep rather than per-file style review. Modules that do not parse are listed in `unparseable` and the rest are audited. These are lint findings: a policy with none can still let a request through, so probe it with `rego_eval` inputs (absent, null and wrong-typed fields) for that. Requires regal.

Statically analyse one or more Rego policies and return a JSON Schema (draft-07) object describing every input.* field the policies read. It follows the ways a policy reads input: loop variables (`some c in input.containers` then `c.image`), rules whose value is an input path (`pod_spec := input.request.object.spec`), function parameters (`trusted(c)`) and `object.get` keys. A key the policy computes is left open, and a scalar type is set only where a comparison with a literal, an `is_*` check or a string built-in shows it. Uses opa parse -- no running OPA server required. A starting point for test inputs and for a schema to give rego_check_schema; review it first, since types the policy never shows are left out. Accepts inline source, individual files, or directories (walked recursively for *.rego files).

Run regal fix to automatically apply mechanical fixes. Regal 0.42 fixes opa-fmt, use-rego-v1, use-assignment-operator, no-whitespace-comment, directory-package-mismatch, non-raw-regex-pattern, prefer-equals-comparison, redundant-existence-check and constant-condition; older releases fix a subset. Use dryRun: true to preview changes before modifying files. NOTE: directory-package-mismatch moves files to match their package path -- use disable: ["directory-package-mismatch"] to skip it. Regal before 0.41 refuses files with uncommitted git changes unless force: true. Requires regal.

Run `opa fmt --write` to canonically format one or more Rego files or directories in place. Use `dryRun: true` to preview which files would change without modifying them. Returns a list of files that were (or would be) reformatted. Unlike `rego_format` which returns formatted source as a string, this tool writes directly to disk. Supports `regoV1`, `v0Compatible`, and `v1Compatible` flags for version-specific formatting. If any file cannot be parsed, the operation is aborted and no files are written.

Evaluate the same query against two policies (or two versions of the same policy) and compare the results. Both evaluations run in parallel. Returns `equal: true/false`, the raw result from each side, and `changedPaths` -- the dot/bracket paths that differ. Useful for verifying that a refactor preserves behavior, or understanding exactly where two policies diverge. Each side takes either inline source (sourceA/sourceB) or a file/directory path (pathA/pathB). The same input and query are used for both evaluations; pass `inputs` to compare on many input documents in one call, and `dataPaths` to load the data the policies read.

Formally verify a property about a Rego rule using SMT solving (Microsoft Z3). Unlike testing, this checks ALL possible inputs and either proves the property holds or returns a concrete counterexample input that falsifies it. Supports equality, comparison, startswith, endswith, contains, and simple regex.match patterns (prefix: ^lit.*, suffix: .*lit$, exact: ^lit$, contains: .*lit.*, wildcard: .*). Complex regex patterns (character classes, quantifiers, alternation) return INCONCLUSIVE. Also reports INCONCLUSIVE for negation-as-failure (not), comprehensions, partial set and object rules (deny contains msg), functions, else chains, and any operand it cannot encode. A body that reads an absent field is undefined rather than true, so always_true holds only if the rule is also true for an empty input: a rule requiring input.x will be answered with the counterexample {}.

Share a Rego policy with teammates or create a reproducible example by publishing it as a GitHub Gist, secret unless `public: true` is passed, so only people holding the link can read it. Returns { gistUrl, rawPolicyUrl, id, public }: the gistUrl renders the policy with syntax highlighting on github.com; the rawPolicyUrl can be passed directly to OPA (`opa eval -d <rawPolicyUrl> <query>`) or used as a data source in Conftest. When query, input, or data are supplied, a metadata.json file is bundled into the Gist so recipients have the full evaluation context to reproduce results. Each call creates a new Gist -- use the returned id to reference it later. Requires GITHUB_TOKEN in the environment (GitHub personal access token with the "gist" scope); returns GITHUB_TOKEN_MISSING with setup instructions if unset.

Evaluate configuration files (Kubernetes manifests, Terraform plans, Dockerfiles, Helm charts, or any YAML/JSON/HCL/TOML/INI) against Rego policies using `conftest test`. Returns per-file, per-namespace pass/fail/warn results so you can pinpoint exactly which policy rules fired. Requires `conftest` on PATH or `CONFTEST_BINARY` set; returns CONFTEST_NOT_FOUND otherwise. Provide config via `files` (disk paths) or `inlineConfig` (inline string). Provide policy via `policy` (disk path) or `inlinePolicy` (inline Rego source). Omit `policy` and `inlinePolicy` to use conftest's default `./policy` directory. Policies are executed by conftest and can call OPA built-ins such as http.send. A run in which no rule was evaluated (wrong `namespace`, or no `deny`/`violation`/`warn` rules) is reported as `passed: false` with `nothingEvaluated: true` and the namespaces that do hold rules, where conftest itself would exit 0.

Run the `test_*` rules inside `*_test.rego` files within a conftest policy directory, verifying that the policies themselves are correct. Equivalent to `opa test` but using conftest's policy-loading machinery. Returns per-file pass/fail results, and NO_TESTS_FOUND when the directory holds no test rules. Requires `conftest` on PATH or `CONFTEST_BINARY` set; returns CONFTEST_NOT_FOUND otherwise.

Download Rego policies from an OCI registry or Git repository into a local directory using `conftest pull`. Use this to hydrate a local `policy/` directory before running `conftest_test`. Requires `conftest` on PATH or `CONFTEST_BINARY` set. The `policy` directory must be inside OPA_MCP_ALLOWED_PATHS. SECURITY: pulled policies are arbitrary Rego source that will be executed by `conftest_test`. Only pull from registries or repositories you own or explicitly trust -- malicious policy code can use OPA built-ins (http.send, opa.runtime) to exfiltrate data or make outbound network requests when the tests run.

Package the local Rego policy directory as an OCI artifact and push it to a registry using `conftest push`. Registry credentials must be pre-configured in the host environment (docker login, ORAS keychain, etc.) -- this tool never handles credentials. The `policy` directory must be inside OPA_MCP_ALLOWED_PATHS. Requires `conftest` on PATH or `CONFTEST_BINARY` set.

Return the name, version, and runtime details of this opa-mcp server instance. Use this when you need to confirm which version of opa-mcp is running, or to verify that the OPA, Regal, and Conftest binaries are reachable.

无需输入参数。