repo-contract
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
repo-contract — AI Agent Governance Layer
repo-contract is a lightweight, portable Python package and command-line tool that acts as an enforceable governance layer for AI coding agents (such as Claude Code, Cursor, Codex, Windsurf, Aider, etc.).
It allows repositories to declare machine-checkable architectural, safety, and workflow rules. The engine deterministically validates proposed agent plans (pre-edit) and git diff patches (post-edit) to ensure compliance before code is modified or merged.
Why Governance?
AI agents are excellent at generating edits, but often fail to respect repository-specific constraints:
Scope Creep: Editing unrelated components or refactoring large sub-systems.
Architectural Regressions: Importing internal database handlers directly into view controllers.
Workflow Breaches: Editing crucial functionality without adding corresponding tests.
Safety Violations: Reading/modifying forbidden files (
.env,secrets/) or sensitive directories.
Rather than trying to help agents "understand more code" or storing synthetic meaning, repo-contract focuses on enforcing negative constraints, which empirical studies show is the most effective way to shape safe agent workflows.
Related MCP server: safe-code-mcp
Key Features
YAML/TOML Contracts: Declarative policy schema containing architecture layers, safety paths, agent limits, and test mappings.
Python Module Inspector: AST-based import resolution (both absolute and relative package paths).
Plan Validation: Pre-checks an agent's text/markdown plan block, extracting planned files and verifying safety boundaries before edits begin.
Diff Validation: Analyzes git patches/diffs to catch forbidden imports, path violations, test gaps, and file counts.
Dependency Guard: Warns when a diff adds imports of external packages that are not declared in
pyproject.toml/requirements.txt/setup.py— a common AI-agent failure mode.Unrelated Refactor Detection: Identifies whether modifications span disjoint, unconnected modules in the import graph (connected components analysis).
Deterministic Engine: 100% deterministic rules with clear, human-readable explanations and JSON-RPC outputs.
MCP Server Integration: Stdio-based Model Context Protocol (MCP) server wrapper that exposes validators directly as tools for AI assistants.
Installation
pip install repo-contractRequires Python 3.11 or newer. This installs the repo-contract command along with the MCP server.
git clone https://github.com/dager23/RepoContract.git
cd RepoContract
pip install -e ".[dev]"
pytestQuick Start
1. Initialize the Contract
Create a default configuration file in your repository:
repo-contract init
# Generates repo-contract.yaml2. Configure Rules
Modify repo-contract.yaml (or TOML equivalent) to define your rules:
version: 1
project:
name: my-app
src_root: "my_app" # Directory containing python package modules
architecture:
layers:
- name: ui
paths: ["my_app/ui/**"]
# Entries may be layer names ("db"), dotted module prefixes ("my_app.db"),
# or path prefixes ("my_app/db") — all three are equivalent.
cannot_import: ["my_app/db"] # UI layer cannot import DB layer directly
- name: db
paths: ["my_app/db/**"]
cannot_import: ["my_app/ui"]
workflow:
required_tests:
# Require corresponding test file to be modified when source is modified
- when_paths_match: ["my_app/**/*.py"]
require: ["tests/**/test_*.py"]
safety:
forbidden_paths:
- ".env"
- "secrets/**"
approval_required_for:
- "my_app/auth/**"
agent:
max_files_per_change: 6
forbid_unrelated_refactors: true
dependencies:
# Warn when a diff adds imports of packages not declared in the
# project's dependency files (pyproject.toml / requirements.txt / setup.py)
check_undeclared: true3. Run Validation
Scan Codebase
Scan the entire repository for static layer boundary violations or missing tests:
repo-contract scanValidate Agent Plan (Pre-edit)
Pass the agent's proposed plan (as raw text or from a file) to ensure they aren't touching forbidden files or planning changes that are too broad:
repo-contract check-plan "I will edit my_app/auth/login.py and .env to configure authentication."
# Fails because .env is forbidden and auth/ requires approval.
# Or validate a plan saved to a file:
repo-contract check-plan plan.mdIf the argument is a path to an existing file it is read as a plan file; otherwise it is treated as raw plan text (use --text to force raw-text interpretation).
Validate Git Diff (Post-edit / CI Gate)
Check uncommitted working tree edits, a specific git commit range, or a patch file:
# Validate local uncommitted edits
repo-contract check-diff
# Validate staging changes
repo-contract check-diff --staged
# Validate range (e.g. CI run)
repo-contract check-diff HEAD~1..HEAD
# Validate a patch file
repo-contract check-diff my-change.patchModel Context Protocol (MCP) Integration
You can run repo-contract as a stdio-based MCP Server in your favorite editor (like Cursor, Claude Desktop, or Windsurf) by adding this command to your configuration:
{
"mcpServers": {
"repo-contract": {
"command": "python",
"args": ["-m", "repo_contract.mcp.server"],
"cwd": "/path/to/your/project"
}
}
}Exposed Tools
scan_repository: Runs structural checks on the current workspace.check_plan: Analyzes the agent's textual/markdown plan, extracting planned files and validating bounds before edits begin.check_diff: Checks current uncommitted working directory edits.
License
MIT © Yash Shah
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Zero-log MCP server with 49 tools for AI guardrails, secret scanning, MCP linting & EU compliance.
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
MCP server for secureFlows: token-free URL builders and integration-linting tools for AI agents.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAn MCP server that enforces runtime governance on AI agent actions — file access, command execution, delegation chains, and permission escalation.MIT
- FlicenseNot gradedqualityDmaintenanceA local MCP server that provides controlled repository access with policy-based file filtering, secret redaction, and audit logging for AI coding agents.-
- AlicenseNot gradedqualityDmaintenanceAn MCP server that provides a governance layer for coding agents, enforcing policies, validation, and human-in-the-loop for tool calls without requiring an API key.MIT
- AlicenseAqualityBmaintenanceMCP server that enables AI coding assistants to audit repositories against engineering rules, generating self-contained HTML reports with citations and optional GitHub issue filing.102Apache 2.0