cleanroom-mcp

An MCP server that enforces the clean-room software reimplementation process. AI coding agents connect to this server and receive role-gated access to tools — an analyst agent gets spec-writing tools, an implementer agent gets coding tools, and neither can cross the information barrier. Every action is automatically logged to a tamper-evident audit trail.

Why

Clean-room reimplementation is a legal process for recreating software without copying the original source code. It requires strict separation between people who study the original (analysts) and people who write the new version (implementers). Traditionally this is enforced by policy. This MCP server enforces it architecturally — an implementer agent literally cannot call analyst tools or read draft specs.

How It Works

The server exposes 20 MCP tools organized by role:

| Role | Can Do | Cannot Do | |------|--------|-----------| | Analyst | Create specs, study original software, submit for review | Read implementation code, access clean room tools | | Implementer | Read handed-off specs, write code, run tests | Read draft specs, access analysis tools | | Monitor | Review specs for contamination, approve/reject, view audit trail | Modify specs or implementation | | Lead | All monitor capabilities + project init, team management | Create specs (that's the analyst's job) |

Every tool call is logged to a SHA-256 hash-chained audit trail. Access denials are logged too — if an implementer tries to read a draft spec, the attempt is recorded and blocked.

The Spec Lifecycle

Analyst creates spec ──> Submits for review ──> Monitor reviews
                                                    │
                                        ┌───────────┴───────────┐
                                        │                       │
                                   Approved                 Rejected
                                        │                  (with feedback)
                                        v                       │
                              Monitor hands off          Analyst revises
                                        │                       │
                                        v                       └──> Resubmits
                              Implementer receives
                              (spec is now immutable)

Features

• 20 MCP tools across project management, spec lifecycle, review, team, audit, implementation, and verification
• Role-based access control enforced at the tool level — not just policy, but architecture
• Hash-chained audit trail — tamper-evident log of every action with SHA-256 chain verification
• 6 spec templates — api-endpoint, behavior, file-format, protocol, data-structure, algorithm
• 3 MCP prompts — role-specific system instructions for analyst, implementer, and monitor sessions
• MCP Resources — implementers automatically see handed-off specs via cleanroom://specs/
• Black-box verification — compare original and reimplementation behavior with exact, fuzzy, or semantic matching
• Web dashboard — real-time overview at localhost:7391 with three role-gated views (Dirty Room, Clean Room, Bridge)
• Audit export — JSON or CSV export of the full audit trail for compliance records
• Attestation system — record formal attestations from humans and AI agents about data access

Installation

npm install -g cleanroom-mcp

Or run directly with npx (no install needed):

npx cleanroom-mcp --project ./my-project

Quick Start

See docs/getting-started.md for a complete walkthrough.

# Start as analyst
CLEANROOM_ROLE=analyst CLEANROOM_USER=analyst-01 \
  npx cleanroom-mcp --project ./my-project

# Start with the web dashboard
CLEANROOM_ROLE=analyst CLEANROOM_USER=analyst-01 \
  npx cleanroom-mcp --project ./my-project --dashboard

Using with Claude Code

Add to your project's .mcp.json:

{
  "mcpServers": {
    "cleanroom": {
      "command": "npx",
      "args": ["cleanroom-mcp", "--project", "."],
      "env": {
        "CLEANROOM_ROLE": "analyst",
        "CLEANROOM_USER": "analyst-agent-01"
      }
    }
  }
}

Run separate Claude Code sessions for each role:

# Terminal 1: Analyst studies the original, writes specs
CLEANROOM_ROLE=analyst claude

# Terminal 2: Monitor reviews specs for contamination
CLEANROOM_ROLE=monitor claude

# Terminal 3: Implementer builds from handed-off specs
CLEANROOM_ROLE=implementer claude

Example configs are in the examples/ directory.

Dashboard

Start the server with --dashboard to enable the web UI:

CLEANROOM_ROLE=analyst CLEANROOM_USER=analyst-01 \
  node dist/server.js --project ./my-project --dashboard --port 7391

The dashboard prints per-role URLs with auth tokens. Three views:

• Dirty Room — analyst's workspace, spec progress, activity feed
• Clean Room — implementer's view, handed-off specs, test results
• Bridge — monitor's command center with pipeline view, review queue, and audit trail

The dashboard updates in real-time via SSE as agents work.

Project Structure

src/
├── server.ts              # MCP server entry + CLI
├── core/
│   ├── types.ts           # Zod schemas + TypeScript types
│   ├── config.ts          # .cleanroom/config.yaml management
│   ├── audit-engine.ts    # SHA-256 hash-chained audit log
│   ├── access-control.ts  # Role-based tool gating
│   └── spec-engine.ts     # Spec lifecycle (create → handoff)
├── tools/
│   ├── project.ts         # cleanroom_init, cleanroom_status
│   ├── spec.ts            # spec_create, spec_read, spec_list, spec_submit
│   ├── review.ts          # spec_review, spec_handoff
│   ├── team.ts            # team_add, team_list, attest, ai_log
│   ├── audit.ts           # audit_log, audit_verify, audit_export
│   ├── implement.ts       # impl_read_spec, impl_run_tests
│   └── verify.ts          # verify_run, verify_report
├── prompts/               # Role-specific MCP prompt templates
├── resources/             # MCP Resources (specs, project status)
├── templates/             # Spec templates (markdown)
└── dashboard/
    ├── server.ts          # Express server + auth
    ├── api.ts             # REST API routes
    ├── sse.ts             # Server-Sent Events
    ├── auth.ts            # Token generation
    └── views/             # HTML dashboard pages

Development

npm install          # Install dependencies
npm run build        # Build with tsup
npm run dev          # Build in watch mode
npm test             # Run tests (vitest)
npm run typecheck    # Type check without emitting

Security Considerations

What the MCP enforces

• Tool-level access control — roles cannot call tools outside their permissions
• Resource-level filtering — implementers only see handed-off specs
• Automatic audit logging — every tool call recorded, including denied access
• Tamper-evident audit trail — hash chain detects any modification

What the MCP does not enforce

• Filesystem access — an agent with normal filesystem access could read analysis files directly. For maximum rigor, keep analysis and implementation in separate repositories.
• AI training data — if the AI model was trained on the original source code, the MCP cannot prevent that knowledge from influencing the implementation. Record this risk via attestations.
• Network access — agents could search the web for the original source. The MCP prompts instruct agents not to, but human oversight remains important.

License

Apache-2.0

Disclaimer

This is a process management tool, not legal advice. The legal validity of any clean-room implementation depends on the specific circumstances, jurisdiction, and execution. Consult with intellectual property counsel for your specific situation.