io.github.coderifts/api-governance

Official3 toolsLive

by coderifts · JavaScript

Signed, offline-verifiable contract-change authorization. Only a granted change can proceed.

The io.github.coderifts/api-governance MCP server provides API governance for AI agents. It detects breaking changes, scores blast radius, and blocks unsafe calls to help manage how agents interact with APIs.

🛠️ Key Features

Detects breaking changes
Scores blast radius
Blocks unsafe calls

🚀 Use Cases

Preventing unsafe API interactions by AI agents
Managing risk from API changes across agent workflows

⚡ Developer Benefits

Structured governance signals via breaking-change detection and blast-radius scoring
Clear enforcement by blocking unsafe calls

⚠️ Limitations

No additional tool count, topics, or further capabilities are provided in the available server data
The provided excerpt contains CodeRifts self-hosting Docker Compose instructions, but does not describe this MCP server’s tooling or configuration details

Topics

ai-agentsapi-contractapi-governancebreaking-changesdeveloper-toolsmcpmcp-servermodel-context-protocolopenapiopenapi3

Captured live from the server via tools/list.

preflight_change_set

Use this when: a contract artifact (OpenAPI, GraphQL, protobuf, AsyncAPI, MCP manifests, or agent tool schemas) changes before merge, deploy, publish, or tool registration; AND any agent-executed operation with no supported contract type — send type agent_operation. Do not call for documentation-only changes, static readiness scoring, or receipt verification. Use analyze for risk only; authorize requires context.operation. Skipping this call is not permission. Absence of a key is not permission. Inputs: preflight_mode is required: "analyze" (risk only; no receipt, no execution_action) or "authorize" (may mint a receipt; requires context.operation — merge is not deploy is not publish). Supply exactly one artifact source: artifacts[] (1–20 items, each {id, type, before, after} as the FULL spec/schema text, not a path or URL; type is openapi|graphql|grpc|asyncapi|mcp_manifest|agent_tools|agent_operation) XOR derivation="server" (server reads GitHub Compare; needs context.repository + context.base + context.head; sending artifacts[] together is 400). Grant fields sit in one object, execution_grant_request {include_execution_grant, grant_version, tenant_id, executor_id, adapter_id, target_uri, expected_state_token, state_nonce, audience, policy_hash}; analyze ignores it; required is preflight_mode only. previous_receipt is a chain token base64url(body).base64url(signature) to LINK a prior decision — it does not re-verify; use coderifts.verify_receipt instead; for details of a past decision use coderifts.get_decision_details instead. idempotency_key replays authorize only (24h), never analyze.

Parameters9

artifacts	array	optional	1–20 contract documents analyzed together. Each item is {id, type, before, after} where before/after are the FULL document strings (YAML/JSON/proto text), not URLs or file paths. Omit this array entirely when derivation="server".
context	object	optional	Optional apply-site context folded into the bundle fingerprint. operation distinguishes merge vs deploy vs publish (and other labels); the server accepts any non-empty string; conventional values: merge, deploy, tool_call, publish. The receipt/gate must match this label.
previous_receipt	string	optional	Optional prior chain token to LINK this call into a receipt chain: base64url(body).base64url(signature). Linking is not verification — a linked token is not re-checked here; use verify_receipt.
execution_grant_request	object	optional	Authorize + include_execution_grant only: the execution-grant request fields. Analyze ignores them. Flat root-level spellings are also accepted; the same field sent both ways with different values is INVALID_INPUT.
response_detail	string	optional	How much of the response to return. control = the fields an agent branches on; standard = control + the human report and labelled break rows (the MCP default); full = everything (the REST default). Every value is copied from the full response.
idempotency_key	string	optional	Optional client key; in authorize mode, a repeat with the same key + body replays the original decision (24h). Analyze responses are not replayed.
preflight_mode	string	required	REQUIRED. "analyze" = informational risk only (no decision/execution_action/safe_for_agent; analysis_outcome + may_execute:false). "authorize" = operation-bound path; may mint a receipt (requires context.operation). Decision Spec 2.0: omission is INVALID_INPUT. Do not pin 1.0 — that pin retired.
decision_spec_version	string	optional	Optional. Omit or '2.0' = current contract. '1.0' retired (INVALID_INPUT); do not pin 1.0.
derivation	string	optional	"server" = the server derives artifacts[] from GitHub Compare via the App installation. Allowed only when context.repository, context.base and context.head are all present and the tenant has a proven binding for that repository. Do not send artifacts[] in the same call (400 — one source of truth). Omit this field for the caller-supplied artifacts[] path.

Raw schema

{
  "type": "object",
  "properties": {
    "artifacts": {
      "type": "array",
      "description": "1–20 contract documents analyzed together. Each item is {id, type, before, after} where before/after are the FULL document strings (YAML/JSON/proto text), not URLs or file paths. Omit this array entirely when derivation=\"server\".",
      "minItems": 1,
      "maxItems": 20,
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Caller-chosen id, unique within the bundle"
          },
          "type": {
            "type": "string",
            "enum": [
              "openapi",
              "graphql",
              "grpc",
              "asyncapi",
              "mcp_manifest",
              "agent_tools",
              "agent_operation"
            ],
            "description": "Artifact kind. One of openapi, graphql, grpc, asyncapi, mcp_manifest, agent_tools, agent_operation. Contract types determine how before/after text is parsed. agent_operation: An opaque proposed agent operation for which no supported contract-artifact type applies. CodeRifts does not semantically analyze this content and does not issue an execution grant. Not inferred from the filename."
          },
          "before": {
            "type": "string",
            "description": "The baseline document as raw text (the spec/schema/manifest body). Empty string means \"no prior version\" (create), not \"load from disk\"."
          },
          "after": {
            "type": "string",
            "description": "The proposed document as raw text, same kind as before. Must be the bytes you intend to merge/deploy/publish, not a diff."
          }
        },
        "required": [
          "id",
          "type",
          "before",
          "after"
        ]
      }
    },
    "context": {
      "type": "object",
      "description": "Optional apply-site context folded into the bundle fingerprint. operation distinguishes merge vs deploy vs publish (and other labels); the server accepts any non-empty string; conventional values: merge, deploy, tool_call, publish. The receipt/gate must match this label.",
      "properties": {
        "operation": {
          "type": "string",
          "description": "Application operation for this change set (fingerprint + envelope). Server accepts any non-empty string; conventional values: merge, deploy, tool_call, publish. Merge is not deploy is not publish — the receipt/gate must match this label."
        },
        "environment": {
          "type": "string",
          "description": "Target environment (e.g. production, staging, npm) — optional; folded into fingerprint when set."
        },
        "repository": {
          "type": "string",
          "description": "Repository identity (optional; fingerprint context)"
        },
        "branch": {
          "type": "string",
          "description": "Branch name (optional; fingerprint context)"
        },
        "pull_request": {
          "description": "Pull request id when applicable (optional; fingerprint context)",
          "oneOf": [
            {
              "type": "string"
            },
            {
              "type": "number"
            }
          ]
        },
        "policy_profile": {
          "type": "string",
          "description": "Policy profile name (optional; fingerprint context)"
        },
        "base": {
          "type": "string",
          "description": "Base commit/ref SHA the change set was computed against (optional; PR/commit identity)"
        },
        "head": {
          "type": "string",
          "description": "Head commit/ref SHA of the proposed change (optional; PR/commit identity)"
        },
        "target_id": {
          "type": "string",
          "description": "Optional apply-site target (IntentContext parity; not folded into the bundle fingerprint)"
        },
        "target_uri": {
          "type": "string",
          "description": "Optional apply-site URI the cr.exec.v2 grant binds (handler fallback: input.target_uri, then context.target_uri, then repository/head-derived). Distinct from target_id."
        },
        "fingerprint": {
          "type": "string",
          "description": "Optional change fingerprint (IntentContext parity; not folded into the bundle fingerprint)"
        },
        "audience": {
          "type": "string",
          "description": "Optional audience (IntentContext parity; REST/MCP accept, server-derived audience still wins on the envelope)"
        }
      }
    },
    "previous_receipt": {
      "type": "string",
      "description": "Optional prior chain token to LINK this call into a receipt chain: base64url(body).base64url(signature). Linking is not verification — a linked token is not re-checked here; use verify_receipt."
    },
    "execution_grant_request": {
      "type": "object",
      "description": "Authorize + include_execution_grant only: the execution-grant request fields. Analyze ignores them. Flat root-level spellings are also accepted; the same field sent both ways with different values is INVALID_INPUT.",
      "properties": {
        "include_execution_grant": {
          "type": "boolean",
          "description": "Authorize only. When true on an allow-class authorize, the response includes a signed execution_grant, or HTTP 503 SIGNER_UNAVAILABLE — never an unsigned grant. Default false. Analyze ignores this flag. Ignored unless preflight_mode=\"authorize\"."
        },
        "state_nonce": {
          "type": "string",
          "description": "Authorize+grant only. Opaque nonce copied into the signed grant as its own field (not folded into scope_hash). Absent → BEARER grant. Ignored unless include_execution_grant is true."
        },
        "grant_version": {
          "type": "string",
          "enum": [
            "v1",
            "v2"
          ],
          "x-coderifts-effective-default": "v2",
          "x-coderifts-default-changes-at": "2026-09-18",
          "description": "Grant envelope to mint when include_execution_grant is true. Omitting this yields cr.exec.v1 until 2026-09-18 and cr.exec.v2 on and after it (see x-coderifts-effective-default / x-coderifts-default-changes-at). The response meta.grant_version is the version actually issued. An explicit value always wins — pin \"v1\" to keep current behaviour with no code change on the date."
        },
        "tenant_id": {
          "type": "string",
          "description": "Authorize+grant v2 only. Tenant the grant is issued under. ASCII slug. When omitted the server uses \"default\" — pin it if you are not on the default tenant."
        },
        "executor_id": {
          "type": "string",
          "description": "Authorize+grant v2 only. Executor identity the grant is bound to (example: agent:ci-bot, host:github-actions). Empty/absent is not \"any executor\"."
        },
        "adapter_id": {
          "type": "string",
          "description": "Authorize+grant v2 only. Adapter that will apply the change. Conventional values: fs, postgres, git. Must match the adapter the executor actually uses; a git grant does not authorize an fs write."
        },
        "target_uri": {
          "type": "string",
          "description": "Authorize+grant v2 only. URI the grant binds (example: git://owner/repo.git/refs/heads/main). Fallback if omitted: context.target_uri, then repository/head-derived. Distinct from context.target_id."
        },
        "expected_state_token": {
          "type": "string",
          "description": "Authorize+grant v2 only. Compare-and-swap token the executor must observe at apply time (the \"before\" state). Signed as its own field. Omit only if the adapter has no prior state; do not send a placeholder."
        },
        "audience": {
          "type": "string",
          "description": "Requester identity for the decision envelope. Accepted here; the server-derived audience wins when both are present."
        },
        "policy_hash": {
          "type": "string",
          "description": "Authorize+grant v2 only. Policy identity bound into the grant, sha256: + 64 hex. When supplied, apply must use that same policy; a different policy is a different grant."
        }
      }
    },
    "response_detail": {
      "type": "string",
      "enum": [
        "control",
        "standard",
        "full"
      ],
      "description": "How much of the response to return. control = the fields an agent branches on; standard = control + the human report and labelled break rows (the MCP default); full = everything (the REST default). Every value is copied from the full response."
    },
    "idempotency_key": {
      "type": "string",
      "description": "Optional client key; in authorize mode, a repeat with the same key + body replays the original decision (24h). Analyze responses are not replayed."
    },
    "preflight_mode": {
      "type": "string",
      "enum": [
        "analyze",
        "authorize"
      ],
      "description": "REQUIRED. \"analyze\" = informational risk only (no decision/execution_action/safe_for_agent; analysis_outcome + may_execute:false). \"authorize\" = operation-bound path; may mint a receipt (requires context.operation). Decision Spec 2.0: omission is INVALID_INPUT. Do not pin 1.0 — that pin retired."
    },
    "decision_spec_version": {
      "type": "string",
      "enum": [
        "2.0"
      ],
      "description": "Optional. Omit or '2.0' = current contract. '1.0' retired (INVALID_INPUT); do not pin 1.0."
    },
    "derivation": {
      "type": "string",
      "enum": [
        "server"
      ],
      "description": "\"server\" = the server derives artifacts[] from GitHub Compare via the App installation. Allowed only when context.repository, context.base and context.head are all present and the tenant has a proven binding for that repository. Do not send artifacts[] in the same call (400 — one source of truth). Omit this field for the caller-supplied artifacts[] path."
    }
  },
  "required": [
    "preflight_mode"
  ],
  "if": {
    "properties": {
      "preflight_mode": {
        "const": "authorize"
      }
    },
    "required": [
      "preflight_mode"
    ]
  },
  "then": {
    "required": [
      "context"
    ],
    "properties": {
      "context": {
        "type": "object",
        "required": [
          "operation"
        ],
        "properties": {
          "operation": {
            "type": "string",
            "minLength": 1
          }
        }
      }
    }
  }
}

verify_receipt

Verify a CodeRifts signed chain-receipt you ALREADY HOLD: cryptographic authenticity (signature + key id), body binding, and — when lifecycle indices are available — whether it is currently valid authorization (not expired, superseded, or revoked) for a stated operation/target. Use this when: - You already obtained a chain_receipt / receipt token from a prior preflight (or CI artifact) and are about to act (merge/deploy) under that receipt. - A contract-gate or policy requires offline/online proof that the receipt is authentic for this change before proceeding. - You must distinguish "signature ok" from "currently authorized" (stale or superseded receipts must not be treated as live approval). Do not use when: - You do not have a receipt yet — call coderifts.preflight_change_set first. - You need a NEW decision for a changed base→head set — preflight again; verify_receipt does not re-diff specs. - The receipt you hold binds a different operation or target than the one you are about to perform — call coderifts.preflight_change_set with context.operation set to that operation (a merge receipt does not authorize a deploy); verify_receipt cannot re-scope or re-issue a decision. - You only need human-readable history of an old decision_id without a receipt token — use coderifts.get_decision_details. - The change set itself is unknown or incomplete — fix the change set and preflight; do not "verify" a placeholder. Inputs: receipt token (required); target_id = decision_result.artifact_digest — required for an authorization verdict; omitted → target_not_stated. Optional intended context (operation, environment, fingerprint, audience, repository/branch/pull_request, base/head) and the body_hash-bound decision_result envelope. 30s clock-skew leeway on expiry. A 0s grace for declared destructive production operations is defined in the policy but is unreachable today: the intended-context schema has no destructive field, so nothing can declare one and the 30s leeway always applies. Returns { valid, status, currently_authorized (bool|null), reason, payload, authz_* }. Branch on currently_authorized; null = not evaluated. When a decision envelope is also in hand (e.g. from a prior preflight), its control_envelope.next_agent_step (if present) is structured remediation guidance the agent MAY follow after a non-CONTINUE decision — still branch on execution_action; next_agent_step is suggestion, not permission.

Parameters12

token	string	required	The chain receipt token (base64url(body).base64url(signature))
operation	string	optional	Intended operation the receipt must authorize (conventional: merge\|deploy\|tool_call\|publish). Triggers authorization evaluation when non-empty; supply decision_result for full scope binding.
target_id	string	optional	REQUIRED to authorize under a held receipt. Set it to decision_result.artifact_digest — the digest of the artifact the receipt was issued for, which you already hold in the decision_result you are passing. The server does NOT derive it for you: it carries YOUR intended apply-site, and taking it from the envelope would compare that document against itself. Omit it and the answer is currently_authorized false with authz_reason target_not_stated and authz_status VERIFIED_TARGET_NOT_STATED — a missing input, distinct from target_mismatch, which means the receipt covers a different target.
environment	string	optional	Intended environment (e.g. production) — must match the receipt
fingerprint	string	optional	Intended change fingerprint — must equal the receipt fp
audience	string	optional	Intended audience — must match the receipt
repository	string	optional	Intended repository the receipt must bind (place binding; optional)
branch	string	optional	Intended branch the receipt must bind (place binding; optional)
pull_request	any	optional	Intended pull-request id the receipt must bind (place binding; optional)
base	string	optional	Intended base commit/ref SHA the receipt must match (signed-wins vs envelope.base)
head	string	optional	Intended head commit/ref SHA the receipt must match (signed-wins vs envelope.head)
decision_result	object	optional	The body_hash-bound decision envelope (carries operation/target/decision). Required for a meaningful AUTHORIZATION evaluation of scope; without it, intended context alone fails closed on authorization (currently_authorized false) while signature status remains independent. Full schema: https://coderifts.com/schemas/decision-result.v1.consumer.json.

Raw schema

{
  "type": "object",
  "properties": {
    "token": {
      "type": "string",
      "description": "The chain receipt token (base64url(body).base64url(signature))"
    },
    "operation": {
      "type": "string",
      "description": "Intended operation the receipt must authorize (conventional: merge|deploy|tool_call|publish). Triggers authorization evaluation when non-empty; supply decision_result for full scope binding."
    },
    "target_id": {
      "type": "string",
      "description": "REQUIRED to authorize under a held receipt. Set it to decision_result.artifact_digest — the digest of the artifact the receipt was issued for, which you already hold in the decision_result you are passing. The server does NOT derive it for you: it carries YOUR intended apply-site, and taking it from the envelope would compare that document against itself. Omit it and the answer is currently_authorized false with authz_reason target_not_stated and authz_status VERIFIED_TARGET_NOT_STATED — a missing input, distinct from target_mismatch, which means the receipt covers a different target."
    },
    "environment": {
      "type": "string",
      "description": "Intended environment (e.g. production) — must match the receipt"
    },
    "fingerprint": {
      "type": "string",
      "description": "Intended change fingerprint — must equal the receipt fp"
    },
    "audience": {
      "type": "string",
      "description": "Intended audience — must match the receipt"
    },
    "repository": {
      "type": "string",
      "description": "Intended repository the receipt must bind (place binding; optional)"
    },
    "branch": {
      "type": "string",
      "description": "Intended branch the receipt must bind (place binding; optional)"
    },
    "pull_request": {
      "description": "Intended pull-request id the receipt must bind (place binding; optional)",
      "oneOf": [
        {
          "type": "string"
        },
        {
          "type": "number"
        }
      ]
    },
    "base": {
      "type": "string",
      "description": "Intended base commit/ref SHA the receipt must match (signed-wins vs envelope.base)"
    },
    "head": {
      "type": "string",
      "description": "Intended head commit/ref SHA the receipt must match (signed-wins vs envelope.head)"
    },
    "decision_result": {
      "type": "object",
      "description": "The body_hash-bound decision envelope (carries operation/target/decision). Required for a meaningful AUTHORIZATION evaluation of scope; without it, intended context alone fails closed on authorization (currently_authorized false) while signature status remains independent. Full schema: https://coderifts.com/schemas/decision-result.v1.consumer.json.",
      "properties": {
        "spec_version": {
          "type": "string",
          "pattern": "^decision-result\\.v1(\\.[0-9]+)?$"
        },
        "decision": {
          "type": "string",
          "enum": [
            "ALLOW",
            "WARN",
            "REQUIRE_APPROVAL",
            "BLOCK"
          ]
        },
        "execution_action": {
          "type": "string",
          "enum": [
            "CONTINUE",
            "CONTINUE_WITH_MONITORING",
            "REQUEST_APPROVAL",
            "STOP"
          ]
        },
        "safe_for_agent": {
          "type": "boolean"
        },
        "decision_id": {
          "type": "string"
        },
        "fingerprint": {
          "type": "string"
        },
        "input_fingerprint": {
          "type": "string"
        },
        "decision_body_hash": {
          "type": [
            "string",
            "null"
          ]
        },
        "operation": {
          "type": [
            "string",
            "null"
          ]
        },
        "environment": {
          "type": [
            "string",
            "null"
          ]
        },
        "repository": {
          "type": [
            "string",
            "null"
          ]
        },
        "base": {
          "type": [
            "string",
            "null"
          ]
        },
        "head": {
          "type": [
            "string",
            "null"
          ]
        },
        "audience": {
          "type": [
            "string",
            "null"
          ]
        },
        "authority": {
          "type": [
            "object",
            "null"
          ],
          "description": "Additive. { audience, tenant_scope: bound|unbound, binding_proven_at? }. Informational — not permission, not a verify-receipt gate, not an ACL."
        },
        "derivation": {
          "type": [
            "object",
            "null"
          ],
          "description": "Additive. Present only when derivation:\"server\" produced this envelope. { source, platform?, base_sha, head_sha }. Covered by body_hash; not fingerprint."
        },
        "receipt": {
          "type": "object"
        },
        "expires_at": {
          "type": "string"
        },
        "blast_radius": {
          "type": "object",
          "description": "Additive COUNTS (not a score). Not permission.",
          "properties": {
            "endpoints": {
              "type": "integer",
              "minimum": 0
            },
            "fields": {
              "type": "integer",
              "minimum": 0
            },
            "params": {
              "type": "integer",
              "minimum": 0
            },
            "consumers_declared": {
              "type": "integer",
              "minimum": 0
            },
            "consumers_observed": {
              "type": "integer",
              "minimum": 0
            },
            "graph_source": {
              "type": "string"
            }
          }
        }
      },
      "additionalProperties": true
    }
  },
  "required": [
    "token"
  ],
  "description": "Two evaluation modes (schema-documented; no mode discriminator field). SIGNATURE: supply token only — signature + expiry; currently_authorized is null. AUTHORIZATION: also supply intended context (operation, environment, fingerprint, target_id set to decision_result.artifact_digest, audience, repository/branch/pull_request, and/or base/head) AND the body_hash-bound decision_result envelope so currently_authorized / authz_status / authz_reason can be evaluated. Token alone is always accepted; omitting the envelope when context fields are present yields a signature verdict plus fail-closed authorization (currently_authorized false), not a schema reject."
}

get_decision_details

Retrieve a PAST CodeRifts decision by exactly one identifier (case_id | decision_id | fingerprint): full report, breaking changes, scores, and linked receipt metadata if stored. Use this when: - You have a decision_id (or fingerprint) from a previous preflight, PR comment, or CI log and need to inspect or explain that past decision. - You are auditing why a prior ALLOW/WARN/BLOCK was issued. - You are NOT requesting a new analysis of current before/after specs. Do not use when: - You need a decision for the CURRENT uncommitted or PR head change set — call coderifts.preflight_change_set with the current artifacts. - You hold a receipt token and only need cryptographic/lifecycle verification — use coderifts.verify_receipt. - You have no identifier — run preflight first to create one. Inputs: exactly one of case_id, decision_id, or fingerprint. {} → INVALID_INPUT; two identifiers → LOOKUP_IDENTIFIER_CONFLICT; case_id → CASE_NOT_FOUND (lookup never opens a case). Returns the stored document or not_found. Scoping — fingerprint lookup returns only YOUR OWN decisions. A fingerprint is derived from content, not from an account, so two callers who preflight byte-identical specs derive the same one; the lookup is therefore constrained to the decisions your credential can prove it owns. A decision that exists but is not yours returns the SAME not_found as one that was never issued. This is deliberate: a distinguishable "exists but forbidden" would confirm to any caller that a given content hash had been decided on by someone, which is the fact the scoping exists to withhold. Do not read not_found as proof that no such decision exists anywhere. Decisions persisted without context.repository cannot currently be attributed to an account, and are not retrievable by fingerprint at all — not by their owner either. Retrieve those by decision_id, which is unchanged and unscoped. This is a limitation of what older stored rows carry, not a property of the lookup: rows written from now on record the account directly, so the gap narrows as older rows age out. If a fingerprint you expect returns not_found, use the decision_id before concluding the decision is missing. When the stored envelope carries control fields, control_envelope.next_agent_step is structured remediation guidance the agent MAY follow for non-CONTINUE execution_action values (null on CONTINUE*). Still branch on execution_action; next_agent_step is a suggestion, not permission.

Parameters3

case_id	string	optional	A case identifier. Lookup never opens a case. Until the case store exists this returns CASE_NOT_FOUND.
decision_id	string	optional	The decision_id from a prior decision_result envelope. Provide exactly one identifier.
fingerprint	string	optional	A verdict fingerprint (sha256:...); returns the latest matching decision you own. Provide exactly one identifier.

Raw schema

{
  "type": "object",
  "properties": {
    "case_id": {
      "type": "string",
      "minLength": 1,
      "description": "A case identifier. Lookup never opens a case. Until the case store exists this returns CASE_NOT_FOUND."
    },
    "decision_id": {
      "type": "string",
      "minLength": 1,
      "description": "The decision_id from a prior decision_result envelope. Provide exactly one identifier."
    },
    "fingerprint": {
      "type": "string",
      "minLength": 1,
      "description": "A verdict fingerprint (sha256:...); returns the latest matching decision you own. Provide exactly one identifier."
    }
  },
  "description": "Closed exclusive identifier union: exactly one of case_id | decision_id | fingerprint. Encoded as minProperties=1 + maxProperties=1 + additionalProperties=false, NOT as a top-level oneOf/anyOf/allOf — Anthropic (and other strict tool APIs) reject those combinators at the root of input_schema and then refuse the entire tools array (measured: test/mcp-input-oneof-honesty.test.js, mcp-streamable.js comment). The server enforces the same mutex with named codes: empty {} → INVALID_INPUT; two or more identifiers → LOOKUP_IDENTIFIER_CONFLICT; case_id alone → CASE_NOT_FOUND (no case store yet; lookup never opens a case).",
  "minProperties": 1,
  "maxProperties": 1,
  "additionalProperties": false
}

README.md19 KBView on GitHub

CodeRifts — contract-change authorization

Only a granted change can proceed. Before a contract change merges, deploys or registers, CodeRifts decides whether it is authorized — and the check is red without a grant.

One grant binds three things: the authorization, its single use, and the target state the change moves to. The decision is signed, and the receipt verifies offline — you do not have to trust our database to check what was authorized.

Every decision also names what it does not prove.

Hosted MCP server: https://app.coderifts.com/mcp
Manifest: https://coderifts.com/mcp.json — the canonical published document. The mcp.json at the root of this repository is a pointer to it, not a second copy.
Official MCP Registry: io.github.coderifts/api-governance
Website: https://coderifts.com
Live demo PR: https://github.com/coderifts/demo/pull/4

Install

text

# Claude Code
/plugin marketplace add coderifts/api-governance
/plugin install api-governance@coderifts

# Any MCP client (Streamable HTTP) — add to its MCP config
{ "mcpServers": { "coderifts": { "url": "https://app.coderifts.com/mcp",
  "headers": { "Authorization": "Bearer <YOUR_CODERIFTS_API_KEY>" } } } }

# SDKs
npm install @coderifts/sdk
pip install coderifts-sdk

GitHub Copilot reads the same server under three different root keys — servers in .vscode/mcp.json, mcpServers in the cloud agent's MCP settings, and mcp-servers in a custom agent's frontmatter — and npx coderifts copilot-setup writes all three (details below).

A key is needed only to authorize; get one at https://app.coderifts.com/api/signup.

Claude Code plugin

Install the CodeRifts marketplace, then the api-governance plugin (MCP server + skill). Requires CODERIFTS_API_KEY for tool calls.

text

/plugin marketplace add coderifts/api-governance
/plugin install api-governance@coderifts

Local checkout (after clone):

text

/plugin marketplace add .
/plugin install api-governance@coderifts

The plugin wires the hosted MCP at https://app.coderifts.com/mcp and the api-governance skill. Tools exposed: preflight_change_set, verify_receipt, get_decision_details only.

Cursor plugin

Cursor Plugin package (measured Cursor layout: .cursor-plugin/plugin.json + skills/ + rules/ + mcp.json + hooks/hooks.json). Same hosted MCP and the same three tools as the Claude plugin — no fourth tool. Deterministic / signed / fail-closed — not an AI compatibility scan.

Path	Role	Source of truth
`plugins/api-governance-cursor/.cursor-plugin/plugin.json`	Cursor Plugin manifest	cursor/plugins `plugin.schema.json`
`plugins/api-governance-cursor/skills/coderifts/SKILL.md`	Skill (`name: coderifts`)	Generated — coderifts-app `scripts/generate-skill-carriers.js`; the website `.well-known/agent-skills/coderifts/SKILL.md` is vendored from it
`plugins/api-governance-cursor/rules/coderifts.mdc`	Cursor rule	Generated — `generate-agent-host-files.js`
`plugins/api-governance-cursor/mcp.json`	Streamable HTTP MCP wiring	Same endpoint as Claude `.mcp.json` (not the website tool-card)
`plugins/api-governance-cursor/hooks/hooks.json`	preToolUse adapter, `failClosed: true`	CLI `coderifts cursor-hook` on `Write\|Delete` — same shape as the app's generated `.cursor/hooks.json`
`.cursor-plugin/marketplace.json`	Cursor marketplace entry	Cursor `marketplace.schema.json`

Validate:

bash

npm run validate:cursor

The generated-rule check is LIVE when CODERIFTS_APP_ROOT (default ~/coderifts-app) has generated/agent-host/.cursor/rules/coderifts.mdc, and RECORDED against fixtures/recorded/app-generator when it does not (weaker, named). A missing or corrupt snapshot still exits 1 — no silent skip.

OpenAI / Codex package

Codex plugin package (measured OpenAI Codex layout: .codex-plugin/plugin.json + .mcp.json + skills/ + AGENTS.md). Same hosted MCP and the same three tools as the Claude plugin — no fourth tool.

Path	Role	Source of truth
`plugins/api-governance-openai/.codex-plugin/plugin.json`	Codex plugin manifest	Codex `plugin-json-spec` (scaffold skill)
`plugins/api-governance-openai/.mcp.json`	Streamable HTTP MCP wiring	Same endpoint as Claude `.mcp.json`
`plugins/api-governance-openai/skills/api-governance/SKILL.md`	Skill + tool list	Trigger wording from agent-setup rule; tool names/descriptions from generated `mcp.json`
`plugins/api-governance-openai/AGENTS.md`	Agent rules file	Generated — `coderifts agent-setup` / `generate-agent-host-files.js`
`plugins/api-governance-openai/openai-agent-instructions.md`	OpenAI Agents SDK instructions	Generated — same generator
`plugins/api-governance-openai/docs/openai-production-pattern.md`	Production pattern (ID108) — host dispatch loop with `executeOpenAIToolCall`	Hand-authored recipe on shipped `@coderifts/agent-guard` ≥ 6.4.0 (first npm release that exports `executeOpenAIToolCall`; current npm 17.3.3)
`plugins/api-governance-openai/scripts/smoke-execute-openai-tool-call.mjs`	Offline smoke (ALLOW + BLOCK; no OpenAI key)	Real dispatcher + stub client
`.agents/plugins/marketplace.json`	Codex marketplace entry	Codex marketplace schema

Production pattern (function-calling apps)

OpenAI’s model only emits tool_call JSON; your app executes it. Wire governance at that host loop — not as a Claude-style PreToolUse hook. Full steps + one canonical loop:

→ plugins/api-governance-openai/docs/openai-production-pattern.md

bash

# Offline smoke (needs ~/coderifts-agent-guard built, or CODERIFTS_AGENT_GUARD_ROOT)
npm run smoke:openai-dispatch

⚠ Still failing on the same one assertion, re-measured 2026-09-24: ALLOW factory ran — execute() did not run. The other eight assertions pass (4 ALLOW, 5 BLOCK), and the BLOCK side — the side that matters for a gate — is fully green: the factory does not run, the content is the gate denial with no fabricated success, and the decision identity is surfaced. The failing assertion is on the ALLOW path, where the dispatch wrapper returns the function result without having invoked the injected factory.

The 2026-09-14 version of this note ended "Investigation is in progress." That was dropped rather than re-dated: ten days on, it is a claim about activity that nothing here can verify, and a README that reports its own diligence is reporting the one thing a reader cannot check. What a reader can check is the assertion name and today's date.

Local checkout in Codex (team marketplace path):

text

# From a clone of this repo, point Codex at .agents/plugins/marketplace.json
# then install api-governance-openai (UI / plugin install — see Codex plugin docs).

Validate package consistency (manifest, tool parity, AGENTS.md empty-diff vs regeneration):

bash

npm run validate:openai
# or: node scripts/validate-openai-package.js

AGENTS.md regeneration is LIVE when ~/coderifts-app (or CODERIFTS_APP_ROOT) exists, and RECORDED against fixtures/recorded/app-generator when it does not (weaker, named). A missing or corrupt snapshot still exits 1. Directory listing / account submission steps are not automated here.

GitHub Copilot kit

Reference copies of the generated Copilot MCP configs + instructions (single source: coderifts-app generators). Same hosted MCP and the same three tools — no fourth tool.

Primary install (living command — prefer this over copying from the kit):

bash

npx coderifts copilot-setup
# optional: --out <dir>   --check (drift-gate)   --force

Agent-host instructions (including .github/copilot-instructions.md) come from:

bash

npx coderifts agent-setup

Three Copilot surfaces (root keys differ)

From the generated guide (copilot/docs/copilot-mcp.md — do not re-author this table):

Surface	Config location	Root key	Auth
VS Code / Copilot Chat	`.vscode/mcp.json`	`servers`	`${input:coderifts_api_key}` + `inputs[]`
Copilot cloud agent + code review	Repo Settings → Copilot → MCP servers (paste JSON)	`mcpServers`	Agents secret `COPILOT_MCP_CODERIFTS_API_KEY` in `headers`
Custom agent (org/enterprise)	Agent profile `.md` YAML frontmatter	`mcp-servers`	`${{ secrets.COPILOT_MCP_CODERIFTS_API_KEY }}`

Tools allowlisted everywhere: preflight_change_set, verify_receipt, get_decision_details.

Vendored reference tree (`copilot/`)

Path	Role	Source of truth
`copilot/.vscode/mcp.json`	VS Code / Copilot Chat	Generated — `generate-copilot-mcp.js`
`copilot/copilot-cloud-agent-mcp.json`	Cloud agent paste JSON (`mcpServers`)	Generated — same
`copilot/copilot-custom-agent-mcp.frontmatter.md`	Custom agent YAML frontmatter	Generated — same
`copilot/docs/copilot-mcp.md`	Install guide + surfaces table	Generated — same
`copilot/.github/copilot-instructions.md`	Copilot coding-agent instructions	Generated — `generate-agent-host-files.js`
`copilot/SOURCE.md`	Provenance + re-sync commands	Packaging note (this repo)

Validate empty-diff vs regeneration + 3-tool discipline:

bash

node scripts/validate-copilot-kit.js

Empty-diff vs regeneration is LIVE when CODERIFTS_APP_ROOT has the generators, and RECORDED against fixtures/recorded/app-generator when it does not (weaker, named). A missing or corrupt snapshot still exits 1. The kit is a communication / distribution mirror — npx coderifts copilot-setup remains the install path.

Agent Skill (skills.sh)

bash

npx skills add coderifts/api-governance

The skills CLI discovers skills/api-governance/SKILL.md at this repository's root and installs it under the name api-governance. Where it lands depends on the agent (the CLI's own table): .agents/skills/api-governance/ for most agents (Codex, Cursor, Gemini CLI, GitHub Copilot, OpenCode, …) and .claude/skills/api-governance/ for Claude Code.

One skill, one name (2026-09-29). The three SKILL.md carriers — Claude (plugins/api-governance/skills/api-governance/), Cursor (plugins/api-governance-cursor/skills/coderifts/) and Codex/OpenAI (plugins/api-governance-openai/skills/api-governance/) — carry the same body byte for byte and the same name: coderifts, the name skills.sh lists (npx skills add coderifts/api-governance installs ./.agents/skills/coderifts/, measured 2026-09-29). Only the frontmatter description is per host. All three are generated by coderifts-app scripts/generate-skill-carriers.js from agent/skills/coderifts/SKILL.md; test/one-skill.test.js holds them together. The website's .well-known/agent-skills/coderifts/SKILL.md is the Cursor carrier, vendored.

MCP server

CodeRifts runs as a hosted Streamable HTTP MCP server. Any MCP-compatible agent (Claude Desktop, Cursor, LangGraph, AutoGen, custom) can connect and run governance checks before tool calls or merges.

Endpoint: https://app.coderifts.com/mcp
Transport: Streamable HTTP (protocol version 2025-06-18)
Server: CodeRifts API Governance v1.0.3 — read from initialize → result.serverInfo.version on 2026-09-24. A version typed into a README is a claim with a date on it; npm run validate:tools-wire compares the TOOLS to the live server on every push, pull request and daily cron, but nothing compares this line, so re-read it rather than trust it.
Auth: initialize, tools/list and an analyze tools/call need no key (measured live 2026-09-26). An authorize call mints a signed receipt and needs an API key — send Authorization: Bearer <key> or X-API-Key: <key>.

Connect

json

{
  "mcpServers": {
    "coderifts": {
      "url": "https://app.coderifts.com/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_CODERIFTS_API_KEY>"
      }
    }
  }
}

Verify the connection

bash

curl -sS https://app.coderifts.com/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'

Expected: a JSON-RPC result with serverInfo and capabilities.tools.

Try without a key

An analyze call over MCP needs no key:

bash

curl -sS https://app.coderifts.com/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"preflight_change_set","arguments":{"preflight_mode":"analyze","artifacts":[{"id":"api","type":"openapi","before":"openapi: 3.0.0\ninfo: {title: Pets, version: 1.0.0}\npaths:\n  /pets:\n    get:\n      responses:\n        \"200\":\n          description: ok\n          content:\n            application/json:\n              schema:\n                type: object\n                properties:\n                  id: {type: string}\n                  name: {type: string}\n","after":"openapi: 3.0.0\ninfo: {title: Pets, version: 1.0.0}\npaths:\n  /pets:\n    get:\n      responses:\n        \"200\":\n          description: ok\n          content:\n            application/json:\n              schema:\n                type: object\n                properties:\n                  id: {type: string}\n"}]}}}'

Measured response (live, 2026-09-26 — removing name from GET /pets), in the tool result:

json

{ "preflight_mode": "analyze", "analysis_outcome": "BREAKS_DETECTED",
  "authorization_effect": "NONE", "may_execute": false, "receipt_kind": "NONE",
  "breaking_changes": 1, "risk_score": 14 }

That is information, not permission: may_execute is false on every analyze answer. To act, call again with preflight_mode: "authorize" and context.operation, with a key.

Two public REST endpoints need no auth at all:

bash

curl -s "https://app.coderifts.com/api/v1/public/preflight?url=https://petstore3.swagger.io/api/v3/openapi.json"

curl -s -X POST https://app.coderifts.com/api/v1/public/actionguard-check \
  -H "Content-Type: application/json" \
  -d '{"filename":".github/workflows/ci.yml","base_content":null,"head_content":"jobs:\n  b:\n    steps:\n      - uses: some-owner/some-action@main"}'

Both return HTTP 200 without a key. They do not share a response shape:

GET /api/v1/public/preflight is analyze-only. There is no decision field. The body carries analysis_outcome (Petstore URL: NO_BREAK_DETECTED), authorization_effect: NONE, and may_execute: false.
POST /api/v1/public/actionguard-check does return a decision field (unpinned uses: @main payload: WARN) plus execution_action: CONTINUE_WITH_MONITORING.

Tools

The hosted MCP server exposes exactly three tools (from live tools/list; pinned in this repository as tools.wire.v1.json, which npm run validate:tools-wire checks against the live server on every push, pull request and the daily cron):

Tool	What it does
`preflight_change_set`	Preflight a complete base→head change set of contract artifacts. Returns risk score and breaking-change analysis. With `preflight_mode: "authorize"` (and `context.operation`), returns a governance decision (ALLOW / WARN / REQUIRE_APPROVAL / BLOCK) and may mint a signed chain-receipt. With `preflight_mode: "analyze"`, returns informational risk only (`may_execute: false`, no decision, no receipt). Requires `artifacts` + `preflight_mode`.
`verify_receipt`	Verify a signed chain-receipt you already hold: signature authenticity, body binding, and (when lifecycle indices are available) whether it is currently authorized for a stated operation/target. Requires `token`. Does not re-diff specs.
`get_decision_details`	Retrieve a past decision by `decision_id` (preferred) or `fingerprint`: stored report, breaking changes, scores, and linked receipt metadata if present. Not for a new analysis of the current change set.

On the authorize path of preflight_change_set, the decision envelope includes fields such as decision, execution_action, risk_score, safe_for_agent, and related analysis fields so agent runtimes can branch on a stable contract. Prefer branching on execution_action when present.

How agents use it

Before merging an API change (or before an agent acts on a contract change), call preflight_change_set with full before/after artifacts and preflight_mode: "authorize" (plus context.operation).
Branch on execution_action only: CONTINUE proceeds, CONTINUE_WITH_MONITORING proceeds with a wired monitoring sink, REQUEST_APPROVAL pauses for a human, STOP stops the merge / aborts the agent step. Any other value is not permission — fail closed.
Before acting under the receipt you hold, call verify_receipt with the same context the preflight was made under, and act only when currently_authorized is true. Do not re-preflight unless the change set or operation changed.
To inspect a prior decision by id, call get_decision_details.

Decision logic is deterministic: a single breaking change is never silently allowed. Tests can pass and still ship a broken contract — CodeRifts checks the contract itself at PR time.

Also available

GitHub App on the GitHub Marketplace — installs without configuration and posts a signed contract-change decision (ALLOW / WARN / REQUIRE_APPROVAL / BLOCK) on every pull request, across four gates: API contract, schema-vs-code, auth surface and workflow actions. ⚠ It reports by default: the check's phase-1 conclusion is clamped to neutral and MERGEGATE_ENFORCE defaults false, so it prevents a merge only once the check is required on the branch and that variable is on. The platform truth table is the source of truth for that distinction: https://coderifts.com/docs/platform-truth-table/
SDKs: npm install @coderifts/sdk (TypeScript), pip install coderifts-sdk (Python).
CLI: coderifts (npm) with a pre-push hook.
Integrations: Backstage plugin, VS Code extension, LangGraph / AutoGen / CrewAI.

License

See LICENSE.

Install

Tools (3)

preflight_change_setverify_receiptget_decision_details

Remote endpoint

Streamable HTTP

Hosted server - connect over the network, no local install.

url

https://app.coderifts.com/mcp

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "api-governance": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://app.coderifts.com/mcp"
      ]
    }
  }
}

Desktop config is stdio-only; this bridges via mcp-remote. Native remote: Settings > Connectors.

io.github.coderifts/api-governance

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

Topics

preflight_change_set

verify_receipt

get_decision_details

CodeRifts — contract-change authorization

Install

Claude Code plugin

Cursor plugin

OpenAI / Codex package

Production pattern (function-calling apps)

GitHub Copilot kit

Three Copilot surfaces (root keys differ)

Vendored reference tree (`copilot/`)

Agent Skill (skills.sh)

MCP server

Connect

Verify the connection

Try without a key

Tools

How agents use it

Also available

Links

License

Install

Remote endpoint

Related servers

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

Topics

preflight_change_set

verify_receipt

get_decision_details

CodeRifts — contract-change authorization

Install

Claude Code plugin

Cursor plugin

OpenAI / Codex package

Production pattern (function-calling apps)

GitHub Copilot kit

Three Copilot surfaces (root keys differ)

Vendored reference tree (copilot/)

Agent Skill (skills.sh)

MCP server

Connect

Verify the connection

Try without a key

Tools

How agents use it

Also available

Links

License

Install

Remote endpoint

Related servers

Vendored reference tree (`copilot/`)