How do I use MCP Contractor?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@MCP Contractor search for active features" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

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.

Related MCP server: Primitiv

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

Maintenance

Resources

Latest Blog Posts

MCP directory API