mcp-coordinator 0.1.0 → 0.2.0

package/dist/cli/doctor.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function createDoctorCommand(): Command;

package/dist/cli/doctor.js

@@ -0,0 +1,220 @@
+import { Command } from "commander";
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+import { createConnection } from "net";
+import { request } from "http";
+import { getConfigDir, loadConfig } from "./config.js";
+async function tcpReachable(host, port, timeoutMs = 1500) {
+    return new Promise((resolveP) => {
+        const sock = createConnection({ host, port });
+        const settle = (ok) => {
+            try {
+                sock.destroy();
+            }
+            catch { }
+            resolveP(ok);
+        };
+        sock.setTimeout(timeoutMs, () => settle(false));
+        sock.on("connect", () => settle(true));
+        sock.on("error", () => settle(false));
+    });
+}
+async function httpGet(host, port, path, timeoutMs = 1500) {
+    return new Promise((resolveP) => {
+        const req = request({ host, port, path, method: "GET", timeout: timeoutMs }, (res) => {
+            const chunks = [];
+            res.on("data", (c) => chunks.push(c));
+            res.on("end", () => {
+                resolveP({ status: res.statusCode ?? 0, body: Buffer.concat(chunks).toString("utf-8").slice(0, 200) });
+            });
+        });
+        req.on("timeout", () => {
+            req.destroy();
+            resolveP(null);
+        });
+        req.on("error", () => resolveP(null));
+        req.end();
+    });
+}
+async function mcpInitialize(host, port, timeoutMs = 2500) {
+    return new Promise((resolveP) => {
+        const payload = JSON.stringify({
+            jsonrpc: "2.0",
+            id: 1,
+            method: "initialize",
+            params: {
+                protocolVersion: "2024-11-05",
+                capabilities: {},
+                clientInfo: { name: "mcp-coordinator-doctor", version: "1.0.0" },
+            },
+        });
+        const req = request({
+            host,
+            port,
+            path: "/mcp",
+            method: "POST",
+            timeout: timeoutMs,
+            headers: {
+                "Content-Type": "application/json",
+                "Accept": "application/json, text/event-stream",
+                "Content-Length": Buffer.byteLength(payload).toString(),
+            },
+        }, (res) => {
+            const chunks = [];
+            res.on("data", (c) => chunks.push(c));
+            res.on("end", () => {
+                const body = Buffer.concat(chunks).toString("utf-8");
+                // streaming MCP responses prefix with `data: { ... }`
+                resolveP(res.statusCode === 200 && body.includes('"protocolVersion"'));
+            });
+        });
+        req.on("timeout", () => {
+            req.destroy();
+            resolveP(false);
+        });
+        req.on("error", () => resolveP(false));
+        req.write(payload);
+        req.end();
+    });
+}
+export function createDoctorCommand() {
+    return new Command("doctor")
+        .description("Run a health check: config, server liveness, MCP endpoint, MQTT broker, dashboard")
+        .option("--host <host>", "Hostname to probe", "127.0.0.1")
+        .option("--port <port>", "HTTP port", "")
+        .option("--mqtt-port <port>", "MQTT TCP port", "")
+        .action(async (opts) => {
+        const results = [];
+        const host = opts.host;
+        // 1. Config dir
+        const configDir = getConfigDir();
+        results.push({
+            name: "config-dir",
+            ok: existsSync(configDir),
+            detail: existsSync(configDir) ? configDir : `missing — run 'mcp-coordinator init'`,
+            hint: existsSync(configDir) ? undefined : "Run: mcp-coordinator init",
+        });
+        // 2. config.json
+        const configFile = join(configDir, "config.json");
+        let parsedConfig = null;
+        if (existsSync(configFile)) {
+            try {
+                parsedConfig = loadConfig();
+                results.push({
+                    name: "config.json",
+                    ok: true,
+                    detail: `valid — port ${parsedConfig.server.port}, data_dir ${parsedConfig.server.data_dir}`,
+                });
+            }
+            catch (e) {
+                results.push({
+                    name: "config.json",
+                    ok: false,
+                    detail: `invalid: ${e.message}`,
+                    hint: "Re-run 'mcp-coordinator init' to restore defaults",
+                });
+            }
+        }
+        else {
+            results.push({
+                name: "config.json",
+                ok: false,
+                detail: "missing — defaults will be used",
+                hint: "Run: mcp-coordinator init",
+            });
+        }
+        const port = parseInt(opts.port || String(parsedConfig?.server.port ?? 3100), 10);
+        const mqttPort = parseInt(opts.mqttPort || process.env.COORDINATOR_MQTT_TCP_PORT || "1883", 10);
+        // 3. Server PID file
+        const pidPath = join(configDir, "server.pid");
+        let pidFromFile = null;
+        if (existsSync(pidPath)) {
+            try {
+                pidFromFile = parseInt(readFileSync(pidPath, "utf-8").trim(), 10);
+                results.push({
+                    name: "pid-file",
+                    ok: !isNaN(pidFromFile) && pidFromFile > 0,
+                    detail: `PID ${pidFromFile} (this is just the PID file; check 'tcp-${port}' below to confirm the server is actually listening)`,
+                });
+            }
+            catch {
+                results.push({
+                    name: "pid-file",
+                    ok: false,
+                    detail: "exists but unreadable",
+                    hint: "Stale state — run 'mcp-coordinator server stop' or delete ~/.mcp-coordinator/server.pid",
+                });
+            }
+        }
+        else {
+            results.push({
+                name: "pid-file",
+                ok: false,
+                detail: "absent (server not running in daemon mode)",
+                hint: "Start the server: mcp-coordinator server start --daemon",
+            });
+        }
+        // 4. HTTP TCP reachable
+        const httpUp = await tcpReachable(host, port);
+        results.push({
+            name: `tcp-${port}`,
+            ok: httpUp,
+            detail: httpUp ? `${host}:${port} accepts connections` : `${host}:${port} unreachable`,
+            hint: httpUp ? undefined : `Start the server: mcp-coordinator server start --daemon (or check the configured port)`,
+        });
+        // 5. /health endpoint
+        if (httpUp) {
+            const health = await httpGet(host, port, "/health");
+            results.push({
+                name: "/health",
+                ok: !!health && health.status === 200,
+                detail: health ? `HTTP ${health.status}: ${health.body}` : "no response",
+                hint: !!health && health.status === 200 ? undefined : "Server is reachable but /health failed; check server logs",
+            });
+            // 6. /mcp initialize
+            const mcpOk = await mcpInitialize(host, port);
+            results.push({
+                name: "/mcp initialize",
+                ok: mcpOk,
+                detail: mcpOk ? "JSON-RPC 2.0 initialize succeeded" : "no valid MCP response",
+                hint: mcpOk ? undefined : "MCP HTTP transport not responding; check server logs and version compatibility",
+            });
+            // 7. Dashboard
+            const dash = await httpGet(host, port, "/dashboard/");
+            results.push({
+                name: "/dashboard",
+                ok: !!dash && dash.status === 200,
+                detail: dash ? `HTTP ${dash.status}` : "no response",
+                hint: !!dash && dash.status === 200 ? undefined : "Dashboard files not found; verify package install or rerun init",
+            });
+        }
+        // 8. MQTT broker
+        const mqttUp = await tcpReachable(host, mqttPort);
+        results.push({
+            name: `mqtt-${mqttPort}`,
+            ok: mqttUp,
+            detail: mqttUp ? `${host}:${mqttPort} accepts connections` : `${host}:${mqttPort} unreachable`,
+            hint: mqttUp ? undefined : `MQTT broker not listening on port ${mqttPort}; check COORDINATOR_MQTT_TCP_PORT and server logs`,
+        });
+        // Print
+        let allOk = true;
+        console.log("");
+        for (const r of results) {
+            const prefix = r.ok ? "[ OK ]" : "[FAIL]";
+            console.log(`${prefix}  ${r.name.padEnd(20)} ${r.detail}`);
+            if (!r.ok) {
+                allOk = false;
+                if (r.hint)
+                    console.log(`        hint: ${r.hint}`);
+            }
+        }
+        console.log("");
+        if (allOk) {
+            console.log("All checks passed. Coordinator is healthy.");
+        }
+        else {
+            console.log("Some checks failed. See hints above.");
+            process.exit(1);
+        }
+    });
+}

package/dist/cli/index.js

@@ -2,12 +2,18 @@
 import { Command } from "commander";
 import { createServerProgram } from "./server/index.js";
 import { createDashboardCommand } from "./dashboard.js";
+import { createInitCommand } from "./init.js";
+import { createDoctorCommand } from "./doctor.js";
+import { createUninstallCommand } from "./uninstall.js";
 import { getVersion } from "./version.js";
 const program = new Command();
 program
     .name("mcp-coordinator")
     .description("Embedded MQTT broker + MCP server for multi-agent coordination")
     .version(getVersion());
+program.addCommand(createInitCommand());
 program.addCommand(createServerProgram());
 program.addCommand(createDashboardCommand());
+program.addCommand(createDoctorCommand());
+program.addCommand(createUninstallCommand());
 program.parse();

package/dist/cli/init.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function createInitCommand(): Command;

package/dist/cli/init.js

@@ -0,0 +1,199 @@
+import { Command } from "commander";
+import { writeFileSync, existsSync, readFileSync, statSync } from "fs";
+import { join, resolve } from "path";
+import { ensureConfigDir, loadConfig, saveConfig } from "./config.js";
+const CLAUDE_MD_TEMPLATE = `## Coordination via mcp-coordinator
+
+You share a coordinator with other Claude Code sessions on this repo. Use the
+\`coordinator\` MCP tools to announce work and resolve conflicts before writing
+code.
+
+### How coordination flows (important — read first)
+
+You communicate with the coordinator over MCP (request/response). You do NOT
+receive automatic push notifications. To stay aware of what other agents are
+doing, you must **poll** at the right moments:
+
+- **Session start** — call \`register_agent\` once.
+- **Before any source-file change** — call \`announce_work\`. The response tells
+  you immediately if a thread was opened (conflict detected). If yes, react.
+- **Before resuming work after a non-trivial pause** (e.g., before a new
+  feature, between phases, after returning from a sub-task) — call
+  \`coordinator_status\` to see if anyone has posted to threads you're a
+  participant in. New posts may need your reply or vote.
+- **Anytime you suspect activity** — call \`list_threads\` or
+  \`coordinator_status\` to scan for open threads.
+
+If you skip the polling step, you can still write code, but you may miss a
+question another agent posted on a thread you opened. The dashboard
+(\`http://localhost:3100/dashboard\`) is the human's view of all activity if
+you want a quick visual.
+
+### Before any source-file change
+
+1. (Once per session) Call \`register_agent\` with your name and the modules
+   you plan to touch.
+2. Call \`announce_work\` with:
+   - \`subject\`: short description of the change
+   - \`target_files\`: files you will modify
+   - \`depends_on_files\` (optional): files whose interface you depend on
+   - \`target_modules\`: bounded contexts you'll touch
+3. **Read the response carefully**. If \`thread_id\` is present, a conflict
+   was detected — DO NOT proceed to code. Instead:
+   - Call \`get_thread(thread_id)\` to see what other agents have said.
+   - Call \`post_to_thread\` with \`type: "context"\` to share your plan and
+     constraints.
+   - Wait for the other agent to acknowledge. Poll \`get_thread_updates\` or
+     \`coordinator_status\` until the thread reaches \`resolving\`.
+   - When a resolution is proposed, call \`approve_resolution\` or
+     \`contest_resolution\` (with reason).
+   - Only proceed to code once the thread is \`resolved\`.
+4. After completing a meaningful change, call \`log_action_summary\` to update
+   the dashboard timeline.
+
+### Polling for thread updates (the most-missed step)
+
+Whenever you've opened a thread or are a participant in one, the other agents
+may post new context. They cannot push to you — you must check. A reasonable
+cadence:
+
+- **Whenever you call any other coordinator tool** (announce_work,
+  log_action_summary, etc.), spend one extra call on
+  \`coordinator_status\` and scan for open threads where the latest message is
+  from someone else.
+- **Before each major task transition** (finishing one feature, starting the
+  next), call \`list_threads\` or \`coordinator_status\` once.
+
+A useful pattern: after every 3-5 file edits, run
+\`coordinator_status\` once to confirm no thread you opened is still waiting on
+your input.
+
+### Tools you'll reach for most
+
+- \`coordinator_status\` — full system snapshot (agents, threads, files, quota)
+- \`announce_work\` / \`post_to_thread\` / \`approve_resolution\` /
+  \`contest_resolution\` — consultation flow
+- \`get_thread_updates\` — fetch only new posts since a timestamp
+- \`hot_files\` — files multiple agents are editing
+- \`check_file_conflict\` — quick check before opening a file
+
+If you want push-based coordination (real-time interrupts between agent
+turns instead of polling), see [essaim](https://github.com/swoofer/essaim) —
+it ships an agent-loop wrapper that subscribes to the coordinator's MQTT
+broker and injects events into your turn flow automatically.
+`;
+export function createInitCommand() {
+    return new Command("init")
+        .description("First-time setup: create the config dir, write a default config.json, and print a .mcp.json snippet for your MCP client")
+        .option("--url <url>", "Coordinator URL to use in the printed .mcp.json snippet (defaults to http://localhost:<port>/mcp)")
+        .option("--write-mcp-config <path>", "Write the .mcp.json snippet into <path>/.mcp.json (merges if the file already exists). <path> must be an existing directory.")
+        .option("--write-claude-md <path>", "Write a sample CLAUDE.md (system instructions for your coordinator-aware agent) into <path>/CLAUDE.md (merges with existing — appends a clearly-marked section). <path> must be an existing directory.")
+        .action((opts) => {
+        const dir = ensureConfigDir();
+        console.log(`Config directory: ${dir}`);
+        const configPath = join(dir, "config.json");
+        if (!existsSync(configPath)) {
+            saveConfig(loadConfig());
+            console.log(`Wrote default config:    ${configPath}`);
+        }
+        else {
+            console.log(`Config already exists:   ${configPath} (untouched)`);
+        }
+        const config = loadConfig();
+        const url = opts.url ?? `http://localhost:${config.server.port}/mcp`;
+        const snippet = {
+            mcpServers: {
+                coordinator: {
+                    type: "http",
+                    url,
+                },
+            },
+        };
+        const validateDir = (p, label) => {
+            const abs = resolve(p);
+            if (!existsSync(abs)) {
+                console.error(`Error: ${label} path ${abs} does not exist.`);
+                return null;
+            }
+            const st = statSync(abs);
+            if (!st.isDirectory()) {
+                console.error(`Error: ${label} path ${abs} is not a directory.`);
+                return null;
+            }
+            return abs;
+        };
+        let exitCode = 0;
+        if (opts.writeMcpConfig) {
+            const dirAbs = validateDir(opts.writeMcpConfig, "--write-mcp-config");
+            if (!dirAbs) {
+                exitCode = 1;
+            }
+            else {
+                const target = resolve(dirAbs, ".mcp.json");
+                let merged = snippet;
+                if (existsSync(target)) {
+                    try {
+                        const existing = JSON.parse(readFileSync(target, "utf-8"));
+                        merged = {
+                            ...existing,
+                            mcpServers: {
+                                ...(existing.mcpServers ?? {}),
+                                coordinator: snippet.mcpServers.coordinator,
+                            },
+                        };
+                    }
+                    catch {
+                        console.warn(`Warning: ${target} is not valid JSON; overwriting`);
+                    }
+                }
+                writeFileSync(target, JSON.stringify(merged, null, 2) + "\n");
+                console.log(`Wrote MCP config:        ${target}`);
+            }
+        }
+        if (opts.writeClaudeMd) {
+            const dirAbs = validateDir(opts.writeClaudeMd, "--write-claude-md");
+            if (!dirAbs) {
+                exitCode = 1;
+            }
+            else {
+                const target = resolve(dirAbs, "CLAUDE.md");
+                const SENTINEL = "<!-- mcp-coordinator:coordination-section -->";
+                const sectionBody = SENTINEL + "\n" + CLAUDE_MD_TEMPLATE + SENTINEL + "\n";
+                let final;
+                if (existsSync(target)) {
+                    const existing = readFileSync(target, "utf-8");
+                    if (existing.includes(SENTINEL)) {
+                        const re = new RegExp(`${SENTINEL}[\\s\\S]*?${SENTINEL}\\n?`, "g");
+                        final = existing.replace(re, sectionBody);
+                        console.log(`Updated CLAUDE.md (replaced existing coordinator section): ${target}`);
+                    }
+                    else {
+                        const sep = existing.endsWith("\n") ? "\n" : "\n\n";
+                        final = existing + sep + sectionBody;
+                        console.log(`Appended coordinator section to CLAUDE.md: ${target}`);
+                    }
+                }
+                else {
+                    final = "# CLAUDE.md\n\n" + sectionBody;
+                    console.log(`Wrote CLAUDE.md:         ${target}`);
+                }
+                writeFileSync(target, final);
+            }
+        }
+        if (!opts.writeMcpConfig && !opts.writeClaudeMd) {
+            console.log("");
+            console.log("Add this to your MCP client (e.g., ~/.claude/.mcp.json):");
+            console.log("");
+            console.log(JSON.stringify(snippet, null, 2));
+        }
+        console.log("");
+        console.log("Next steps:");
+        console.log("  1. Start the coordinator:  mcp-coordinator server start --daemon");
+        console.log("  2. Open the dashboard:     mcp-coordinator dashboard");
+        console.log("  3. Connect any MCP client (Claude Code, Cursor, Cline, ...) using the snippet above");
+        console.log("  4. Health check:           mcp-coordinator doctor");
+        if (exitCode !== 0) {
+            process.exit(exitCode);
+        }
+    });
+}

package/dist/cli/server/index.js

@@ -2,10 +2,12 @@ import { Command } from "commander";
 import { createServerStartCommand } from "./start.js";
 import { createServerStopCommand } from "./stop.js";
 import { createServerStatusCommand } from "./status.js";
+import { createServerLogsCommand } from "./logs.js";
 export function createServerProgram() {
     const server = new Command("server").description("Manage the coordination server");
     server.addCommand(createServerStartCommand());
     server.addCommand(createServerStopCommand());
     server.addCommand(createServerStatusCommand());
+    server.addCommand(createServerLogsCommand());
     return server;
 }

package/dist/cli/server/logs.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function createServerLogsCommand(): Command;

package/dist/cli/server/logs.js

@@ -0,0 +1,83 @@
+import { Command } from "commander";
+import { existsSync, statSync, openSync, readSync, closeSync, watchFile, unwatchFile } from "fs";
+import { join } from "path";
+import { getConfigDir } from "../config.js";
+export function createServerLogsCommand() {
+    return new Command("logs")
+        .description("Tail the daemon server log at ~/.mcp-coordinator/logs/server.log")
+        .option("-n, --lines <n>", "Print the last N lines and exit (default: 50)", "50")
+        .option("-f, --follow", "After printing the tail, follow the file for new lines")
+        .action((opts) => {
+        const logPath = join(getConfigDir(), "logs", "server.log");
+        if (!existsSync(logPath)) {
+            console.error(`No log file at ${logPath}.`);
+            console.error("The server has never been started in daemon mode (foreground runs print to stdout).");
+            console.error("Start a daemon: mcp-coordinator server start --daemon");
+            process.exit(1);
+        }
+        const n = Math.max(1, parseInt(opts.lines, 10) || 50);
+        // Print the last N lines by reading from the end of the file in chunks.
+        const fd = openSync(logPath, "r");
+        try {
+            const size = statSync(logPath).size;
+            const chunkSize = 65536;
+            let pos = size;
+            let collected = "";
+            let newlines = 0;
+            while (pos > 0 && newlines <= n) {
+                const readLen = Math.min(chunkSize, pos);
+                pos -= readLen;
+                const buf = Buffer.alloc(readLen);
+                readSync(fd, buf, 0, readLen, pos);
+                const piece = buf.toString("utf-8");
+                collected = piece + collected;
+                newlines = (collected.match(/\n/g) ?? []).length;
+            }
+            const lines = collected.split("\n");
+            const tail = lines.slice(Math.max(0, lines.length - n - 1));
+            process.stdout.write(tail.join("\n"));
+            if (!collected.endsWith("\n"))
+                process.stdout.write("\n");
+        }
+        finally {
+            closeSync(fd);
+        }
+        if (!opts.follow)
+            return;
+        // Follow mode: poll the file for size changes and print appended bytes.
+        let lastSize = statSync(logPath).size;
+        const onChange = () => {
+            try {
+                const cur = statSync(logPath).size;
+                if (cur < lastSize) {
+                    // file truncated/rotated — reset
+                    lastSize = 0;
+                }
+                if (cur > lastSize) {
+                    const fd2 = openSync(logPath, "r");
+                    try {
+                        const buf = Buffer.alloc(cur - lastSize);
+                        readSync(fd2, buf, 0, buf.length, lastSize);
+                        process.stdout.write(buf.toString("utf-8"));
+                        lastSize = cur;
+                    }
+                    finally {
+                        closeSync(fd2);
+                    }
+                }
+            }
+            catch {
+                // ignore transient errors during rotation
+            }
+        };
+        console.log("");
+        console.log("[following — Ctrl+C to stop]");
+        watchFile(logPath, { interval: 500 }, onChange);
+        const cleanup = () => {
+            unwatchFile(logPath, onChange);
+            process.exit(0);
+        };
+        process.on("SIGINT", cleanup);
+        process.on("SIGTERM", cleanup);
+    });
+}

package/dist/cli/uninstall.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function createUninstallCommand(): Command;