# 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
- **Solo mode** — `--solo` flag enables mid-session role switching for single-developer use (ceremonial barrier only — see caveats)

## Installation

```bash
npm install -g cleanroom-mcp
```

Or run directly with npx (no install needed):

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

## Quick Start

See [docs/getting-started.md](docs/getting-started.md) for a complete walkthrough.

```bash
# 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:

```bash
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

### Multi-role setup (recommended for real clean-room processes)

Add to your project's `.mcp.json`:

```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:

```bash
# 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)

```json
{
  "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:

```bash
npm install -g cleanroom-mcp
```

```json
{
  "mcpServers": {
    "cleanroom": {
      "command": "cleanroom-mcp",
      "args": ["--solo", "--role", "analyst", "--user", "nick"]
    }
  }
}
```

Example configs are in the [`examples/`](examples/) directory.

## Dashboard

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

```bash
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

```bash
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.