statemap-mcp 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,184 @@
+#!/usr/bin/env node
+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 { 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);
+    }
+    let projectId = process.env.STATEMAP_PROJECT_ID || "";
+    let baseUrl = process.env.STATEMAP_BASE_URL || "https://statemap.io";
+    try {
+        const configPath = resolve(process.cwd(), ".statemap");
+        const raw = readFileSync(configPath, "utf-8");
+        const parsed = JSON.parse(raw);
+        if (parsed.project_id)
+            projectId = parsed.project_id;
+        if (parsed.base_url)
+            baseUrl = parsed.base_url;
+    }
+    catch {
+        // .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 { projectId, baseUrl: baseUrl.replace(/\/$/, ""), apiKey };
+}
+async function api(config, path, opts) {
+    const url = `${config.baseUrl}/api/projects/${config.projectId}${path}`;
+    const res = await fetch(url, {
+        ...opts,
+        headers: {
+            "Content-Type": "application/json",
+            "Authorization": `Bearer ${config.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;
+    }
+}
+function text(data) {
+    return { content: [{ type: "text", text: typeof data === "string" ? data : JSON.stringify(data, null, 2) }] };
+}
+const config = loadConfig();
+const server = new McpServer({
+    name: "statemap",
+    version: "0.1.0",
+});
+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);
+});
+server.tool("statemap_query", "Ask a natural language question about the system state (e.g. 'what breaks if I remove the cart model?', 'who reads from user?')", { question: z.string().describe("Natural language question about the system state"), scope: z.array(z.string()).optional().describe("Optional: limit query to specific entity names") }, async ({ question, scope }) => {
+    const data = await api(config, "/query", { method: "POST", body: JSON.stringify({ question, scope }) });
+    return text(data);
+});
+server.tool("statemap_validate", "Check all invariant constraints pass — returns passed/failed counts and details for each failure", async () => {
+    const data = await api(config, "/validate");
+    return text(data);
+});
+server.tool("statemap_divergence", "Check for internal consistency issues — orphaned states, missing transitions, broken references", async () => {
+    const data = await api(config, "/divergence");
+    return text(data);
+});
+server.tool("statemap_update_model", "Create or update a data model declaration. Omit id to create, include id to update.", {
+    id: z.string().optional().describe("Model ID — omit to create new, include to update existing"),
+    name: z.string().describe("Model name (e.g. 'User', 'Order')"),
+    layer: z.enum(["database", "application", "ui"]).describe("Where this model lives"),
+    schema: z.object({
+        fields: z.array(z.object({
+            name: z.string(),
+            type: z.string(),
+            nullable: z.boolean().default(false),
+            unique: z.boolean().default(false),
+            default: z.string().optional(),
+            description: z.string().optional(),
+        })),
+    }).describe("Field definitions"),
+    relationships: z.array(z.object({
+        target_model_id: z.string().describe("Target model name or ID"),
+        type: z.enum(["one_to_one", "one_to_many", "many_to_many"]),
+        foreign_key: z.string().optional(),
+        description: z.string().optional(),
+    })).optional().describe("Relationships to other models"),
+}, async ({ id, ...data }) => {
+    if (id) {
+        const result = await api(config, `/models/${id}`, { method: "PUT", body: JSON.stringify(data) });
+        return text(result);
+    }
+    const result = await api(config, "/models", { method: "POST", body: JSON.stringify(data) });
+    return text(result);
+});
+server.tool("statemap_update_container", "Create or update a state container (where state lives). Omit id to create, include id to update.", {
+    id: z.string().optional().describe("Container ID — omit to create, include to update"),
+    name: z.string().describe("Container name (e.g. 'PostgreSQL', 'Redis Cache', 'useAuthStore')"),
+    container_type: z.enum(["database", "cache", "local_state", "url_params", "session", "cookie", "env", "kv", "durable_object", "r2"]).describe("Container type"),
+    models: z.array(z.string()).optional().describe("Model names or IDs stored in this container"),
+    config: z.record(z.unknown()).optional().describe("Optional configuration metadata"),
+}, async ({ id, ...data }) => {
+    if (id) {
+        const result = await api(config, `/containers/${id}`, { method: "PUT", body: JSON.stringify(data) });
+        return text(result);
+    }
+    const result = await api(config, "/containers", { method: "POST", body: JSON.stringify(data) });
+    return text(result);
+});
+server.tool("statemap_update_transition", "Create or update a state transition (mutation). Omit id to create, include id to update.", {
+    id: z.string().optional().describe("Transition ID — omit to create, include to update"),
+    name: z.string().describe("Transition name (e.g. 'CreateOrder', 'UpdateProfile')"),
+    trigger: z.string().describe("What triggers this (e.g. 'api_call', 'user_action', 'cron')"),
+    source_states: z.array(z.string()).describe("Model names read/modified by this transition"),
+    target_states: z.array(z.string()).describe("Model names written/created by this transition"),
+    preconditions: z.array(z.string()).optional().describe("Conditions that must be true before"),
+    postconditions: z.array(z.string()).optional().describe("Conditions guaranteed after"),
+}, async ({ id, ...data }) => {
+    if (id) {
+        const result = await api(config, `/transitions/${id}`, { method: "PUT", body: JSON.stringify(data) });
+        return text(result);
+    }
+    const result = await api(config, "/transitions", { method: "POST", body: JSON.stringify(data) });
+    return text(result);
+});
+server.tool("statemap_add_invariant", "Add a constraint/invariant that the system must satisfy", {
+    name: z.string().describe("Invariant name (e.g. 'UserEmailUnique', 'OrderTotalPositive')"),
+    expression: z.string().describe("Constraint expression (e.g. 'unique(User.email)', 'Order.total >= 0')"),
+    scope: z.array(z.string()).optional().describe("Model names this invariant applies to"),
+    severity: z.enum(["error", "warning", "info"]).default("error").describe("How severe a violation is"),
+}, async (data) => {
+    const result = await api(config, "/invariants", { method: "POST", body: JSON.stringify(data) });
+    return text(result);
+});
+server.tool("statemap_update_read_deps", "Create or update a read dependency (what consumes state). Omit id to create, include id to update.", {
+    id: z.string().optional().describe("Read dep ID — omit to create, include to update"),
+    consumer: z.string().describe("Consumer name (e.g. 'UserProfile', 'checkoutApi', 'useCartStore')"),
+    consumer_type: z.enum(["component", "view", "hook", "function", "api_route", "worker"]).describe("Consumer type"),
+    state_refs: z.array(z.string()).describe("Model names this consumer reads from"),
+}, async ({ id, ...data }) => {
+    if (id) {
+        const result = await api(config, `/read-deps/${id}`, { method: "PUT", body: JSON.stringify(data) });
+        return text(result);
+    }
+    const result = await api(config, "/read-deps", { method: "POST", body: JSON.stringify(data) });
+    return text(result);
+});
+server.tool("statemap_import", "Bulk import entities — for initial project scan. Provide arrays of models, containers, transitions, invariants, and/or read dependencies.", {
+    data_models: z.array(z.record(z.unknown())).optional().describe("Array of model objects to import"),
+    state_containers: z.array(z.record(z.unknown())).optional().describe("Array of container objects to import"),
+    state_transitions: z.array(z.record(z.unknown())).optional().describe("Array of transition objects to import"),
+    invariants: z.array(z.record(z.unknown())).optional().describe("Array of invariant objects to import"),
+    read_dependencies: z.array(z.record(z.unknown())).optional().describe("Array of read dependency objects to import"),
+}, async (data) => {
+    const result = await api(config, "/import", { method: "POST", body: JSON.stringify(data) });
+    return text(result);
+});
+server.tool("statemap_analyze", "Submit source files for codebase analysis and drift detection — compares actual code against declared model", {
+    files: z.array(z.object({
+        path: z.string().describe("File path relative to repo root"),
+        content: z.string().describe("File contents"),
+    })).describe("Source files to analyze (Prisma schemas, TypeScript interfaces, SQL, state stores, etc.)"),
+}, async (data) => {
+    const result = await api(config, "/analyze-and-compare", { method: "POST", body: JSON.stringify(data) });
+    return text(result);
+});
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "statemap-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for Statemap — system state working memory for AI agents",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "statemap-mcp": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "zod": "^3.25.67"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.0",
+    "typescript": "^5.8.3"
+  },
+  "keywords": [
+    "mcp",
+    "statemap",
+    "ai",
+    "agent",
+    "state-management"
+  ],
+  "license": "MIT"
+}