MCP Contractor

AI agents shouldn't guess. They should read the contract.

MCP Contractor is a Model Context Protocol server that acts as a contract linter for AI. Instead of relying on ls, find, or scanning raw files, AI agents call MCP Contractor to understand a project through structured YAML contracts.

Each contract defines a feature's dependencies, exports, business rules, file structure, and types -- giving the AI everything it needs to work without breaking things.

---

Why

AI agents working on large codebases often:

• Break dependencies they didn't know existed
• Forget business rules buried in code comments
• Produce code that doesn't follow project conventions
• Lose context across feature boundaries

MCP Contractor solves this by making contracts the source of truth. The AI reads the contract before touching the code.

---

How It Works

   Developer                    AI Agent (Claude Code)
       |                              |
       |  writes contracts (.yaml)    |
       |----------------------------->|
       |                              |  calls MCP tools
       |                              |---------------->  MCP Contractor
       |                              |                      |
       |                              |  <-- XML response    |
       |                              |     (deps, rules,    |
       |                              |      exports, types) |
       |                              |                      |
       |       writes code that       |                      |
       |    <-- respects contracts    |                      |
       |                              |                      |
       |   opens dashboard (browser)  |                      |
       |----------------------------->|  http://localhost:8000

---

MCP Tools

9 tools available, organized by workflow:

Discovery

Tool	Description
search	Search contracts with filters (query, status, dependsOn, dependedBy, owner, hasRules, hasViolations)
get_feature	Get the full contract of a feature as optimized XML
get_dependencies	Get dependency graph (direct + transitive + circular detection)

Analysis

Tool	Description
compile	Compile all contracts, return XML diagnostic report
validate	Verify implementation code matches contract declarations
drift	Detect drift between the index and actual contract files
index	Generate or update the contracts YAML index

Mutation

Tool	Description
scaffold	Generate a YAML contract template for a new feature (configurable basePath)
update	Modify an existing contract (metadata, deps, rules, files)

Onboarding

Tool	Description
reference	Get contract-driven development guide. Sections: workflow, tools, rules, claude-md

All responses are token-optimized XML -- compact, action-oriented, no redundancy.

Example Workflows

AI exploring a new codebase:

search({ status: "active" })           -> overview of active features
get_feature({ feature: "auth" })       -> full contract details
get_dependencies({ feature: "auth" })  -> what auth depends on

AI before modifying code:

search({ dependsOn: "database" })      -> who depends on database?
validate({ feature: "database" })      -> is database currently valid?
get_feature({ feature: "database" })   -> read the rules before changing

AI creating a new feature:

scaffold({ feature: "payments", basePath: "src/modules", deps: "auth,database" })
update({ feature: "payments", addRules: "idempotent-charges", status: "draft" })
validate({ feature: "payments" })

AI checking health:

compile()                               -> any broken contracts?
drift()                                 -> index up to date?
search({ hasViolations: true })         -> which features have problems?

---

Search Filters

The search tool supports combining multiple filters for precise queries:

Filter	Type	Description
query	string	Text search across all fields (name, description, deps, exports, rules, files)
status	string	Filter by draft, active, or deprecated
dependsOn	string	Find features that depend on this feature
dependedBy	string	Find features that this feature depends on
owner	string	Filter by contract owner
hasRules	string	Find features with rules matching this ID
hasViolations	boolean	true = only broken features, false = only clean

All filters are combinable: search({ dependsOn: "compiler", status: "active" })

---

Web Dashboard (for Humans)

A live dashboard auto-starts on localhost:8000 (auto-fallback to next port if busy):

View	URL	Description
Summary	/	Status bar, metric cards, features table with inline violations
Project	/project	Tree view of contracts + humanized contract detail cards
Brain Link	/graph	Interactive force-directed dependency graph (Canvas 2D, drag & hover)

API endpoints for integration:

• GET /api/data -- Dashboard summary (JSON)
• GET /api/contracts -- All compiled contracts (JSON)
• GET /api/graph -- Dependency graph nodes + edges (JSON)

---

Contract Validation

The validator checks your code against its contracts:

• exports-match -- Barrel exports must match what the contract declares
• deps-declared -- Imports from other features must be declared in dependencies
• no-circular-deps -- Circular dependencies between features are detected
• files-exist -- Declared files must exist in the filesystem

Feature discovery is dynamic -- the validator searches src/**/features/{name}/ and src/**/{name}/ to find feature directories, supporting any project structure.

---

Contract Discovery

Contracts are scanned from two locations:

• contracts/ -- Centralized project-wide contracts (flat scan)
• src/**/ -- Feature-local contracts colocated with code (recursive **/*.contract.yaml)

Ignored directories: node_modules, dist, build, .git, .next, .nuxt, .svelte-kit, coverage, .turbo, .cache

---

Quick Start

Install

bun install

Connect to Claude Code

Create .mcp.json in your project root:

{
  "mcpServers": {
    "contract-mcp": {
      "command": "bun",
      "args": ["run", "src/app/index.ts"],
      "cwd": "/path/to/contract-mcp"
    }
  }
}

Restart Claude Code. You'll see 10 new tools available. The dashboard opens automatically at http://localhost:8000.

Run Standalone

bun run dev    # Start MCP server (stdio)

---

Contract Anatomy

Every feature has a .contract.yaml that follows this structure:

contract:
  version: "1.0.0"
  feature: auth
  description: "Authentication and authorization"
  owner: backend-team
  status: active              # draft | active | deprecated

dependencies:
  internal:
    - feature: database
      reason: "Stores user sessions and credentials"
  external:
    - package: bcrypt
      version: "^5.1.0"
      reason: "Password hashing"

exports:
  functions:
    - name: authenticate
      signature: "(credentials: Credentials) => Result<AuthToken, AuthError>"
      description: "Validates credentials and returns a token"
      pure: true
  types:
    - name: AuthToken
      description: "JWT token wrapper with expiry"

rules:
  - id: token-expiry
    description: "Tokens must expire within 24 hours"
    severity: error           # error | warning | info
    testable: true
  - id: rate-limit
    description: "Max 5 failed attempts per minute per IP"
    severity: error
    testable: true

files:
  - path: src/features/auth/index.ts
    purpose: "Barrel export"
  - path: src/features/auth/auth.ts
    purpose: "Core authentication logic"

The scaffold tool generates this template automatically:

scaffold({ feature: "auth", basePath: "src/modules", deps: "database,crypto", owner: "backend-team" })

---

XML Output (for AI)

Responses are optimized for token efficiency:

<?xml version="1.0" encoding="UTF-8"?>
<contract-mcp tool="search" status="success">
<results dependsOn="compiler" count="4">
<match feature="validator" status="draft" owner="adam" deps="compiler,contract-entity,dependency-graph" exports="validate,validateAll" rules="5">Verifica se o codigo corresponde aos contratos</match>
<match feature="dashboard" status="draft" owner="adam" deps="compiler,validator,indexer" exports="startDashboard,renderDashboard,renderHtml" rules="4">Web dashboard humanizado</match>
</results>
</contract-mcp>

One line per result. Attributes for data, text content for descriptions. Maximum information, minimum tokens.

---

License

MIT