@stackwright-pro/mcp

The MCP server that powers the Pro Otter Raft. Exposes 30 deterministic TypeScript tools to Claude Code and other MCP clients for structured pipeline orchestration, artifact validation, and controlled file I/O.

Architecture: Sinks Not Pipes

When the Otter Raft scaled past nine concurrent agents, the foreman's context window became the bottleneck. Every specialist was shovelling its output back into the conversation, bloating the shared context until the whole raft flipped. Coordination collapsed: later otters couldn't reliably read what earlier otters had produced, and the foreman had no authoritative record of what was actually done versus what was merely narrated.

The fix is a single discipline: every intermediate result is a file on disk; MCP tools are the only I/O interface. Otters never write anything directly — they call a tool, the tool validates and writes, and the next otter reads via another tool. The foreman never accumulates state in memory; it reads the current truth from disk on every step. This makes the pipeline inspectable, resumable, and safe to parallelize — because there is nothing to lose when a context window expires.

.stackwright/
├── init-context.json          ← launcher writes once
├── pipeline-state.json        ← set_pipeline_state
├── questions/{phase}.json     ← write_phase_questions
├── answers/{phase}.json       ← save_phase_answers
└── artifacts/{output}.json    ← validate_artifact (the chokepoint)

Tools Reference

Pipeline State & Control

Sourced from registerPipelineTools (tools/pipeline.ts).

| Tool | Purpose | Reads | Writes | | --------------------------------------- | ---------------------------------------------- | ---------------------------------- | ---------------------------------- | | stackwright_pro_get_pipeline_state | Read current pipeline state | .stackwright/pipeline-state.json | — | | stackwright_pro_set_pipeline_state | Update phase field or top-level status | .stackwright/pipeline-state.json | .stackwright/pipeline-state.json | | stackwright_pro_check_execution_ready | Gate: true only when all 8 phases have answers | .stackwright/answers/ | — | | stackwright_pro_list_artifacts | Inventory of completed specialist outputs | .stackwright/artifacts/ | — |

Question Collection

Sourced from registerPipelineTools (tools/pipeline.ts), registerQuestionTools (tools/questions.ts), and registerOrchestrationTools (tools/orchestration.ts).

| Tool | Purpose | Reads | Writes | | ----------------------------------------- | ---------------------------------------------------------------- | ------------------------------------- | ------------------------------------- | | stackwright_pro_write_phase_questions | Parse otter QUESTION_COLLECTION_MODE response and sink to disk | — | .stackwright/questions/{phase}.json | | stackwright_pro_present_phase_questions | Adapt questions for ask_user_question format | .stackwright/questions/{phase}.json | — | | stackwright_pro_save_phase_answers | Sink user answers to disk | — | .stackwright/answers/{phase}.json | | stackwright_pro_read_phase_answers | Read answers for a phase | .stackwright/answers/{phase}.json | — |

Specialist Execution

Sourced from registerPipelineTools (tools/pipeline.ts) and registerOrchestrationTools (tools/orchestration.ts).

| Tool | Purpose | Reads | Writes | | ----------------------------------------- | ------------------------------------------------------------- | --------------------------------------------- | ------------------------------------- | | stackwright_pro_build_specialist_prompt | Assemble answers + upstream artifacts into specialist prompt | answers/{phase}.json, upstream artifacts/ | — | | stackwright_pro_validate_artifact | Validate specialist output, detect off-script, write if valid | — | .stackwright/artifacts/{phase}.json | | stackwright_pro_get_otter_name | Resolve phase name → otter agent name | — | — | | stackwright_pro_parse_otter_response | Extract JSON from otter response text | — | — | | stackwright_pro_save_manifest | Write consolidated question manifest (legacy path) | — | .stackwright/question-manifest.json |

Controlled File I/O

Sourced from registerSafeWriteTools (tools/safe-write.ts).

| Tool | Purpose | Reads | Writes | | ---------------------------- | ----------------------------------------------------------------------------------- | ----- | ---------------------- | | stackwright_pro_safe_write | Per-otter path allowlist enforcement — the only way specialists write content files | — | Allowlisted paths only |

Domain Knowledge

Sourced from registerDomainTools (tools/domain.ts).

| Tool | Purpose | Reads | Writes | | --------------------------------------- | ----------------------------------------------- | ------------------------------------------------------------- | ------ | | stackwright_pro_list_collections | List API-backed collections for page generation | .stackwright/artifacts/data-config.json → stackwright.yml | — | | stackwright_pro_resolve_data_strategy | Deterministic data freshness strategy lookup | — | — | | stackwright_pro_validate_workflow | Validate workflow.yml graph structure | .stackwright/artifacts/workflow-config.json | — |

Integrity

Sourced from registerIntegrityTools (integrity.ts).

| Tool | Purpose | Reads | Writes | | ---------------------------------------- | --------------------------------------------------------------- | ---------------------------------- | ------ | | stackwright_pro_verify_otter_integrity | SHA-256 certificate-pinned verification of all otter JSON files | packages/otters/src/*-otter.json | — |

Data Explorer

Sourced from registerDataExplorerTools (tools/data-explorer.ts).

| Tool | Purpose | | --------------------------------- | ----------------------------------- | | stackwright_pro_list_entities | List API entities from OpenAPI spec | | stackwright_pro_generate_filter | Generate endpoint filter config |

Security

Sourced from registerSecurityTools (tools/security.ts).

| Tool | Purpose | | ------------------------------------- | ------------------------------------------- | | stackwright_pro_validate_spec | Validate OpenAPI spec against approved list | | stackwright_pro_add_approved_spec | Add spec to approved list | | stackwright_pro_list_approved_specs | List approved specs |

ISR Configuration

Sourced from registerIsrTools (tools/isr.ts).

| Tool | Purpose | | ------------------------------------- | -------------------------------------- | | stackwright_pro_configure_isr | Configure ISR for a single collection | | stackwright_pro_configure_isr_batch | Configure ISR for multiple collections |

Auth

Sourced from registerAuthTools (tools/auth.ts).

| Tool | Purpose | | -------------------------------- | --------------------------------------------- | | stackwright_pro_configure_auth | Generate auth middleware from provider config |

Clarification

Sourced from registerClarificationTools (tools/clarification.ts).

| Tool | Purpose | | --------------------------------- | -------------------------------------- | | stackwright_pro_clarify | Surface mid-execution question to user | | stackwright_pro_detect_conflict | Detect conflicting user preferences |

Packages

Sourced from registerPackageTools (tools/packages.ts).

| Tool | Purpose | | -------------------------------- | ------------------------------ | | stackwright_pro_setup_packages | Bootstrap Pro npm dependencies |

Dashboard Generation

Sourced from registerDashboardTools (tools/dashboard.ts).

| Tool | Purpose | | -------------------------------------- | ---------------------------- | | stackwright_pro_generate_dashboard | Generate dashboard page spec | | stackwright_pro_generate_detail_page | Generate detail page spec |

Security Model

Three layers keep the raft from sinking:

1. Per-otter path allowlists — stackwright_pro_safe_write enforces that each specialist otter can only write to approved paths. page-otter is limited to pages/*/content.yml; auth-otter is limited to config/*.yml and .env*. Attempts to write outside the allowlist are rejected with an error — the otter never touches the filesystem directly.

2. Artifact validation chokepoint — specialists never write artifacts directly. All specialist output flows through stackwright_pro_validate_artifact, which validates the JSON structure and detects off-script code output (e.g. raw TypeScript or markdown smuggled inside a JSON field) before the file is committed. Bad output is rejected and the phase stays incomplete.

3. Certificate-pinned integrity — canonical SHA-256 checksums for all otter JSON prompt files are hardcoded inside this MCP package. stackwright_pro_verify_otter_integrity re-hashes every file in packages/otters/src/*-otter.json at runtime and compares against the pinned values. A modified or tampered otter file is rejected before its prompt ever reaches an LLM.

Phase Dependency Graph

The pipeline enforces this dependency order. A phase cannot begin specialist execution until all of its upstream phases have committed artifacts.

designer ──────────────────────────────┐
api ────────────────────────────────┐  │
auth ───────────────────────────┐   │  │
                                │   │  │
data    ← api                   │   │  │
theme   ← designer              │   │  │
pages   ← designer, theme, api, data, auth
dashboard ← designer, theme, api, data
workflow  ← auth

Integrity

The full integrity enforcement model is documented in docs/INTEGRITY_MODEL.md, including certificate pinning at startup, known enforcement gaps, and the threat model table for each pipeline component.

# The MCP server is configured automatically by the launcher
npx @stackwright-pro/launch-stackwright-pro

# Or manually in claude_desktop_config.json / .mcp.json:
{
  "mcpServers": {
    "stackwright-pro": {
      "command": "node",
      "args": ["node_modules/@stackwright-pro/mcp/dist/server.js"]
    }
  }
}

Development

pnpm --filter @stackwright-pro/mcp test
pnpm --filter @stackwright-pro/mcp build

License

Proprietary — Per Aspera LLC