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

MCP Contractor

MCP Contractor

Why

How It Works

MCP Tools

Discovery

Analysis

Mutation

Onboarding

Example Workflows

Search Filters

Web Dashboard (for Humans)

Contract Validation

Contract Discovery

Quick Start

Install

Connect to Claude Code

Run Standalone

Contract Anatomy

XML Output (for AI)

License

Score

Proud of your score? Add this badge to your README.

MCP Contractor FAQ

How do I install MCP Contractor?

Is MCP Contractor an official MCP server?

Related MCP servers

Related guides