Skip to main content
Glama

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.

Related MCP server: mcp-audit-server

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

  • Solo mode — --solo flag enables mid-session role switching for single-developer use (ceremonial barrier only — see caveats)

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

Solo Mode

For solo developers or experimentation, the --solo flag enables mid-session role switching without restarting the server:

npx cleanroom-mcp --project ./my-project --solo --role analyst --user nick

This registers a cleanroom_switch_role tool that lets you change roles on the fly:

cleanroom_switch_role({ role: "implementer" })
→ Role switched. Previous: analyst, Current: implementer

Important caveats about solo mode:

  • Role-based tool gating is still enforced — when you're operating as an analyst, you can't call implementer tools until you switch. This provides structural discipline for thinking in the right mode.

  • However, since you can switch roles at any time, solo mode would not stand up to a rigorous legal audit. There's nothing stopping you from switching to analyst, reading a draft spec, switching to implementer, and using that knowledge. The information barrier is ceremonial, not enforceable.

  • Every role switch is recorded in the audit trail, so there's a clear record of what happened, but the process integrity depends entirely on your own discipline.

  • Without the --solo flag, the cleanroom_switch_role tool doesn't exist at all — the hard wall is preserved for real multi-person clean-room processes.

Solo mode is useful for:

  • Learning the clean-room process before involving a full team

  • Prototyping specs and implementation in a single session

  • Personal projects where the process discipline matters more than legal defensibility

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

Solo setup (single session, role switching)

{
  "mcpServers": {
    "cleanroom": {
      "command": "npx",
      "args": ["cleanroom-mcp", "--project", ".", "--solo", "--role", "analyst", "--user", "nick"]
    }
  }
}

Or install globally and add to ~/.mcp.json to make it available in every project:

npm install -g cleanroom-mcp
{
  "mcpServers": {
    "cleanroom": {
      "command": "cleanroom-mcp",
      "args": ["--solo", "--role", "analyst", "--user", "nick"]
    }
  }
}

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.

  • Solo mode boundaries — --solo mode lets a single user switch roles freely. Tool gating is enforced per-role, but since the same person controls when to switch, the information barrier is ceremonial. Solo mode is for process discipline and learning, not legal defensibility. The audit trail records every role switch, but it will clearly show a single actor wearing multiple hats.

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.

Available Tools

19 tools
cleanroom_ai_logLog AI ActivityA

Log AI agent activity to the audit trail. Call this to record significant actions taken by AI agents, including session starts, model identifiers, and context that was provided to the agent.

Inputs: model (required), action (required), agent_name (required), session_id, +1 more.

cleanroom_attestRecord AttestationA

Record a formal attestation for the clean-room process. For human team members, this confirms they have not accessed restricted materials. For AI agents, this records what data the agent had access to, including training data disclosures. Attestations are permanently recorded in the audit trail.

Inputs: name (required), role (required), statement (required), attestation_type (required), +2 more.

cleanroom_audit_exportExport Audit TrailA

Export the complete audit trail as JSON or CSV for compliance records and legal documentation. The export includes all entries with their hash chain, timestamps, and actor information.

Inputs: format, output_path, include_details.

cleanroom_audit_logView Audit LogA

View the project's tamper-evident audit trail. Every tool call, spec handoff, review decision, access denial, and attestation is logged with timestamps and hash-chained entries. Supports filtering by type and date.

Inputs: limit, since, filter_type.

cleanroom_audit_verifyVerify Audit IntegrityA

Verify the integrity of the project's audit trail by checking the SHA-256 hash chain. If any entry has been modified, added, or removed, this will detect the break point. All roles can verify the audit trail.

Inputs: no named parameters.

cleanroom_impl_read_specRead Implementation SpecA

Read a specification that has been handed off to the implementation team. Returns the full spec content along with extracted acceptance criteria that the implementation must satisfy. Only handed-off specs are accessible through this tool.

Inputs: name (required).

cleanroom_impl_run_testsRun Implementation TestsA

Run the test suite for the reimplementation. Executes the test command in the implementation directory and returns results. Optionally filter to tests for a specific spec.

Inputs: spec_name, test_command.

cleanroom_initInitialize Clean-Room ProjectA

Create a new clean-room reimplementation project with the standard directory structure, config file, and audit trail. This sets up the analysis/, implementation/, and verification/ directories with proper separation. Use this at the start of a new clean-room project.

Inputs: name (required), target (required), description (required), license, +1 more.

cleanroom_spec_createCreate SpecificationA

Create a new behavioral specification for a component of the target software. Uses a structured template to guide the analyst through documenting observable behavior without including implementation details. The spec will be in 'draft' status. Available templates: api-endpoint, file-format, protocol, behavior, data-structure, algorithm.

Inputs: name (required), template (required), target_component (required), initial_content.

cleanroom_spec_handoffHand Off SpecificationA

Release an approved specification to the implementation team. This copies the spec to the handoff directory, makes it available as an MCP Resource for implementer agents, and creates a signed audit record of the handoff. This action is IRREVERSIBLE — once handed off, the spec cannot be modified.

Inputs: name (required).

cleanroom_spec_listList SpecificationsA

List all specifications in the project. Supports filtering by status. Implementers will only see specs with status 'handed-off'. Returns a summary of each spec with name, status, template, and target component.

Inputs: status.

cleanroom_spec_readRead SpecificationA

Read the contents of a specification. Analysts can read any spec. Implementers can only read specs that have been handed off (status: 'handed-off'). Monitors can read any spec for review purposes.

Inputs: name (required).

cleanroom_spec_reviewReview SpecificationA

Review a submitted specification for contamination. Check that it contains only observable behavior descriptions and no implementation details from the original software. Approve it for handoff or reject it with specific feedback about which sections need revision.

Inputs: name (required), decision (required), feedback, contamination_flags.

cleanroom_spec_submitSubmit Spec for ReviewA

Submit a draft specification for contamination review by the monitor. The monitor will check that the spec contains no implementation details, source code, or internal architecture from the original. Only draft or rejected specs can be submitted.

Inputs: name (required), notes.

cleanroom_statusProject StatusA

Get the current status of the clean-room project including spec progress, team members, and audit trail integrity. Shows a summary of all specifications by status, team composition, and whether the audit chain is intact.

Inputs: no named parameters.

cleanroom_team_addAdd Team MemberA

Add a team member (human or AI agent) to the clean-room project. Each member is assigned a role that determines their tool access. Only the lead role can add team members.

Inputs: name (required), role (required), type (required), email, +1 more.

cleanroom_team_listList Team MembersA

List all team members in the clean-room project with their roles, types (human/AI), and any associated metadata.

Inputs: no named parameters.

cleanroom_verify_reportVerification ReportA

Generate a report from the most recent verification run, or a summary of all verification runs. Includes match rates, mismatched cases, and spec coverage.

Inputs: format.

cleanroom_verify_runRun Behavioral VerificationA

Compare the reimplementation's behavior against the original software using black-box testing. Feeds identical inputs to both commands and compares outputs. Does NOT access or analyze source code of either — both are treated as opaque executables. Comparison modes: exact (byte-for-byte), fuzzy (whitespace-normalized), semantic (JSON-aware).

Inputs: test_cases (required), reimpl_command (required), original_command (required), timeout_ms, +1 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 19 tools

    Disambiguation4/5

    Most tools have clearly distinct purposes, but cleanroom_spec_read and cleanroom_impl_read_spec overlap in that both read specs, though the former has role-based restrictions and the latter is specifically for handed-off specs. Overall, the separation is clear enough.

    Naming Consistency4/5

    All tools share the cleanroom_ prefix and use snake_case, but the pattern varies between domain_verb (cleanroom_init, cleanroom_status) and domain_object_verb (cleanroom_spec_create, cleanroom_audit_log). This is mostly consistent but not perfectly uniform.

    Tool Count4/5

    19 tools is on the higher side but reasonable for a full clean-room workflow covering setup, team management, specs, audit, implementation, and verification. Each tool serves a distinct function in the process.

    Completeness3/5

    The core lifecycle is covered (init, spec creation/review/handoff, audit, verification), but there is no tool to edit or delete a draft spec, and no way to remove team members. These gaps could hinder workflow efficiency but are not fatal.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers