statemap-mcp

MCP server for Statemap — system state management and architectural coherence for codebases.

Statemap tracks every data model, state container, transition, invariant, and read dependency in your system. It catches drift between your code and your architecture, enforces constraints automatically, and keeps your codebase structurally sound as it scales.

This MCP server gives any compatible agent (Claude Code, Cursor, Windsurf, VS Code Copilot) direct access to your project's state model via tool calls.

What Statemap does

• Tracks system state — data models, stores, transitions, invariants, and read dependencies, persisted across sessions
• Enforces constraints — uniqueness, referential integrity, missing fields, orphaned references — caught automatically
• Detects drift — diffs your actual source files (Prisma, SQL, TypeScript, Zustand) against the declared model
• Guided cleanup — architect review walks through every entity to identify dead state from pivots and fix broken wiring
• CI integration — GitHub Action posts divergence reports on PRs and blocks merges on invariant violations

Setup

1. Create an account

Sign up at statemap.io and copy your API key from the Keys tab.

2. Add to your editor

Claude Code

claude mcp add statemap -e STATEMAP_API_KEY=sm_your_key_here -- npx -y statemap-mcp

Or add to .claude.json:

{
  "mcpServers": {
    "statemap": {
      "command": "npx",
      "args": ["-y", "statemap-mcp"],
      "env": {
        "STATEMAP_API_KEY": "sm_your_key_here"
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "statemap": {
      "command": "npx",
      "args": ["-y", "statemap-mcp"],
      "env": {
        "STATEMAP_API_KEY": "sm_your_key_here"
      }
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "statemap": {
      "command": "npx",
      "args": ["-y", "statemap-mcp"],
      "env": {
        "STATEMAP_API_KEY": "sm_your_key_here"
      }
    }
  }
}

VS Code Copilot

Add to .vscode/mcp.json:

{
  "servers": {
    "statemap": {
      "command": "npx",
      "args": ["-y", "statemap-mcp"],
      "env": {
        "STATEMAP_API_KEY": "sm_your_key_here"
      }
    }
  }
}

3. Initialize

Tell your agent to run statemap_init — it creates a project and writes a .statemap config file to your repo root. From there it can scan your codebase, import your architecture, and start enforcing.

Tools

| Tool | Description | |------|-------------| | statemap_init | Create or connect to a project | | statemap_snapshot | Load the full system state model | | statemap_list | List entities by type with pagination | | statemap_search | Query references, impact, readers, writers, storage, schemas | | statemap_validate | Check all invariant constraints | | statemap_divergence | Detect consistency issues | | statemap_update_model | Create or update a data model | | statemap_update_container | Create or update a state container | | statemap_update_transition | Create or update a state transition | | statemap_add_invariant | Add a constraint | | statemap_update_read_deps | Create or update read dependencies | | statemap_import | Bulk import entities (idempotent) | | statemap_analyze | Submit source files for drift detection | | statemap_architect_review | Guided dead-state cleanup session |

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | STATEMAP_API_KEY | Yes | Your Statemap API key (sm_...) | | STATEMAP_PROJECT_ID | No | Override project ID (default: from .statemap) | | STATEMAP_BASE_URL | No | Override API URL (default: https://statemap.io) |

How it works

The MCP server wraps the Statemap REST API. Each tool maps to one or more API calls. It reads .statemap from your working directory for the project ID, authenticates with STATEMAP_API_KEY, and communicates over stdio.

Your agent uses it to check existing architecture before writing code, update the state model after changes, enforce constraints continuously, and detect when code has drifted from the declared architecture.

License

MIT