statemap-mcp 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,138 @@
+# statemap-mcp
+
+MCP server for [Statemap](https://statemap.io) — system state working memory for AI coding agents.
+
+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.
+
+## Setup
+
+### 1. Create a `.statemap` file in your repo root
+
+```json
+{
+  "project_id": "your-project-id",
+  "base_url": "https://statemap.io"
+}
+```
+
+Get this from your project page — click **connect** in the header.
+
+### 2. Set your API key
+
+```sh
+export STATEMAP_API_KEY="sm_your_key_here"
+```
+
+Find your key at [statemap.io/app](https://statemap.io/app) under **API Key**. Add to `.env` or shell profile. Never commit this.
+
+### 3. Add to your editor
+
+#### Claude Code
+
+```sh
+claude mcp add statemap-mcp -e STATEMAP_API_KEY=sm_your_key_here -- npx -y statemap-mcp
+```
+
+Or add to `.claude/mcp.json`:
+
+```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):
+
+```json
+{
+  "mcpServers": {
+    "statemap": {
+      "command": "npx",
+      "args": ["-y", "statemap-mcp"],
+      "env": {
+        "STATEMAP_API_KEY": "sm_your_key_here"
+      }
+    }
+  }
+}
+```
+
+#### Windsurf
+
+Add to `~/.codeium/windsurf/mcp_config.json`:
+
+```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`:
+
+```json
+{
+  "servers": {
+    "statemap": {
+      "command": "npx",
+      "args": ["-y", "statemap-mcp"],
+      "env": {
+        "STATEMAP_API_KEY": "sm_your_key_here"
+      }
+    }
+  }
+}
+```
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `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_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_analyze` | Submit source files for drift detection |
+
+## 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 base URL (default: from `.statemap` or `https://statemap.io`) |
+
+## 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.
+
+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.
+
+## License
+
+MIT

package/dist/index.js

@@ -7,8 +7,7 @@ import { resolve } from "node:path";
 function loadConfig() {
     const apiKey = process.env.STATEMAP_API_KEY;
     if (!apiKey) {
-        process.stderr.write("STATEMAP_API_KEY environment variable is required\n");
-        process.exit(1);
+        return { error: "STATEMAP_API_KEY environment variable is required. Get your key at https://statemap.io/app" };
     }
     let projectId = process.env.STATEMAP_PROJECT_ID || "";
     let baseUrl = process.env.STATEMAP_BASE_URL || "https://statemap.io";
@@ -25,18 +24,20 @@ function loadConfig() {
         // .statemap file not found — rely on env vars
     }
     if (!projectId) {
-        process.stderr.write("Project ID required: set in .statemap file or STATEMAP_PROJECT_ID env var\n");
-        process.exit(1);
+        return { error: "Project ID required: add a .statemap file to your repo root or set STATEMAP_PROJECT_ID env var. See https://statemap.io" };
     }
     return { projectId, baseUrl: baseUrl.replace(/\/$/, ""), apiKey };
 }
-async function api(config, path, opts) {
-    const url = `${config.baseUrl}/api/projects/${config.projectId}${path}`;
+async function api(cfg, path, opts) {
+    const err = checkConfig();
+    if (err)
+        throw new Error(err);
+    const url = `${cfg.baseUrl}/api/projects/${cfg.projectId}${path}`;
     const res = await fetch(url, {
         ...opts,
         headers: {
             "Content-Type": "application/json",
-            "Authorization": `Bearer ${config.apiKey}`,
+            "Authorization": `Bearer ${cfg.apiKey}`,
             "X-Agent-Id": "mcp-server",
             ...opts?.headers,
         },
@@ -60,11 +61,16 @@ async function api(config, path, opts) {
 function text(data) {
     return { content: [{ type: "text", text: typeof data === "string" ? data : JSON.stringify(data, null, 2) }] };
 }
-const config = loadConfig();
+const loaded = loadConfig();
+const configError = "error" in loaded ? loaded.error : null;
+const config = "error" in loaded ? { projectId: "", baseUrl: "", apiKey: "" } : loaded;
 const server = new McpServer({
     name: "statemap",
     version: "0.1.0",
 });
+function checkConfig() {
+    return configError;
+}
 server.tool("statemap_snapshot", "Load the full system state model — all models, containers, transitions, invariants, and read dependencies", async () => {
     const data = await api(config, "/snapshot");
     return text(data);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "statemap-mcp",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "MCP server for Statemap — system state working memory for AI agents",
   "type": "module",
   "main": "dist/index.js",
@@ -12,7 +12,8 @@
     "dev": "tsc --watch"
   },
   "files": [
-    "dist"
+    "dist",
+    "README.md"
   ],
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.1",