statemap-mcp 0.1.11 → 0.1.12

package/README.md

@@ -1,39 +1,34 @@
 # statemap-mcp
 
-MCP server for [Statemap](https://statemap.io) — system state working memory for AI coding agents.
+MCP server for [Statemap](https://statemap.io) — system state management and architectural coherence for codebases.
 
-Gives any MCP-compatible agent (Claude Code, Cursor, Windsurf, VS Code Copilot) native access to your project's state model. No context window loading required — agents call tools directly.
+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.
 
-## Setup
-
-### 1. Create a `.statemap` file in your repo root
+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.
 
-```json
-{
-  "project_id": "your-project-id",
-  "base_url": "https://statemap.io"
-}
-```
+## What Statemap does
 
-Get this from your project page — click **connect** in the header.
+- **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
 
-### 2. Set your API key
+## Setup
 
-```sh
-export STATEMAP_API_KEY="sm_your_key_here"
-```
+### 1. Create an account
 
-Find your key at [statemap.io/app](https://statemap.io/app) under **API Key**. Add to `.env` or shell profile. Never commit this.
+Sign up at [statemap.io](https://statemap.io) and copy your API key from the **Keys** tab.
 
-### 3. Add to your editor
+### 2. Add to your editor
 
 #### Claude Code
 
 ```sh
-claude mcp add statemap-mcp -e STATEMAP_API_KEY=sm_your_key_here -- npx -y statemap-mcp
+claude mcp add statemap -e STATEMAP_API_KEY=sm_your_key_here -- npx -y statemap-mcp
 ```
 
-Or add to `.claude/mcp.json`:
+Or add to `.claude.json`:
 
 ```json
 {
@@ -103,21 +98,28 @@ Add to `.vscode/mcp.json`:
 }
 ```
 
+### 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_query` | Natural language query ("what breaks if I remove X?") |
-| `statemap_validate` | Check all invariant constraints pass |
-| `statemap_divergence` | Check for internal consistency issues |
+| `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 |
+| `statemap_import` | Bulk import entities (idempotent) |
 | `statemap_analyze` | Submit source files for drift detection |
+| `statemap_architect_review` | Guided dead-state cleanup session |
 
 ## Environment Variables
 
@@ -125,13 +127,13 @@ Add to `.vscode/mcp.json`:
 |----------|----------|-------------|
 | `STATEMAP_API_KEY` | Yes | Your Statemap API key (`sm_...`) |
 | `STATEMAP_PROJECT_ID` | No | Override project ID (default: from `.statemap`) |
-| `STATEMAP_BASE_URL` | No | Override base URL (default: from `.statemap` or `https://statemap.io`) |
+| `STATEMAP_BASE_URL` | No | Override API URL (default: `https://statemap.io`) |
 
-## How It Works
+## How it works
 
-The MCP server is a thin wrapper around the [Statemap REST API](https://statemap.io). Each tool maps to one API call. The server reads `.statemap` from your working directory for the project ID and base URL, authenticates with `STATEMAP_API_KEY` from your environment, and communicates over stdio.
+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.
 
-Agents use it to check existing state before writing code, update the model after changes, and validate constraints before merging — all without you manually loading anything into context.
+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
 

package/dist/index.js

@@ -294,7 +294,7 @@ let configError = "error" in loaded ? loaded.error : null;
 let config = "error" in loaded ? { projectId: "", baseUrl: "", apiKey: "" } : loaded;
 const server = new McpServer({
     name: "statemap",
-    version: "0.1.11",
+    version: "0.1.12",
 }, {
     instructions: `Statemap is a system state model for this project. Here's how to get started:
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "statemap-mcp",
-  "version": "0.1.11",
-  "description": "MCP server for Statemap — system state working memory for AI agents",
+  "version": "0.1.12",
+  "description": "MCP server for Statemap — system state management and architectural coherence for codebases",
   "type": "module",
   "main": "dist/index.js",
   "bin": {