statemap-mcp 0.1.7 → 0.1.8

package/dist/index.js

@@ -2,7 +2,7 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
-import { readFileSync } from "node:fs";
+import { readFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 function loadConfig() {
     const apiKey = process.env.STATEMAP_API_KEY;
@@ -27,6 +27,33 @@ function loadConfig() {
     }
     return { projectId, baseUrl: baseUrl.replace(/\/$/, ""), apiKey };
 }
+async function apiRaw(baseUrl, apiKey, path, opts) {
+    const url = `${baseUrl}${path}`;
+    const res = await fetch(url, {
+        ...opts,
+        headers: {
+            "Content-Type": "application/json",
+            "Authorization": `Bearer ${apiKey}`,
+            "X-Agent-Id": "mcp-server",
+            ...opts?.headers,
+        },
+    });
+    const body = await res.text();
+    if (!res.ok) {
+        let msg = res.statusText;
+        try {
+            msg = JSON.parse(body).error || msg;
+        }
+        catch { }
+        throw new Error(`API error ${res.status}: ${msg}`);
+    }
+    try {
+        return JSON.parse(body);
+    }
+    catch {
+        return body;
+    }
+}
 async function api(cfg, path, opts) {
     const err = checkConfig();
     if (err)
@@ -254,28 +281,53 @@ function batchSearch(snap, op, names) {
     }
     return results;
 }
-const loaded = loadConfig();
-const configError = "error" in loaded ? loaded.error : null;
-const config = "error" in loaded ? { projectId: "", baseUrl: "", apiKey: "" } : loaded;
+let loaded = loadConfig();
+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.5",
+    version: "0.1.6",
+}, {
+    instructions: `Statemap is a system state model for this project. Here's how to get started:
+
+1. If there's no .statemap config file in the project root, run statemap_init first:
+   - Use action "list" to see existing projects
+   - Use action "select" to connect to one, or "create" to make a new one
+   - This writes a .statemap file and configures the server automatically
+
+2. Once connected, the typical workflow is:
+   - statemap_snapshot: Get an overview of all declared state (models, containers, transitions, invariants, read deps)
+   - statemap_list: Drill into a specific entity type (supports pagination with offset/limit)
+   - statemap_validate: Check invariant constraints for violations
+   - statemap_divergence: Detect drift between declared state and actual code
+   - statemap_import: Bulk upsert entities (idempotent — safe to re-run)
+   - statemap_analyze: Submit source files for codebase analysis
+   - statemap_architect_review: Start a guided review session with the project architect to identify dead and unhooked state
+
+3. When modifying state, use the specific update tools (statemap_update_model, statemap_update_container, etc.)
+
+If any tool returns a config error, run statemap_init to fix it.`,
 });
 function checkConfig() {
     return configError;
 }
+function reloadConfig() {
+    loaded = loadConfig();
+    configError = "error" in loaded ? loaded.error : null;
+    config = "error" in loaded ? { projectId: "", baseUrl: "", apiKey: "" } : loaded;
+}
 server.tool("statemap_snapshot", "Load the system state model. Returns a summary with all model names, fields, containers, transitions, invariants, and read deps. Use statemap_list for full details on a specific entity type.", async () => {
     const data = await api(config, "/snapshot");
     return text(summarizeSnapshot(data));
 });
-server.tool("statemap_list", "List full details for a specific entity type: models, containers, transitions, invariants, or read-deps. Use after statemap_snapshot to drill into specifics.", {
+server.tool("statemap_list", "List full details for a specific entity type: models, containers, transitions, invariants, or read-deps. Use after statemap_snapshot to drill into specifics. Supports pagination via offset (default 0) and limit (default 50).", {
     entity_type: z.enum(["models", "containers", "transitions", "invariants", "read-deps"]).describe("Which entity type to list"),
-}, async ({ entity_type }) => {
+    offset: z.number().int().min(0).default(0).describe("Starting index for pagination (default 0)"),
+    limit: z.number().int().min(1).max(100).default(50).describe("Number of items to return (default 50, max 100)"),
+}, async ({ entity_type, offset, limit }) => {
     const data = await api(config, `/${entity_type}`);
-    if (data.length > 50) {
-        return text({ total: data.length, showing: 50, truncated: true, items: data.slice(0, 50) });
-    }
-    return text(data);
+    const page = data.slice(offset, offset + limit);
+    return text({ total: data.length, offset, limit, showing: page.length, hasMore: offset + limit < data.length, items: page });
 });
 server.tool("statemap_validate", "Check all invariant constraints — returns summary counts and up to 30 failures with details", async () => {
     const data = await api(config, "/validate");
@@ -453,6 +505,14 @@ ${modelList}
 
 Follow these steps IN ORDER. Do not skip entity types — dead state accumulates everywhere.
 
+### Step 0: Safe checkpoint
+**⚠️ WARNING: This review can result in changes to your codebase, database schemas, and live infrastructure. These changes can be extremely dangerous if handled incorrectly. Always create a rollback point before proceeding.**
+
+Check if the project is a git repo. If it is, ask the user: **"Can I commit your current work-in-progress so we have a safe rollback point before the review?"** If they agree, create a commit with a message like "wip: checkpoint before architect review". If there's no git repo, suggest initializing one with \`git init\` and an initial commit before proceeding. If the user declines, make sure they understand the risk before continuing.
+
+### Step 0.5: Codebase discovery
+**Deploy a subagent (if possible)** to scan the codebase and build context before the interactive review begins. The agent should find schema files (schema.sql, prisma, drizzle, etc), state stores (zustand, redux, context), route handlers, components, and config files. This context is essential for Steps 9-10 when you'll be making actual code changes. Keep the results to yourself — don't dump raw findings on the architect.
+
 ### Step 1: Present overview
 Summarize the health from the data above. Note total error counts but don't try to fix anything yet — many errors are downstream of dead state.
 
@@ -486,20 +546,27 @@ Don't assume — a dead parent doesn't always mean dead children.
 After all kills are identified across all entity types, confirm: **"Everything remaining is still live and intentional?"**
 
 ### Step 9: Clean up the codebase
-For each dead entity, find and remove the actual code. Search the codebase for:
+**Deploy a single sequential cleanup subagent.** Do NOT parallelize removals — a single bad delete can cascade into broken imports and runtime errors. The agent processes each dead entity ONE AT A TIME, in this order for each:
+
+1. Search by entity name (grep for the model/table/store name) to find ALL references
+2. Present the full list of files and lines that will be affected to the architect
+3. Wait for explicit approval before making changes
+4. Make the removal
+5. Check imports — if removing code breaks imports elsewhere, trace and fix those too
+6. Confirm the build/typecheck still passes before moving to the next entity
+
+What to remove per entity type:
 - **Dead models**: DROP/remove from schema files (schema.sql, prisma, drizzle, etc), delete TypeScript interfaces/types, remove API routes/handlers that CRUD this model, remove store slices/hooks that manage this state, remove UI components that only exist to display this model
 - **Dead containers**: remove store definitions (zustand stores, context providers, cache configs), remove connection/initialization code
 - **Dead transitions**: remove the handler/route/function that performs this mutation, remove associated validation logic
 - **Dead read deps**: remove the component/hook/function that consumes this state
 - **Dead invariants**: remove validation checks that enforce the dead constraint
 
-Search by entity name (grep for the model/table/store name) to find all references. Check imports — if removing a file breaks imports elsewhere, trace those too.
-
-After the code is cleaned, re-import to Statemap using statemap_import so the model reflects the new codebase reality.
+After ALL dead entities are cleaned, re-import to Statemap using statemap_import so the model reflects the new codebase reality.
 Re-run statemap_validate and statemap_divergence to confirm improvement.
 
 ### Step 10: Fix the living
-Address remaining errors on live entities: missing relationships, orphaned references, unhooked state. Propose fixes based on code analysis, grouped by confidence:
+**Deploy a subagent** to address remaining errors on live entities: missing relationships, orphaned references, unhooked state. The agent proposes fixes based on code analysis, grouped by confidence:
 - **Obvious wiring** — FK exists in schema but undeclared as a relationship, field exists but not in model, etc. Present these as a batch.
 - **Inferred connections** — looks related but no explicit FK, probable container assignment based on naming, etc. Present these individually.
 Ask the architect to approve: they can rubber-stamp the obvious stuff ("all good") and cherry-pick the ambiguous ones.
@@ -517,5 +584,45 @@ Ask the architect to approve: they can rubber-stamp the obvious stuff ("all good
 Start by presenting the overview, then present the model list. Ask the architect which models are dead.`;
     return text(procedure);
 });
+server.tool("statemap_init", "Initialize Statemap for this project. Lists your existing projects or creates a new one, then writes a .statemap config file. Run this if you get config errors or when setting up Statemap for the first time.", {
+    action: z.enum(["list", "create", "select"]).describe("'list' to see existing projects, 'create' to make a new one, 'select' to pick an existing one by ID"),
+    project_name: z.string().optional().describe("Name for new project (required for 'create')"),
+    project_id: z.string().optional().describe("Project ID to select (required for 'select')"),
+}, async ({ action, project_name, project_id }) => {
+    const apiKey = process.env.STATEMAP_API_KEY;
+    if (!apiKey) {
+        return text({ error: "STATEMAP_API_KEY environment variable is required. Get your key at https://statemap.io/app" });
+    }
+    const baseUrl = (process.env.STATEMAP_BASE_URL || "https://statemap.io").replace(/\/$/, "");
+    if (action === "list") {
+        const projects = await apiRaw(baseUrl, apiKey, "/api/projects");
+        if (projects.length === 0) {
+            return text({ projects: [], hint: "No projects found. Use action 'create' with a project_name to create one." });
+        }
+        return text({ projects, hint: "Use action 'select' with a project_id to connect to one of these, or 'create' to make a new one." });
+    }
+    if (action === "create") {
+        if (!project_name)
+            return text({ error: "project_name is required for 'create'" });
+        const project = await apiRaw(baseUrl, apiKey, "/api/projects", {
+            method: "POST",
+            body: JSON.stringify({ name: project_name }),
+        });
+        const configPath = resolve(process.cwd(), ".statemap");
+        writeFileSync(configPath, JSON.stringify({ project_id: project.id }, null, 2) + "\n");
+        reloadConfig();
+        return text({ ok: true, project, config_written: configPath });
+    }
+    if (action === "select") {
+        if (!project_id)
+            return text({ error: "project_id is required for 'select'" });
+        const project = await apiRaw(baseUrl, apiKey, `/api/projects/${project_id}`);
+        const configPath = resolve(process.cwd(), ".statemap");
+        writeFileSync(configPath, JSON.stringify({ project_id: project.id }, null, 2) + "\n");
+        reloadConfig();
+        return text({ ok: true, project, config_written: configPath });
+    }
+    return text({ error: "Unknown action" });
+});
 const transport = new StdioServerTransport();
 await server.connect(transport);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "statemap-mcp",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "MCP server for Statemap — system state working memory for AI agents",
   "type": "module",
   "main": "dist/index.js",