@mclawnet/mcp-server 0.1.2 → 0.1.4

package/README.md

@@ -0,0 +1,44 @@
+# @mclawnet/mcp-server
+
+MCP server exposing ClawNet capabilities (skills, memory, evolution, tasks,
+inbox) to any Model Context Protocol client.
+
+The binary `clawnet-mcp` is registered in `package.json#bin` and launched by
+the agent host (or any external MCP client).
+
+## Tool groups
+
+- **Skill** — discover and execute skills from the local skill manager.
+- **Memory** — read/write the agent memory store.
+- **Evolution** — skill evolution telemetry helpers.
+- **Task & Inbox** — first-class task graph + inter-instance messaging
+  (added in 0.1.4, see below).
+
+## Task & Inbox tools
+
+Backed by `@mclawnet/task`. All tools are project-scoped via a required
+`workDir` argument (absolute path to the project working directory). See
+the design doc `docs/plans/2026-04-25-task-as-first-class-design.md`.
+
+| Tool | Description |
+| --- | --- |
+| `task_create` | Create a task in the project task store. |
+| `task_get` | Fetch a task by id. |
+| `task_list` | List tasks with optional `swarmId` / `status` / `owner` filters. |
+| `task_set_status` | Update status; cancel auto-unlinks edges and fans out inbox notifications to downstream owners. |
+| `task_set_owner` | Set or clear (`null`) the owner instance id. |
+| `task_add_comment` | Append an idempotent comment (auto-uuid if `id` omitted). |
+| `task_link` | Add a `blockedBy` / `blocks` edge; rejects self-link, cycles, missing tasks. |
+| `task_unlink` | Remove an edge in both directions; no-op if absent. |
+| `task_create_from_message` | Spin a task off an inbox message; records `origin_message` system comment. |
+| `task_briefing` | Per-instance situation summary (actionable / awareness / counters / warnings). |
+| `lead_briefing` | Queen-facing buckets: `assign_owner`, `assign_reviewer`, `clarify`, `repair_dependencies`, `lead_owned`. |
+| `member_briefing` | Boot briefing for a worker/queen with hardcoded boot rules + bootstrap context. |
+| `message_send` | Durably write an inbox message between two instances within a swarm. |
+
+### Fan-out
+
+When a task transitions to a terminal state (e.g. `done` or `cancelled`),
+the server walks its `blocks` edges and delivers an inbox message via
+`message_send` to each downstream task's owner — so newly unblocked work
+surfaces without the recipient polling.

package/dist/server.js

@@ -9,19 +9,29 @@ import { createEmbeddingProviders, EmbeddingService, initDatabase, MemoryStore,
 import { SkillStore, EvolutionPipeline } from "@mclawnet/skill-manager";
 import { getAllToolDefinitions, routeToolCall } from "./tools/index.js";
 const log = createLogger({ module: "mcp-server" });
-const dbPath = process.env.CLAWNET_MEMORY_DB ?? join(homedir(), ".clawnet", "memory.db");
+// Two distinct roots:
+//   homeDir    — user home (no `.clawnet` suffix). TaskStore/InboxStore append
+//                `.clawnet/projects/...` themselves via projectRoot(); double-
+//                appending here corrupts the layout (#…/.clawnet/.clawnet/…).
+//                Honour CLAWNET_HOME so tests and InboxStore stay in sync.
+//   clawnetDir — the `.clawnet` directory itself (skills, evolution, memory).
+const homeDir = process.env.CLAWNET_HOME ?? homedir();
+const clawnetDir = process.env.CLAWNET_DIR ?? join(homeDir, ".clawnet");
+const dbPath = process.env.CLAWNET_MEMORY_DB ?? join(clawnetDir, "memory.db");
 const db = initDatabase(dbPath);
 log.info({ dbPath }, "ClawNet MCP server starting");
 const store = new MemoryStore(db);
 const providers = createEmbeddingProviders();
 const embeddingService = new EmbeddingService(db, providers);
-const clawnetDir = process.env.CLAWNET_DIR ?? join(homedir(), ".clawnet");
 const skillStore = new SkillStore(clawnetDir);
 const evolutionPipeline = new EvolutionPipeline(clawnetDir);
 const context = {
     memory: { store, embeddingService },
     skill: { store: skillStore },
     evolution: { pipeline: evolutionPipeline },
+    task: { rootDir: homeDir },
+    inbox: { rootDir: homeDir },
+    planReview: { rootDir: homeDir },
 };
 const server = new Server({ name: "clawnet-mcp", version: "0.1.0" }, { capabilities: { tools: {} } });
 server.setRequestHandler(ListToolsRequestSchema, async () => ({

package/dist/server.js.map

@@ -1 +1 @@
-{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}

package/dist/tools/inbox.d.ts

@@ -0,0 +1,74 @@
+export interface InboxRelayLike {
+    deliver(swarmId: string, instanceId: string): void | Promise<void>;
+}
+export interface InboxToolContext {
+    rootDir: string;
+    /**
+     * Optional task store root, used by `message_send` to validate the optional
+     * `expectedStatus` / `expectedOwner` pre-check fields. When unset, those
+     * fields are silently ignored (back-compat with callers that don't wire a
+     * task context). The router wires this to `context.task.rootDir`.
+     */
+    taskRootDir?: string;
+    /**
+     * Optional in-process relay. When present, message_send will call
+     * `relay.deliver(swarmId, to)` after writing to disk so the recipient
+     * agent is woken immediately. Failures are swallowed (best-effort).
+     */
+    relay?: InboxRelayLike;
+}
+export declare const INBOX_TOOL_NAMES: Set<string>;
+export declare function getInboxToolDefinitions(): {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            workDir: {
+                type: string;
+                description: string;
+            };
+            swarmId: {
+                type: string;
+                description: string;
+            };
+            from: {
+                type: string;
+                description: string;
+            };
+            to: {
+                type: string;
+                description: string;
+            };
+            type: {
+                type: string;
+                description: string;
+            };
+            data: {
+                type: string;
+                description: string;
+            };
+            taskId: {
+                type: string;
+                description: string;
+            };
+            expectedStatus: {
+                type: string;
+                description: string;
+            };
+            expectedOwner: {
+                type: string[];
+                description: string;
+            };
+        };
+        required: string[];
+    };
+}[];
+export declare function handleInboxToolCall(name: string, args: Record<string, unknown>, context: InboxToolContext): Promise<{
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    isError?: boolean;
+}>;
+//# sourceMappingURL=inbox.d.ts.map

package/dist/tools/inbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inbox.d.ts","sourceRoot":"","sources":["../../src/tools/inbox.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACpE;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,KAAK,CAAC,EAAE,cAAc,CAAC;CACxB;AAED,eAAO,MAAM,gBAAgB,aAA4B,CAAC;AAE1D,wBAAgB,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IA+BtC;AAED,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC;IAAE,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC,CAoBhF"}

package/dist/tools/inbox.js

@@ -0,0 +1,168 @@
+import { randomUUID } from "node:crypto";
+import { createLogger } from "@mclawnet/logger";
+import { InboxStore } from "@mclawnet/swarm";
+import { TaskStore } from "@mclawnet/task";
+const log = createLogger({ module: "mcp-server/tools/inbox" });
+export const INBOX_TOOL_NAMES = new Set(["message_send"]);
+export function getInboxToolDefinitions() {
+    return [
+        {
+            name: "message_send",
+            description: "Send an inbox message from one agent instance to another within a swarm. Writes the message to the recipient's inbox file and (when an in-process relay is wired) signals immediate delivery. The swarm/recipient need not exist; the message is durably written and will be picked up later. Optional expectedStatus/expectedOwner act as an optimistic pre-check against the linked task — when the live task no longer matches the sender's view, the send is rejected with isError so the sender can re-read and re-decide rather than nudging based on a stale snapshot.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    workDir: { type: "string", description: "Absolute path of the project working directory" },
+                    swarmId: { type: "string", description: "Swarm id the recipient lives in" },
+                    from: { type: "string", description: "Sender instance id (free-form, e.g. 'queen-0')" },
+                    to: { type: "string", description: "Recipient instance id" },
+                    type: { type: "string", description: "Application-defined message type" },
+                    data: { type: "string", description: "Message payload as a string (callers serialise structured data themselves)" },
+                    taskId: { type: "string", description: "Optional task id this message is associated with" },
+                    expectedStatus: {
+                        type: "string",
+                        description: "Optional optimistic pre-check: requires the linked task's current status to equal this value, otherwise the send is rejected. Requires taskId.",
+                    },
+                    expectedOwner: {
+                        type: ["string", "null"],
+                        description: "Optional optimistic pre-check: requires the linked task's current owner to equal this value (use null to assert the task is unowned). Requires taskId.",
+                    },
+                },
+                required: ["workDir", "swarmId", "from", "to", "type", "data"],
+            },
+        },
+    ];
+}
+export async function handleInboxToolCall(name, args, context) {
+    try {
+        log.info({ tool: name }, "MCP inbox tool called");
+        switch (name) {
+            case "message_send":
+                return await handleMessageSend(args, context);
+            default:
+                return {
+                    content: [{ type: "text", text: JSON.stringify({ error: `Unknown tool: ${name}` }) }],
+                    isError: true,
+                };
+        }
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        log.error({ tool: name, err }, "MCP inbox tool error");
+        return {
+            content: [{ type: "text", text: JSON.stringify({ error: message }) }],
+            isError: true,
+        };
+    }
+}
+/**
+ * All expected-state pre-check rejections share this envelope so callers can
+ * write a single parser. Returned directly (not thrown) because the wrapper
+ * at handleInboxToolCall would otherwise strip structured fields.
+ */
+function rejectPrecheck(payload) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(payload) }],
+        isError: true,
+    };
+}
+async function handleMessageSend(args, context) {
+    const workDir = args.workDir;
+    const swarmId = args.swarmId;
+    const from = args.from;
+    const to = args.to;
+    const type = args.type;
+    const data = args.data;
+    if (!workDir)
+        throw new Error("workDir is required");
+    if (!swarmId)
+        throw new Error("swarmId is required");
+    if (!from)
+        throw new Error("from is required");
+    if (!to)
+        throw new Error("to is required");
+    if (!type)
+        throw new Error("type is required");
+    if (data === undefined || data === null)
+        throw new Error("data is required");
+    const taskId = args.taskId;
+    const hasExpectedStatus = "expectedStatus" in args && args.expectedStatus !== undefined;
+    const hasExpectedOwner = "expectedOwner" in args && args.expectedOwner !== undefined;
+    // Optimistic pre-check: if the sender wants to assert the linked task is in
+    // a specific state (typical use: queen nudging a worker), verify the live
+    // task matches before writing the message. This prevents nudges based on a
+    // stale snapshot — the sender should re-read and re-decide instead.
+    //
+    // All rejections here return the same structured envelope:
+    //   { error, taskId?, expected?, observed? }
+    // …so callers can write a single parser regardless of which precondition
+    // failed. (The wrapper at handleInboxToolCall catches throws and only
+    // serialises {error: message}, which would strip the extra fields — so we
+    // return directly with isError: true rather than throwing.)
+    if (hasExpectedStatus || hasExpectedOwner) {
+        const expected = {};
+        if (hasExpectedStatus)
+            expected.status = args.expectedStatus;
+        if (hasExpectedOwner)
+            expected.owner = args.expectedOwner;
+        if (!taskId) {
+            return rejectPrecheck({
+                error: "taskId is required when expectedStatus or expectedOwner is supplied",
+                expected,
+            });
+        }
+        if (!context.taskRootDir) {
+            // Wiring bug, not a caller error: surface it loudly so the operator can
+            // see that the router didn't pass through task.rootDir.
+            throw new Error("expected-state pre-check requested but inbox context has no taskRootDir wired");
+        }
+        const taskStore = new TaskStore({ workDir, home: context.taskRootDir });
+        const live = taskStore.tryGet(taskId);
+        if (!live) {
+            return rejectPrecheck({
+                error: `Task not found: ${taskId}`,
+                taskId,
+                expected,
+            });
+        }
+        const observed = {
+            status: live.status,
+            owner: live.owner,
+        };
+        const statusMismatch = hasExpectedStatus && observed.status !== expected.status;
+        const ownerMismatch = hasExpectedOwner && observed.owner !== expected.owner;
+        if (statusMismatch || ownerMismatch) {
+            return rejectPrecheck({
+                error: "stale snapshot: expected task state does not match observed state",
+                taskId,
+                expected,
+                observed,
+            });
+        }
+    }
+    const messageId = randomUUID();
+    const msg = {
+        id: messageId,
+        from,
+        type,
+        data,
+        ...(taskId ? { taskId } : {}),
+        timestamp: Date.now(),
+        delivered: false,
+    };
+    const store = new InboxStore(workDir, swarmId, context.rootDir);
+    await store.append(to, msg);
+    if (context.relay) {
+        try {
+            await context.relay.deliver(swarmId, to);
+        }
+        catch (err) {
+            // Best-effort: relay wake-up failures must not abort message_send.
+            log.warn({ err, swarmId, to }, "inbox relay deliver failed (best-effort)");
+        }
+    }
+    return {
+        content: [{ type: "text", text: JSON.stringify({ messageId }) }],
+    };
+}
+//# sourceMappingURL=inbox.js.map

package/dist/tools/inbox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inbox.js","sourceRoot":"","sources":["../../src/tools/inbox.ts"],"names":[],"mappings":"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"}