@ai-setting/roy-task-plugin 0.4.1 → 0.5.0

package/dist/claude-plugin/mcp/roy-task-mcp-server.mjs

@@ -0,0 +1,281 @@
+#!/usr/bin/env node
+/**
+ * roy-task MCP server — exposes the task lifecycle to Claude Code as native
+ * MCP tools.
+ *
+ * ## Protocol
+ *
+ * Newline-delimited JSON-RPC 2.0 over stdin/stdout, per the MCP stdio
+ * transport. We implement exactly the methods a task server needs:
+ *
+ * | method                  | direction       | notes                            |
+ * |-------------------------|-----------------|----------------------------------|
+ * | `initialize`            | client -> server | we negotiate the protocol version |
+ * | `notifications/initialized` | client -> server | acknowledged by doing nothing  |
+ * | `tools/list`            | client -> server | the tool catalogue                |
+ * | `tools/call`            | client -> server | run one tool                     |
+ * | `ping`                  | client -> server | health check                     |
+ *
+ * Unknown methods get JSON-RPC error `-32601`. Notifications (requests with
+ * no `id`) get **no** response at all — replying to a notification is a
+ * protocol violation and desynchronises the client.
+ *
+ * ## stdout discipline
+ *
+ * stdout carries the protocol and nothing else. Every diagnostic goes to
+ * stderr. A stray `console.log` would inject garbage into the JSON-RPC stream
+ * and make Claude Code drop the server.
+ *
+ * ## stdio discipline (the other direction)
+ *
+ * This process reads stdin — that is the transport. It must NOT be spawned
+ * with `stdin: "ignore"` (the rule the daemon's spawn adapter enforces for
+ * *agent* subprocesses); an MCP server whose stdin is closed can never
+ * receive a request.
+ */
+
+import { createInterface } from "node:readline";
+
+import { callTool, openStore, BridgeError, defaultTaskDbPath } from "./bridge.mjs";
+import {
+  MCP_TOOLS,
+  SUPPORTED_PROTOCOL_VERSIONS,
+  DEFAULT_PROTOCOL_VERSION,
+  JSON_RPC_ERRORS,
+} from "./tools.mjs";
+
+const SERVER_NAME = "roy-task";
+const SERVER_VERSION = "0.5.0";
+
+/**
+ * Write one JSON-RPC message to stdout.
+ *
+ * `jsonrpc: "2.0"` is **added here**, not by the callers. That is deliberate:
+ * the MCP SDK's response schema (`JSONRPCResultResponseSchema`) is `.strict()`
+ * and rejects any key it does not know — but it *requires* `jsonrpc` to be
+ * exactly `"2.0"`. A response built as `{ id, result }` and written verbatim
+ * fails to parse on the client with
+ * `Unrecognized keys: "id", "result"` / `expected "2.0"`, and the client then
+ * reports "Failed to connect" even though the server is alive and correct.
+ *
+ * Measured: this exact omission was the reason `claude --plugin-dir` showed
+ * `mcp_servers: [{"name":"plugin:roy-task:roy-task","status":"failed"}]` while
+ * the same server answered perfectly over a hand-rolled pipe.
+ */
+function send(message) {
+  process.stdout.write(`${JSON.stringify({ jsonrpc: "2.0", ...message })}\n`);
+}
+
+function sendResult(id, result) {
+  send({ jsonrpc: "2.0", id, result });
+}
+
+function sendError(id, code, message, data) {
+  const error = { code, message };
+  if (data !== undefined) error.data = data;
+  send({ jsonrpc: "2.0", id, error });
+}
+
+/**
+ * Pick the protocol version to answer with.
+ *
+ * Echo the client's version when we know it; otherwise offer ours. This is
+ * what the official SDK does, and it is what lets an older Claude Code talk to
+ * a newer server without a hard failure.
+ */
+export function negotiateProtocolVersion(requested) {
+  if (typeof requested === "string" && SUPPORTED_PROTOCOL_VERSIONS.includes(requested)) {
+    return requested;
+  }
+  return DEFAULT_PROTOCOL_VERSION;
+}
+
+/** Turn a thrown error into an MCP tool result with `isError: true`. */
+function toolError(message) {
+  return {
+    content: [{ type: "text", text: message }],
+    isError: true,
+  };
+}
+
+/**
+ * The server's identity, shared by `initialize` and `server/discover`.
+ */
+const SERVER_INFO = { name: SERVER_NAME, version: SERVER_VERSION };
+
+/**
+ * The capabilities we advertise.
+ */
+const SERVER_CAPABILITIES = { tools: { listChanged: false } };
+
+/**
+ * Handle one parsed JSON-RPC request.
+ *
+ * Exported for tests: the pure part (dispatch) is separated from the I/O
+ * part (stdin/stdout) so the protocol can be exercised without a pipe.
+ */
+export function handleRequest(request, db) {
+  const { id, method, params } = request;
+
+  // Notifications have no id and must not be answered.
+  if (id === undefined || id === null) {
+    return null;
+  }
+
+  switch (method) {
+    case "initialize": {
+      const requested = params && params.protocolVersion;
+      return {
+        id,
+        result: {
+          protocolVersion: negotiateProtocolVersion(requested),
+          capabilities: SERVER_CAPABILITIES,
+          serverInfo: SERVER_INFO,
+        },
+      };
+    }
+
+    /**
+     * `server/discover` — Claude Code 2.1.285's pre-handshake probe.
+     *
+     * Measured against 2.1.285: before it sends `initialize`, it sends
+     *
+     * ```jsonc
+     * {"jsonrpc":"2.0","id":"server-discover-probe-1","method":"server/discover",
+     *  "params":{"_meta":{
+     *    "io.modelcontextprotocol/protocolVersion":"2026-07-28",
+     *    "io.modelcontextprotocol/clientInfo":{"name":"claude-code","version":"2.1.285"},
+     *    "io.modelcontextprotocol/clientCapabilities":{…}}}}
+     * ```
+     *
+     * A server that answers `-32601 Method not found` is treated by
+     * 2.1.285 as **failed to connect** — the whole MCP server is dropped
+     * even though the later `initialize` handshake would have succeeded.
+     * (Measured: with `server/discover` unhandled the init event reported
+     * `{"name":"plugin:roy-task:roy-task","status":"failed"}`; with it
+     * handled the same event reported `status:"connected"`.)
+     *
+     * The response shape mirrors `initialize` — the server describes itself
+     * — so the two handlers share `SERVER_INFO` / `SERVER_CAPABILITIES`.
+     *
+     * This method is **not** in @modelcontextprotocol/sdk 1.32.1, which is why
+     * an SDK-based client never exercises it and a hand-rolled server can
+     * pass its own tests while failing inside Claude Code.
+     */
+    case "server/discover": {
+      return {
+        id,
+        result: {
+          protocolVersion: negotiateProtocolVersion(
+            (params &&
+              params._meta &&
+              params._meta["io.modelcontextprotocol/protocolVersion"]) ||
+              undefined,
+          ),
+          capabilities: SERVER_CAPABILITIES,
+          serverInfo: SERVER_INFO,
+        },
+      };
+    }
+
+    case "ping":
+      return { id, result: {} };
+
+    case "tools/list":
+      return { id, result: { tools: MCP_TOOLS } };
+
+    case "tools/call": {
+      const toolName = params && params.name;
+      const args = (params && params.arguments) || {};
+      if (typeof toolName !== "string") {
+        return {
+          id,
+          error: {
+            code: JSON_RPC_ERRORS.INVALID_PARAMS,
+            message: "tools/call requires a tool name",
+          },
+        };
+      }
+      try {
+        const value = callTool(db, toolName, args);
+        return {
+          id,
+          result: {
+            content: [{ type: "text", text: JSON.stringify(value, null, 2) }],
+          },
+        };
+      } catch (err) {
+        const message =
+          err instanceof BridgeError
+            ? err.message
+            : `tool "${toolName}" failed: ${err && err.message ? err.message : String(err)}`;
+        return { id, result: toolError(message) };
+      }
+    }
+
+    default:
+      return {
+        id,
+        error: {
+          code: JSON_RPC_ERRORS.METHOD_NOT_FOUND,
+          message: `method not found: ${method}`,
+        },
+      };
+  }
+}
+
+/** Read newline-delimited JSON-RPC from stdin and answer on stdout. */
+export function main() {
+  const dbPath = process.env.ROY_TASK_DB_PATH || defaultTaskDbPath();
+  let db;
+  try {
+    db = openStore(dbPath);
+  } catch (err) {
+    process.stderr.write(
+      `roy-task mcp server: cannot open task store at ${dbPath}: ${err && err.message}\n`,
+    );
+    process.exit(1);
+  }
+
+  const rl = createInterface({ input: process.stdin, crlfDelay: Infinity });
+
+  rl.on("line", (line) => {
+    const trimmed = line.trim();
+    if (trimmed.length === 0) return;
+
+    let request;
+    try {
+      request = JSON.parse(trimmed);
+    } catch {
+      sendError(null, JSON_RPC_ERRORS.PARSE_ERROR, "invalid JSON");
+      return;
+    }
+
+    if (typeof request !== "object" || request === null || Array.isArray(request)) {
+      sendError(null, JSON_RPC_ERRORS.INVALID_REQUEST, "request must be a JSON object");
+      return;
+    }
+
+    const response = handleRequest(request, db);
+    if (response) send(response);
+  });
+
+  rl.on("close", () => {
+    try {
+      db.close();
+    } catch {
+      // already closed
+    }
+    process.exit(0);
+  });
+}
+
+// Only run when executed directly, so tests can import the pure helpers.
+const invokedDirectly =
+  process.argv[1] &&
+  (process.argv[1].endsWith("roy-task-mcp-server.mjs") ||
+    process.argv[1].endsWith("roy-task-mcp-server.js"));
+
+if (invokedDirectly) {
+  main();
+}

package/dist/claude-plugin/mcp/tools.mjs

@@ -0,0 +1,240 @@
+/**
+ * Zero-dependency MCP server exposing the roy task tools over stdio.
+ *
+ * ## Why hand-rolled instead of @modelcontextprotocol/sdk
+ *
+ * The published npm package (`@ai-setting/roy-task-plugin`) is installed on
+ * plain Node.js machines with no native build step. Adding the SDK would add a
+ * dependency tree to a package whose whole point is "install and it runs".
+ * The MCP wire format we need is small and stable:
+ *
+ * - newline-delimited JSON-RPC 2.0 on stdin/stdout
+ * - `initialize` / `tools/list` / `tools/call` (plus `notifications/initialized`)
+ *
+ * That is implemented here in ~200 lines with nothing but `node:child_process`.
+ * The protocol version is negotiated: we echo the client's requested version
+ * when it is one we know, else we answer with our own.
+ *
+ * ## Where the data comes from
+ *
+ * The task store is **roy-agent's** store (`~/.local/share/roy-agent/tasks.db`),
+ * not the plugin's own `~/.roy-task-plugin/tasks.db`. The reason is
+ * interoperability: the roy agent inside opencode/claude creates tasks through
+ * `roy-agent`'s own task tools, and the progress card the daemon sends is
+ * rendered from the *same* rows. If this MCP server wrote to a different
+ * database, Claude would create tasks the card can never see.
+ *
+ * So the tools shell out to the `roy-agent tasks …` CLI, which is the stable,
+ * already-migrated, already-schema-validated way to reach that store. We do
+ * not re-implement the store, and we do not open the SQLite file ourselves.
+ *
+ * ## stdio hygiene
+ *
+ * This process is spawned by Claude Code as an MCP server. It must:
+ *
+ * - **read** stdin (that is the transport) — obviously not `ignore` here;
+ * - **never** write anything but protocol messages to stdout. A stray
+ *   `console.log` would corrupt the stream, so every log line goes to stderr.
+ *
+ * The "stdin must be ignore" rule from the daemon's spawn adapter applies to
+ * *agent* subprocesses, not to an MCP server — an MCP server whose stdin is
+ * closed can never receive a single request.
+ */
+
+export const SUPPORTED_PROTOCOL_VERSIONS = Object.freeze([
+  "2025-11-25",
+  "2025-06-18",
+  "2025-03-26",
+  "2024-11-05",
+  "2024-10-07",
+]);
+
+export const DEFAULT_PROTOCOL_VERSION = "2025-11-25";
+
+/** The JSON-RPC error codes we use. */
+export const JSON_RPC_ERRORS = Object.freeze({
+  PARSE_ERROR: -32700,
+  INVALID_REQUEST: -32600,
+  METHOD_NOT_FOUND: -32601,
+  INVALID_PARAMS: -32602,
+  INTERNAL_ERROR: -32603,
+});
+
+/**
+ * The task tools we expose.
+ *
+ * The names mirror roy-agent's own tool names (`task_create`, `task_list`, …)
+ * so the mental model transfers one-to-one.
+ */
+export const MCP_TOOLS = Object.freeze([
+  {
+    name: "task_tree",
+    description:
+      "Show the task tree. Call this BEFORE creating anything, to decide whether new work belongs under an existing root (parent_task_id) or is genuinely new.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        depth: {
+          type: "number",
+          description: "Tree depth. 1 = roots + their direct children. -1 = unlimited.",
+        },
+        parent_task_id: {
+          type: "number",
+          description: "Only show the subtree under this task id.",
+        },
+      },
+    },
+  },
+  {
+    name: "task_create",
+    description:
+      "Create a tracked task. Task is a first-class citizen: create the task BEFORE doing the work, then update it as you go and complete it when done.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        title: { type: "string", description: "Imperative, specific one-line title." },
+        description: { type: "string", description: "What needs to be done and why." },
+        goals_and_expected_deliverables: {
+          type: "string",
+          description: "Success criteria and expected outputs.",
+        },
+        priority: {
+          type: "string",
+          enum: ["low", "medium", "high"],
+          description: "Task priority.",
+        },
+        type: {
+          type: "string",
+          enum: ["normal", "cycle", "longterm"],
+          description: "normal = one-off; cycle = periodic; longterm = ongoing goal.",
+        },
+        parent_task_id: {
+          type: "number",
+          description: "Parent task id. Omit to create a root task.",
+        },
+        project_path: { type: "string", description: "Project root path." },
+        context: {
+          type: "string",
+          description: "JSON string with worktree_path / branch / type etc.",
+        },
+        tags: {
+          type: "array",
+          items: { type: "string" },
+          description: "Task tags.",
+        },
+      },
+      required: ["title"],
+    },
+  },
+  {
+    name: "task_get",
+    description: "Get one task's full detail, including its operation records.",
+    inputSchema: {
+      type: "object",
+      properties: { id: { type: "number", description: "Task id." } },
+      required: ["id"],
+    },
+  },
+  {
+    name: "task_list",
+    description: "List tasks. Supports filtering by status / priority / type.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        status: {
+          type: "string",
+          enum: ["todo", "active", "completed", "paused", "cancelled", "archived"],
+        },
+        priority: { type: "string", enum: ["low", "medium", "high"] },
+        type: { type: "string", enum: ["normal", "cycle", "longterm"] },
+        limit: { type: "number", description: "Max rows (default 20)." },
+        offset: { type: "number", description: "Row offset." },
+      },
+    },
+  },
+  {
+    name: "task_update",
+    description:
+      "Update a task's status, progress or description. Report progress as you go, not only at the end.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "number", description: "Task id." },
+        status: {
+          type: "string",
+          enum: ["todo", "active", "completed", "paused", "cancelled", "archived"],
+        },
+        progress: { type: "number", description: "0-100." },
+        current_status: { type: "string", description: "One sentence: where you are right now." },
+        description: { type: "string", description: "Replace the description." },
+        goals_and_expected_deliverables: { type: "string", description: "Replace the goals." },
+        priority: { type: "string", enum: ["low", "medium", "high"] },
+      },
+      required: ["id"],
+    },
+  },
+  {
+    name: "task_operation_create",
+    description:
+      "Record a milestone (what was reached) and, optionally, a process summary (how you got there, 100-150 chars). Milestones mark state transitions: RED->GREEN, blocker found, decision made.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        task_id: { type: "number", description: "Task id." },
+        milestone_type: {
+          type: "string",
+          enum: [
+            "create",
+            "progress",
+            "milestone",
+            "problem",
+            "solution",
+            "decision",
+            "review",
+            "completed",
+          ],
+        },
+        milestone_title: { type: "string", description: "One-line milestone title." },
+        milestone_description: { type: "string", description: "What was reached." },
+        process_description: {
+          type: "string",
+          description: "How you got there. 100-150 characters, strictly.",
+        },
+      },
+      required: ["task_id", "milestone_type", "milestone_title"],
+    },
+  },
+  {
+    name: "task_complete",
+    description:
+      "Close out a task. Provide deliverable_storage_path so the outcome is traceable.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "number", description: "Task id." },
+        deliverable_storage_path: {
+          type: "string",
+          description: "Where the work product lives (path / URL / branch).",
+        },
+      },
+      required: ["id"],
+    },
+  },
+  {
+    name: "task_search",
+    description:
+      "Search tasks by keywords across title, description, goals, tags and operation records.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        keywords: {
+          type: "array",
+          items: { type: "string" },
+          description: "Keywords (AND logic).",
+        },
+        limit: { type: "number" },
+      },
+      required: ["keywords"],
+    },
+  },
+]);