@spencerbeggs/claude-coordinator-mcp 0.1.0

package/433.js

@@ -0,0 +1,403 @@
+import { AnswerInputSchema, AskInputSchema, DEFAULT_URL, GetContextInputSchema, JoinInputSchema, ListContextInputSchema, LogDecisionInputSchema, ShareContextInputSchema } from "@spencerbeggs/claude-coordinator-core";
+import { createTRPCClient, createWSClient, wsLink } from "@trpc/client";
+import ws from "ws";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+function createCoordinatorClient(options = {}) {
+    const url = options.url ?? DEFAULT_URL;
+    const wsClient = createWSClient({
+        url,
+        WebSocket: ws
+    });
+    const trpc = createTRPCClient({
+        links: [
+            wsLink({
+                client: wsClient
+            })
+        ]
+    });
+    const close = ()=>{
+        wsClient.close();
+    };
+    return {
+        trpc,
+        close
+    };
+}
+function formatConnectionError(error, url) {
+    const errorStr = String(error);
+    if (errorStr.includes("ECONNREFUSED") || errorStr.includes("ENOTFOUND") || errorStr.includes("WebSocket") || errorStr.includes("connect")) return `Could not connect to coordinator server at ${url}. Please start the server with: npx @spencerbeggs/claude-coordinator-server`;
+    return errorStr;
+}
+async function createMcpServer(options = {}) {
+    const serverUrl = options.url ?? DEFAULT_URL;
+    let client = null;
+    let agentId = null;
+    const server = new McpServer({
+        name: "claude-coordinator",
+        version: "0.1.0"
+    });
+    const getClient = ()=>{
+        if (!client) client = createCoordinatorClient({
+            url: serverUrl
+        });
+        return client;
+    };
+    const formatError = (error)=>formatConnectionError(error, serverUrl);
+    const requireAgentId = ()=>{
+        if (!agentId) throw new Error("Not joined to session. Call coordinator_join first.");
+        return agentId;
+    };
+    server.tool("coordinator_join", "Join the coordination session as an agent", JoinInputSchema.shape, async (params)=>{
+        try {
+            const result = await getClient().trpc.session.join.mutate(params);
+            agentId = result.agent.id;
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            success: true,
+                            agent: result.agent,
+                            sessionId: result.sessionId
+                        })
+                    }
+                ]
+            };
+        } catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            success: false,
+                            error: formatError(error)
+                        })
+                    }
+                ],
+                isError: true
+            };
+        }
+    });
+    server.tool("coordinator_leave", "Leave the coordination session", {}, async ()=>{
+        try {
+            const id = requireAgentId();
+            const result = await getClient().trpc.session.leave.mutate({
+                agentId: id
+            });
+            if (result.success) agentId = null;
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            success: result.success
+                        })
+                    }
+                ]
+            };
+        } catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            success: false,
+                            error: formatError(error)
+                        })
+                    }
+                ],
+                isError: true
+            };
+        }
+    });
+    server.tool("coordinator_list_agents", "List all connected agents in the session", {}, async ()=>{
+        try {
+            const agents = await getClient().trpc.session.list.query();
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            success: true,
+                            agents
+                        })
+                    }
+                ]
+            };
+        } catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            success: false,
+                            error: formatError(error)
+                        })
+                    }
+                ],
+                isError: true
+            };
+        }
+    });
+    server.tool("coordinator_share_context", "Share a context entry with other agents", ShareContextInputSchema.shape, async (params)=>{
+        try {
+            const id = requireAgentId();
+            const entry = await getClient().trpc.context.share.mutate({
+                ...params,
+                agentId: id
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            success: true,
+                            entry
+                        })
+                    }
+                ]
+            };
+        } catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            success: false,
+                            error: formatError(error)
+                        })
+                    }
+                ],
+                isError: true
+            };
+        }
+    });
+    server.tool("coordinator_get_context", "Get a context entry by key", GetContextInputSchema.shape, async (params)=>{
+        try {
+            const entry = await getClient().trpc.context.get.query(params);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            success: true,
+                            entry
+                        })
+                    }
+                ]
+            };
+        } catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            success: false,
+                            error: formatError(error)
+                        })
+                    }
+                ],
+                isError: true
+            };
+        }
+    });
+    server.tool("coordinator_list_context", "List context entries with optional filters", {
+        ...ListContextInputSchema.shape
+    }, async (params)=>{
+        try {
+            const entries = await getClient().trpc.context.list.query(params);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            success: true,
+                            entries
+                        })
+                    }
+                ]
+            };
+        } catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            success: false,
+                            error: formatError(error)
+                        })
+                    }
+                ],
+                isError: true
+            };
+        }
+    });
+    server.tool("coordinator_ask", "Ask a question to other agents", AskInputSchema.shape, async (params)=>{
+        try {
+            const id = requireAgentId();
+            const question = await getClient().trpc.questions.ask.mutate({
+                ...params,
+                agentId: id
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            success: true,
+                            question
+                        })
+                    }
+                ]
+            };
+        } catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            success: false,
+                            error: formatError(error)
+                        })
+                    }
+                ],
+                isError: true
+            };
+        }
+    });
+    server.tool("coordinator_answer", "Answer a pending question", AnswerInputSchema.shape, async (params)=>{
+        try {
+            const id = requireAgentId();
+            const question = await getClient().trpc.questions.answer.mutate({
+                ...params,
+                agentId: id
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            success: true,
+                            question
+                        })
+                    }
+                ]
+            };
+        } catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            success: false,
+                            error: formatError(error)
+                        })
+                    }
+                ],
+                isError: true
+            };
+        }
+    });
+    server.tool("coordinator_pending_questions", "List pending questions (optionally for a specific agent)", {
+        agentId: z.string().uuid().optional().describe("Filter questions directed to this agent")
+    }, async (params)=>{
+        try {
+            const questions = await getClient().trpc.questions.listPending.query(params);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            success: true,
+                            questions
+                        })
+                    }
+                ]
+            };
+        } catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            success: false,
+                            error: formatError(error)
+                        })
+                    }
+                ],
+                isError: true
+            };
+        }
+    });
+    server.tool("coordinator_log_decision", "Log a decision made during the session", LogDecisionInputSchema.shape, async (params)=>{
+        try {
+            const id = requireAgentId();
+            const decision = await getClient().trpc.decisions.log.mutate({
+                ...params,
+                agentId: id
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            success: true,
+                            decision
+                        })
+                    }
+                ]
+            };
+        } catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            success: false,
+                            error: formatError(error)
+                        })
+                    }
+                ],
+                isError: true
+            };
+        }
+    });
+    server.tool("coordinator_list_decisions", "List all decisions made during the session", {}, async ()=>{
+        try {
+            const decisions = await getClient().trpc.decisions.list.query();
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            success: true,
+                            decisions
+                        })
+                    }
+                ]
+            };
+        } catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            success: false,
+                            error: formatError(error)
+                        })
+                    }
+                ],
+                isError: true
+            };
+        }
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("[coordinator-mcp] MCP server started");
+    process.on("exit", ()=>{
+        if (client) client.close();
+    });
+}
+export { DEFAULT_URL, createCoordinatorClient, createMcpServer };

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 C. Spencer Beggs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,138 @@
+# @spencerbeggs/claude-coordinator-mcp
+
+MCP stdio bridge that exposes coordination tools to Claude Code instances,
+enabling them to communicate through the coordinator server.
+
+## Features
+
+- **MCP tool integration** - Expose coordination as Claude Code tools
+- **stdio transport** - Standard MCP communication protocol
+- **Lazy connection** - Connect to server only when needed
+- **Consistent responses** - All tools return predictable JSON format
+
+## Installation
+
+```bash
+npm install @spencerbeggs/claude-coordinator-mcp
+```
+
+## Quick Start
+
+### Configure in Claude Code
+
+Add to your Claude Code MCP settings:
+
+```json
+{
+  "mcpServers": {
+    "claude-coordinator": {
+      "command": "npx",
+      "args": ["@spencerbeggs/claude-coordinator-mcp"]
+    }
+  }
+}
+```
+
+With a custom server URL:
+
+```json
+{
+  "mcpServers": {
+    "claude-coordinator": {
+      "command": "npx",
+      "args": [
+        "@spencerbeggs/claude-coordinator-mcp",
+        "--url=ws://192.168.1.100:3030"
+      ]
+    }
+  }
+}
+```
+
+### Run Standalone
+
+```bash
+# Default URL (ws://localhost:3030)
+npx @spencerbeggs/claude-coordinator-mcp
+
+# Custom URL
+npx @spencerbeggs/claude-coordinator-mcp --url=ws://server:3030
+```
+
+## Available Tools
+
+Once configured, Claude Code can use these tools:
+
+### Session Tools
+
+| Tool | Parameters | Description |
+| ---- | ---------- | ----------- |
+| `coordinator_join` | name, role, repoPath | Join session as agent |
+| `coordinator_leave` | (none) | Leave current session |
+| `coordinator_list_agents` | (none) | List connected agents |
+
+### Context Tools
+
+| Tool | Parameters | Description |
+| ---- | ---------- | ----------- |
+| `coordinator_share_context` | key, value, tags? | Share context entry |
+| `coordinator_get_context` | key | Get context by key |
+| `coordinator_list_context` | tags?, createdBy? | List context entries |
+
+### Question Tools
+
+| Tool | Parameters | Description |
+| ---- | ---------- | ----------- |
+| `coordinator_ask` | question, to? | Ask a question |
+| `coordinator_answer` | questionId, answer | Answer a question |
+| `coordinator_pending_questions` | agentId? | List pending questions |
+
+### Decision Tools
+
+| Tool | Parameters | Description |
+| ---- | ---------- | ----------- |
+| `coordinator_log_decision` | decision, rationale? | Log a decision |
+| `coordinator_list_decisions` | (none) | List all decisions |
+
+## Usage Example
+
+Once configured, Claude Code can coordinate with other instances:
+
+```text
+User: "Join the coordinator as a source agent"
+
+Claude: I'll join the coordination session.
+[Uses coordinator_join tool with role="source"]
+
+User: "Share that we're using React 18"
+
+Claude: I'll share that context.
+[Uses coordinator_share_context with key="framework" value="React 18"]
+
+User: "Ask the other agent what testing framework they prefer"
+
+Claude: I'll ask the question.
+[Uses coordinator_ask with question="What testing framework do you prefer?"]
+```
+
+## Response Format
+
+All tools return JSON with consistent structure:
+
+```json
+// Success
+{ "success": true, "agent": {...}, "sessionId": "..." }
+
+// Error
+{ "success": false, "error": "Error description" }
+```
+
+## Documentation
+
+- [Architecture Design Doc](../../.claude/design/claude-coordinator-mcp/architecture.md)
+- [Core Schemas Package](../claude-coordinator-core/README.md)
+- [Server Package](../claude-coordinator-server/README.md)
+
+## License
+
+MIT

package/bin/claude-coordinator-mcp.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+import { DEFAULT_URL, createMcpServer } from "../433.js";
+const args = process.argv.slice(2);
+let url = DEFAULT_URL;
+for(let i = 0; i < args.length; i++){
+    const arg = args[i];
+    if ("--url" === arg && args[i + 1]) {
+        url = args[i + 1];
+        i++;
+    } else if (arg?.startsWith("--url=")) url = arg.slice(6);
+}
+console.error(`[coordinator-mcp] Connecting to coordinator at ${url}`);
+createMcpServer({
+    url: url
+}).catch((error)=>{
+    console.error("[coordinator-mcp] Failed to start:", error);
+    process.exit(1);
+});

package/index.d.ts

@@ -0,0 +1,126 @@
+/**
+ * \@spencerbeggs/claude-coordinator-mcp
+ *
+ * MCP stdio bridge for the Claude Coordinator system.
+ * Provides MCP tools that Claude Code can use to communicate
+ * with other Claude Code instances through the coordinator server.
+ *
+ * @packageDocumentation
+ */
+
+import type { Agent } from '@spencerbeggs/claude-coordinator-core';
+import type { ContextEntry } from '@spencerbeggs/claude-coordinator-core';
+import type { Decision } from '@spencerbeggs/claude-coordinator-core';
+import type { JoinInput } from '@spencerbeggs/claude-coordinator-core';
+import type { JoinResult } from '@spencerbeggs/claude-coordinator-core';
+import type { Question } from '@spencerbeggs/claude-coordinator-core';
+
+/**
+ * Options for creating the coordinator client
+ */
+export declare interface ClientOptions {
+    url?: string;
+}
+
+/**
+ * Coordinator client instance
+ */
+export declare interface CoordinatorClient {
+    trpc: TypedTRPCClient;
+    close: () => void;
+}
+
+/**
+ * Create a tRPC client that connects to the coordinator server
+ */
+export declare function createCoordinatorClient(options?: ClientOptions): CoordinatorClient;
+
+/**
+ * Create and run the MCP server
+ */
+export declare function createMcpServer(options?: McpServerOptions): Promise<void>;
+
+/**
+ * MCP server options
+ */
+export declare interface McpServerOptions {
+    url?: string;
+}
+
+/**
+ * Typed tRPC client interface matching the coordinator server's router
+ * This provides type safety without requiring cross-package type inference
+ */
+declare interface TypedTRPCClient {
+    session: {
+        join: {
+            mutate: (input: JoinInput) => Promise<JoinResult>;
+        };
+        leave: {
+            mutate: (input: {
+                agentId: string;
+            }) => Promise<{
+                success: boolean;
+            }>;
+        };
+        list: {
+            query: () => Promise<Agent[]>;
+        };
+    };
+    context: {
+        share: {
+            mutate: (input: {
+                key: string;
+                value: string;
+                tags?: string[];
+                agentId: string;
+            }) => Promise<ContextEntry>;
+        };
+        get: {
+            query: (input: {
+                key: string;
+            }) => Promise<ContextEntry | null>;
+        };
+        list: {
+            query: (input?: {
+                prefix?: string;
+                tags?: string[];
+            }) => Promise<ContextEntry[]>;
+        };
+    };
+    questions: {
+        ask: {
+            mutate: (input: {
+                question: string;
+                to?: string;
+                agentId: string;
+            }) => Promise<Question>;
+        };
+        answer: {
+            mutate: (input: {
+                questionId: string;
+                answer: string;
+                agentId: string;
+            }) => Promise<Question>;
+        };
+        listPending: {
+            query: (input?: {
+                agentId?: string;
+            }) => Promise<Question[]>;
+        };
+    };
+    decisions: {
+        log: {
+            mutate: (input: {
+                decision: string;
+                rationale?: string;
+                agentId: string;
+            }) => Promise<Decision>;
+        };
+        list: {
+            query: () => Promise<Decision[]>;
+        };
+    };
+}
+
+export { }

package/index.js

@@ -0,0 +1 @@
+export { createCoordinatorClient, createMcpServer } from "./433.js";

package/package.json

@@ -0,0 +1,54 @@
+{
+	"name": "@spencerbeggs/claude-coordinator-mcp",
+	"version": "0.1.0",
+	"private": false,
+	"description": "MCP stdio bridge for Claude Coordinator",
+	"keywords": [
+		"claude",
+		"coordinator",
+		"mcp",
+		"model-context-protocol"
+	],
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/spencerbeggs/claude-design-coordinator.git",
+		"directory": "pkgs/claude-coordinator-mcp"
+	},
+	"license": "MIT",
+	"author": {
+		"name": "C. Spencer Beggs",
+		"email": "spencer@beggs.codes",
+		"url": "https://spencerbeg.gs"
+	},
+	"type": "module",
+	"exports": {
+		".": {
+			"types": "./index.d.ts",
+			"import": "./index.js"
+		}
+	},
+	"bin": {
+		"claude-coordinator-mcp": "./bin/claude-coordinator-mcp.js"
+	},
+	"dependencies": {
+		"@modelcontextprotocol/sdk": "^1.25.3",
+		"@spencerbeggs/claude-coordinator-core": "0.1.0",
+		"@spencerbeggs/claude-coordinator-server": "0.1.0",
+		"@trpc/client": "^11.8.1",
+		"@trpc/server": "^11.8.1",
+		"ws": "^8.19.0",
+		"zod": "^4.3.5"
+	},
+	"engines": {
+		"node": ">=20.0.0"
+	},
+	"files": [
+		"433.js",
+		"LICENSE",
+		"README.md",
+		"bin/claude-coordinator-mcp.js",
+		"index.d.ts",
+		"index.js",
+		"package.json"
+	]
+}