Skip to main content
Glama
SureshKhemka

constraints-registry-mcp

by SureshKhemka
OverviewSchemaRelated ServersScoreDiscussions
Python
Hybrid

Constraint Registry

License: Apache 2.0 Python CI PRs Welcome

Policy-as-code guardrails for AI-generated code. An MCP server that serves engineering constraints to coding agents (Claude Code, Cursor, Codex) at generation time and validates artifacts with OPA, Conftest, Checkov, and Semgrep.

A single, queryable source of engineering constraints (infrastructure, organizational, architectural) that coding agents (Claude Code, Cursor, Codex, …) consult at code-generation time, exposed over an MCP server. It does not enforce constraints itself — it provides guidance to agents and delegates deterministic validation to existing enforcement engines (OPA, Conftest, Checkov, Semgrep).

Constraints are authored in source repos, aggregated into an immutable, versioned bundle, and served over MCP so an agent can:

  1. describe_scope — discover the valid selector vocabulary,

  2. get_constraints — fetch the rules relevant to what it's building, and

  3. validate — check a candidate artifact against the bound enforcement engines.

Authoritative requirements: constraint-registry-v0-spec.md. Requirement → component → test mapping: TRACEABILITY.md.

Contents

Related MCP server: project-brain-mcp

Features

  • Three constraint categories — infrastructure, organizational, architectural, including relationship-style selectors (e.g. "no synchronous calls across domain boundaries") and advisory (no-enforcement) constraints.

  • Multi-source aggregation — import from many source repos; ids are namespaced per source; deterministic, content-hashed, immutable versioned bundles.

  • Precedence & anti-drift — a configurable default policy (hard outranks weaker; a downstream source may not relax a higher-precedence rule on the same scope); fixture cross-checks keep guidance and enforcement from drifting.

  • Pluggable engines — a stable adapter interface with four real adapters: OPA and Conftest (Rego policies), Checkov (IaC scanning), and Semgrep (application source code). SARIF-emitting engines share one normalization seam (adapters/sarif/), so adding a new SARIF engine is mostly wiring. Adding an engine = one adapter + one config line (see Adding an enforcement engine).

  • Catalog importers — Checkov and Semgrep ship importers that turn an engine's rule catalog/ruleset into draft constraint stubs (with license/source provenance) for a human to enrich — a fast path to bootstrapping a source.

  • MCP server — three tools (describe_scope, get_constraints, validate) over stdio or a shared HTTP endpoint. get_constraints fails open so an agent is never blocked.

  • Hot reload — the server can periodically re-import so constraint changes are picked up without a restart.

  • Validation harness — proves the registry and constraint set are internally consistent; machine-readable JSON, non-zero exit on failure.

Prerequisites

Tool

Required?

Notes

Python ≥ 3.11

yes

the package targets 3.11+

uv

yes

manages the venv and runs entry points

OPA (opa)

for Rego validate / fixture cross-checks

the reference enforcement engine

Conftest (conftest)

optional

second Rego engine; its checks SKIP if absent

Checkov (checkov)

optional

IaC scanning engine; its checks SKIP if absent

Semgrep (semgrep)

bundled

source-code engine; installed automatically by uv sync

Install the external engines on macOS:

brew install opa conftest checkov   # semgrep is installed by `uv sync`

Each engine is optional and independent: any test or harness check whose engine binary is not on PATH is skipped, not failed. The registry and the get_constraints/describe_scope guidance work without any engine at all — an engine is only needed to run validate and the fixture cross-checks for constraints bound to it.

Quick start

git clone https://github.com/SureshKhemka/constraints-registry.git
cd constraints-registry

uv sync                      # create the venv + install deps (incl. semgrep)

uv run cregistry-harness     # run the validation harness against the bundled samples

The harness emits machine-readable JSON and exits non-zero on any failure. A green run looks like:

{ "passed": true, "summary": { "pass": 21, "fail": 0, "skip": 0, "total": 21 }, "checks": [ ... ] }

(skip is used only when an optional engine like conftest is not installed.)

Running the MCP server

Two transports — pick based on how you want tools to connect.

# stdio (default): each tool launches its own copy; nothing to manage
uv run cregistry-mcp

# one shared HTTP server every tool connects to (recommended for multiple tools)
uv run cregistry-mcp --http --port 8765 --reload-interval 60

Flags: --transport {stdio,http,sse}, --http (shorthand), --host (default 127.0.0.1), --port (default 8765), --config (or $CREGISTRY_CONFIG), --reload-interval SECONDS (0 = off).

Manage the shared HTTP server:

lsof -ti tcp:8765 | xargs kill     # stop
# restart = stop + start

Full operational guide (stop/restart, macOS launchd auto-start, the repo-sync/decoupling pattern): docs/RUNNING.md. Tool input/output contracts: docs/MCP_CONTRACT.md.

Integrating with coding agents

The server exposes three tools: describe_scope, get_constraints, validate.

Claude Code

# shared HTTP server (start it first, see above), available in every project:
claude mcp add --scope user --transport http constraint-registry http://127.0.0.1:8765/mcp

# OR stdio (no separate server to run; Claude launches it):
claude mcp add constraint-registry -- uv run --directory "$(pwd)" cregistry-mcp

claude mcp list   # should show: constraint-registry ... ✔ Connected

Cursor (~/.cursor/mcp.json)

{ "mcpServers": { "constraint-registry": { "url": "http://127.0.0.1:8765/mcp" } } }

Codex / other stdio-only tools

Configure an MCP server with command: uv, args: ["run","--directory","/abs/path/to/repo","cregistry-mcp"].

Make the agent actually consult it

Agents auto-discover the tools, but to get them to consult the registry before generating code, add an instruction to your project (or ~/.claude/CLAUDE.md):

Before writing AWS/infra code, call the constraint-registry MCP: describe_scope to learn valid selector values, then get_constraints with the right scope, and comply with every hard constraint as a non-negotiable downstream gate. Optionally validate the result.

Authoring constraints

A source is a directory with constraints/*.yaml (one constraint per file) and, optionally, policies/ (engine policies) and fixtures/ (sample artifacts). Register sources and engines in registry.config.yaml:

sources:
  - { name: platform-security, path: sources/platform-security, precedence: 100 }
  - { name: data-platform,     path: sources/data-platform,     precedence: 50  }
engines:
  - { name: opa,      adapter: "cregistry.engine.adapters.opa:OpaAdapter" }
  - { name: conftest, adapter: "cregistry.engine.adapters.conftest:ConftestAdapter" }
  - { name: checkov,  adapter: "cregistry.engine.adapters.checkov:CheckovAdapter", options: { min_level: warning } }
  - { name: semgrep,  adapter: "cregistry.engine.adapters.semgrep:SemgrepAdapter", options: { min_level: warning } }
precedence_policy: default

A constraint (see sources/platform-security/constraints/aws-s3-no-public-access.yaml):

id: aws.s3.no-public-access
title: "S3 buckets must not be publicly accessible"
intent: "Public buckets are the top source of data-exposure incidents."
category: infrastructure          # infrastructure | organizational | architectural
scope:
  providers: [aws]
  resource_types: [aws_s3_bucket] # Terraform resource ids (NOT "s3_bucket")
  environments: [all]
  repos: ["tag:data-plane"]
severity: hard                    # hard | soft | advisory
enforcement:                      # omit for an advisory (guidance-only) constraint
  - { engine: opa, policy: policies/s3_public.rego }
guidance:
  do:   ["Attach an aws_s3_bucket_public_access_block with all four flags true"]
  dont: ["Never set acl = 'public-read' or 'public-read-write'"]
  example_compliant: |
    {"resources": {"aws_s3_bucket": {"data": {"acl": "private", "public_access_block": true}}}}
owner: platform-security
version: 1.0.0
fixtures:                         # optional; cross-checked against the engine
  pass: fixtures/s3_private.json
  fail: fixtures/s3_public.json

Scoping notes (matters when agents query):

  • resource_types use the target tooling's identifiers (Terraform: aws_s3_bucket). Call describe_scope to discover the exact vocabulary present.

  • A query that omits a dimension matches broadly; a value that contradicts a constraint's selector excludes it. Relationship-scoped constraints are only returned for queries that supply a matching relationship.

  • After authoring, run uv run cregistry-harness to validate schema, precedence, and fixtures.

Hot reload (no restart on constraint changes)

Run the server with --reload-interval N and it re-imports from disk every N seconds, publishing a new immutable bundle when content changes:

uv run cregistry-mcp --http --port 8765 --reload-interval 60

  • No-op when nothing changed; previous bundle versions stay pinnable by id.

  • A failed re-import (e.g. an unresolvable precedence conflict) keeps the last-good bundle serving and logs the reason — the server never goes dark.

  • The server reads from the configured source paths, so wire your teams' constraint repos to sync/pull into those paths (a separate ops job, e.g. a cron git pull or CI publish). Code/dependency changes still need a restart.

Validation harness

uv run cregistry-harness runs end-to-end against the bundled, self-contained sample sources and proves: schema conformance, deterministic import, malformed- constraint isolation, namespacing & precedence, versioning & deprecation, engine- interface conformance (incl. a reusable suite any adapter can be run against), fixture cross-checks / broken-binding detection, the MCP contract / scoping / fail-open, and hot-reload behavior. It prints structured JSON and returns a non-zero exit on any failure — suitable for CI.

uv run cregistry-harness            # human-readable JSON to stdout, exit 0/1
uv run cregistry-harness --config path/to/registry.config.yaml

Adding an enforcement engine

Implement the EngineAdapter interface in a new module under src/cregistry/engine/adapters/, add one line under engines: in registry.config.yaml, and validate it against the existing conformance suite — no changes to the schema, importer, MCP server, or harness. Full walkthrough: docs/ADDING_AN_ENGINE.md.

Repository layout

src/cregistry/
  model.py            constraint schema (Pydantic)
  loader.py           load + per-field schema validation
  config.py           registry config (sources, engines)
  importer.py         import → aggregate → bundle
  precedence.py       namespacing precedence / conflict resolution
  scope.py            scope matching (query + conflict)
  bundle.py store.py  immutable versioned bundles + store
  query.py validate.py  scoped queries + artifact validation
  integrity.py        fixture cross-check / anti-drift
  service.py          transport-independent service (+ hot reload)
  mcp_server.py       MCP server (stdio / http) + CLI
  engine/             stable engine interface, registry, and adapters:
    adapters/opa, adapters/conftest, adapters/checkov, adapters/semgrep
    adapters/sarif    shared SARIF normalization seam (used by checkov + semgrep)
  harness/            the validation harness (checks/*)
sources/              bundled sample source repos (constraints, policies, fixtures)
scenarios/            self-contained fixtures for harness edge cases
tests/                pytest suite: adapter conformance, fixtures, import, e2e
docs/                 RUNNING.md, MCP_CONTRACT.md, ADDING_AN_ENGINE.md
deploy/               launchd template for auto-starting the HTTP server
CONTRACTS.md          the frozen engine-adapter seam new adapters code against

Run the adapter test suite directly with uv run pytest.

Contributing

Contributions are very welcome — bug reports, new engine adapters, constraint sources, and docs. Adding an engine is intentionally small: one adapter module plus one config line, with no changes to the schema, importer, MCP server, or harness.

Before opening a PR, make sure uv run pytest and uv run cregistry-harness are green; CI runs both on every pull request.

License

Licensed under the Apache License 2.0. See NOTICE for attribution and the licenses of the external engines this project integrates with.

Available Tools

3 tools
describe_scopeA

Discover the selector vocabulary present in the registry so you can build a correct scope instead of guessing. Output lists the distinct providers, resource_types (Terraform resource identifiers, e.g. 'aws_s3_bucket' not 's3_bucket'), environments, repos (tags like 'tag:data-plane'), categories, severities, sources, and relationship layers/interactions. Call this first if unsure of valid scope values.

ParametersJSON Schema
NameRequiredDescriptionDefault
versionNo

TDQS

A4.1/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description indicates the tool is read-only (discovers, lists) and outputs a set of vocabulary items, which implies no side effects. Given no annotations, this is reasonably transparent. Missing details like permissions or rate limits, but the core behavior is clear.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences with no filler. The first sentence immediately states the purpose and benefit, and the second lists outputs and usage guidance. Every sentence is valuable and front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the tool's purpose, outputs in detail, and usage guidance. The lack of output schema is compensated by listing output fields. Missing documentation of the version parameter slightly detracts from completeness for a simple tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description does not mention the sole parameter 'version' at all, even though schema coverage is 0%. For a single optional parameter, the description could have explained its purpose, but it does not, leaving the agent to infer from the schema alone.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses specific verbs 'discover' and 'lists' to state what the tool does, and it clearly enumerates the output fields (providers, resource_types, etc.). It distinguishes from siblings (get_constraints, validate) by positioning itself as a preliminary discovery step.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly advises to 'Call this first if unsure of valid scope values,' providing a clear usage context. However, it does not explicitly compare to get_constraints or validate or state when not to use it, leaving some room for improvement.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_constraintsA

Return engineering constraints relevant to a scope. Inputs: scope (providers, resource_types, environments, repos, relationship), optional version (bundle id; defaults to latest). resource_types use Terraform resource identifiers, e.g. 'aws_s3_bucket' (NOT 's3_bucket'); repos are tags like 'tag:data-plane'. If unsure of valid values, call describe_scope first, or simply omit a dimension (omitted dimensions are 'don't care' and broaden the match rather than excluding). Output: {available, bundle_id, constraints[]}. Fails open: on any error returns available=false with an empty constraints list so you can proceed.

ParametersJSON Schema
NameRequiredDescriptionDefault
scopeNo
versionNo

TDQS

A4.9/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It explains input specifics (Terraform identifiers, repos as tags), optional version with default, output format, and error behavior (fails open).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single paragraph with good front-loading, but could be slightly more structured (e.g., bullet points for input fields). Still concise and informative.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite no output schema, description states output format. Covers scope usage, defaults, error behavior, making it complete for agent decision-making.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, but description fully explains both parameters: scope (with details on its dimensions) and version (with default). Provides examples and rules for scope values.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool returns engineering constraints relevant to a scope, and distinguishes itself from siblings like describe_scope and validate by explaining its specific purpose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit guidance on when to call describe_scope first if unsure of valid values, and that omitting dimensions broadens match. Also explains error handling (fails open) so agent knows how to proceed.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

validateA

Validate a candidate artifact against in-scope constraints by delegating to enforcement engines. Inputs: artifact (object), scope, optional version. Output: {bundle_id, passed, results[]} where each result has constraint, severity, kind, verdict, violations, guidance.

ParametersJSON Schema
NameRequiredDescriptionDefault
scopeNo
versionNo
artifactYes

TDQS

A3.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description bears the full burden. It discloses the delegation to enforcement engines and the output structure including bundle_id, passed, and results with detailed sub-fields. This is good but could mention side effects or idempotency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise: two sentences for purpose and one for input/output. It is front-loaded with the core action and uses minimal words without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 3 parameters, 1 required, and no output schema, the description provides the output shape but lacks details on the results array structure (e.g., what constitutes a violation, severity meanings) and behavioral context (e.g., synchronous vs async, error handling). Adequate but with gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, and the description adds meaning by naming and describing each parameter: artifact (object), scope (optional), version (optional). However, it does not elaborate on sub-properties or expected formats, leaving some ambiguity.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Validate a candidate artifact against in-scope constraints by delegating to enforcement engines.' It uses a specific verb (validate) and resource (artifact), and distinguishes from siblings (describe_scope, get_constraints) which have different actions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description does not provide explicit guidance on when to use this tool versus alternatives, such as prerequisites or when not to use it. No context for decision-making between sibling tools is given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 3 tool updatesv0.0.0
    • First observeddescribe_scope
    • First observedget_constraints
    • First observedvalidate
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.2/5.0
Disambiguation5/5

Each tool has a clearly distinct purpose: describe_scope discovers valid scope values, get_constraints retrieves constraints, and validate checks artifacts. No overlap or ambiguity.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern: describe_scope, get_constraints, validate. The pattern is predictable and clear.

Tool Count5/5

Three tools are well-scoped for a constraints registry: discover vocabulary, retrieve constraints, and validate. Each tool earns its place without unnecessary bulk.

Completeness4/5

The set covers the core workflow (discover, fetch, validate). Minor gap: no explicit tool to list all constraint definitions without scope filtering, but the design intentionally omits scope-agnostic retrieval.

Maintenance

ActivityStale
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • project-brain-mcp

    AiraAlfredSF
    A
    license
    Not graded
    quality
    B
    maintenance
    An MCP server that provides CLI coding agents with persistent decision memory, codebase dependency-graph awareness, plan validation against architectural constraints, and a self-bootstrapping constraints.md file.
    18
    MIT
  • testigo-recall-mcp by testigo-recall

    testigo-recall-mcpofficial

    testigo-recall
    F
    license
    A
    quality
    C
    maintenance
    MCP server that exposes pre-extracted facts about code behavior, design decisions, and assumptions to AI agents, saving time and tokens by avoiding direct source file reading.
    6
    -

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/SureshKhemka/constraints-registry'

If you have feedback or need assistance with the MCP directory API, please join our Discord server