@ai-setting/roy-task-plugin 0.6.0 → 0.7.0

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

@@ -3,14 +3,25 @@
  * roy-task MCP server — exposes the task lifecycle to Claude Code as native
  * MCP tools.
  *
- * ## Protocol
+ * ## What this file is
+ *
+ * A **transport**: newline-delimited JSON-RPC 2.0 over stdin/stdout, and
+ * nothing else. The protocol handling, the tool catalogue, the tool
+ * execution and every task semantic live in
+ * `@ai-setting/roy-agent-core/env/task/mcp`.
  *
- * Newline-delimited JSON-RPC 2.0 over stdin/stdout, per the MCP stdio
- * transport. We implement exactly the methods a task server needs:
+ * Before Task #4619 this file (281 lines) plus `bridge.mjs` (482 lines) plus
+ * `tools.mjs` (240 lines) re-implemented the whole task surface: the tool
+ * catalogue was hand-copied, and the tools were raw SQL against roy's own
+ * database. Now the plugin contributes **transport + wiring** and nothing
+ * else.
+ *
+ * ## Protocol
  *
  * | method                  | direction       | notes                            |
  * |-------------------------|-----------------|----------------------------------|
  * | `initialize`            | client -> server | we negotiate the protocol version |
+ * | `server/discover`       | client -> server | Claude Code 2.1.285's pre-handshake probe |
  * | `notifications/initialized` | client -> server | acknowledged by doing nothing  |
  * | `tools/list`            | client -> server | the tool catalogue                |
  * | `tools/call`            | client -> server | run one tool                     |
@@ -36,16 +47,25 @@
 
 import { createInterface } from "node:readline";
 
-import { callTool, openStore, BridgeError, defaultTaskDbPath } from "./bridge.mjs";
+import { createServer, BridgeError, defaultTaskDbPath } from "./bridge.mjs";
 import {
-  MCP_TOOLS,
+  JSON_RPC_ERRORS,
   SUPPORTED_PROTOCOL_VERSIONS,
   DEFAULT_PROTOCOL_VERSION,
-  JSON_RPC_ERRORS,
 } from "./tools.mjs";
+import { setStdoutStrictMode } from "@ai-setting/roy-agent-core/env/log-trace";
 
-const SERVER_NAME = "roy-task";
-const SERVER_VERSION = "0.5.0";
+// ─────────────────────────────────────────────────────────────────────────
+// stdout 归协议，stderr 归诊断（Task #4619）
+//
+// MCP 的 stdio 传输是「按行分隔的 JSON-RPC」，跑在 stdout 上。core 的 logger
+// 原本把 `info` 打到 stdout，task store 的 migration 也用 `console.log` 打印
+// 横幅 —— 实测本 server **26 行 stdout 里有 24 行不是 JSON**，客户端会因此
+// 丢弃整个 server（Claude Code 报 `status: "failed"`）。
+//
+// 所以这里开 core 的 stdout-strict 模式：日志全走 stderr，stdout 只留给协议。
+// ─────────────────────────────────────────────────────────────────────────
+setStdoutStrictMode(true);
 
 /**
  * Write one JSON-RPC message to stdout.
@@ -71,23 +91,7 @@ function sendResult(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;
+  send({ jsonrpc: "2.0", id, error: { code, message, ...(data ? { data } : {}) } });
 }
 
 /** Turn a thrown error into an MCP tool result with `isError: true`. */
@@ -98,23 +102,17 @@ function toolError(message) {
   };
 }
 
-/**
- * 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.
  *
+ * The dispatch is delegated to core's MCP server; this function only adapts
+ * the **shape** (core returns `result` / `error` objects, this module writes
+ * them with the `jsonrpc` envelope).
+ *
  * 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) {
+export async function handleRequest(request, server) {
   const { id, method, params } = request;
 
   // Notifications have no id and must not be answered.
@@ -155,9 +153,6 @@ export function handleRequest(request, db) {
      * `{"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.
@@ -182,7 +177,7 @@ export function handleRequest(request, db) {
       return { id, result: {} };
 
     case "tools/list":
-      return { id, result: { tools: MCP_TOOLS } };
+      return { id, result: { tools: server.listTools() } };
 
     case "tools/call": {
       const toolName = params && params.name;
@@ -197,7 +192,7 @@ export function handleRequest(request, db) {
         };
       }
       try {
-        const value = callTool(db, toolName, args);
+        const value = await server.callTool(toolName, args);
         return {
           id,
           result: {
@@ -224,12 +219,38 @@ export function handleRequest(request, db) {
   }
 }
 
+/**
+ * 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;
+}
+
+/**
+ * The server's identity, shared by `initialize` and `server/discover`.
+ */
+const SERVER_NAME = "roy-task";
+const SERVER_VERSION = "1.0.0";
+const SERVER_INFO = { name: SERVER_NAME, version: SERVER_VERSION };
+
+/**
+ * The capabilities we advertise.
+ */
+const SERVER_CAPABILITIES = { tools: { listChanged: false } };
+
 /** 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;
+  let server;
   try {
-    db = openStore(dbPath);
+    server = createServer(dbPath);
   } catch (err) {
     process.stderr.write(
       `roy-task mcp server: cannot open task store at ${dbPath}: ${err && err.message}\n`,
@@ -256,16 +277,20 @@ export function main() {
       return;
     }
 
-    const response = handleRequest(request, db);
-    if (response) send(response);
+    Promise.resolve(handleRequest(request, server))
+      .then((response) => {
+        if (response) send(response);
+      })
+      .catch((err) => {
+        sendError(
+          request.id ?? null,
+          JSON_RPC_ERRORS.INTERNAL_ERROR,
+          err && err.message ? err.message : String(err),
+        );
+      });
   });
 
   rl.on("close", () => {
-    try {
-      db.close();
-    } catch {
-      // already closed
-    }
     process.exit(0);
   });
 }

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

@@ -1,240 +1,54 @@
 /**
- * Zero-dependency MCP server exposing the roy task tools over stdio.
+ * The MCP tool catalogue — **derived from roy-agent's core**.
  *
- * ## Why hand-rolled instead of @modelcontextprotocol/sdk
+ * ## What this file used to be
  *
- * 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:
+ * Before Task #4619 it was a hand-written catalogue: 240 lines of
+ * hand-copied tool names, descriptions and JSON Schemas for the eight task
+ * tools. It was a **second copy** of core's tool definitions, so it drifted:
+ * core's `task_create` gained a `context` field, a `type` enum and a
+ * `project_path` field, and the plugin's copy did not — so a Claude Code
+ * client could not pass the arguments the real tool accepted.
  *
- * - newline-delimited JSON-RPC 2.0 on stdin/stdout
- * - `initialize` / `tools/list` / `tools/call` (plus `notifications/initialized`)
+ * ## What it is now
  *
- * 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.
+ * A ~20-line re-export of core's own tool definitions. The names,
+ * descriptions and JSON Schema come from the **same factories** the tool
+ * execution uses, so they cannot drift.
  *
- * ## 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.
+ * The MCP wire protocol constants (protocol versions, JSON-RPC error codes)
+ * also come from core now — they are part of the same contract.
  */
 
-export const SUPPORTED_PROTOCOL_VERSIONS = Object.freeze([
-  "2025-11-25",
-  "2025-06-18",
-  "2025-03-26",
-  "2024-11-05",
-  "2024-10-07",
-]);
+import {
+  createTaskMcpToolDefinitions,
+  TASK_MCP_SUPPORTED_PROTOCOL_VERSIONS,
+  TASK_MCP_DEFAULT_PROTOCOL_VERSION,
+  TASK_MCP_JSON_RPC_ERRORS,
+} from "@ai-setting/roy-agent-core/env/task/mcp";
+import { TaskStoreBackend, createSQLiteTaskPort } from "@ai-setting/roy-agent-core/env/task/backend";
+import { SQLiteTaskStore } from "@ai-setting/roy-agent-core/env/task/storage";
+
+/** The MCP protocol versions we accept. */
+export const SUPPORTED_PROTOCOL_VERSIONS = TASK_MCP_SUPPORTED_PROTOCOL_VERSIONS;
 
-export const DEFAULT_PROTOCOL_VERSION = "2025-11-25";
+/** The protocol version we answer with when the client's is unknown. */
+export const DEFAULT_PROTOCOL_VERSION = TASK_MCP_DEFAULT_PROTOCOL_VERSION;
 
 /** 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,
-});
+export const JSON_RPC_ERRORS = TASK_MCP_JSON_RPC_ERRORS;
 
 /**
- * The task tools we expose.
+ * The task tools we expose — derived from core's own tool factories.
  *
- * The names mirror roy-agent's own tool names (`task_create`, `task_list`, …)
- * so the mental model transfers one-to-one.
+ * The factories never touch the store while building a definition, so an
+ * **in-memory** store is enough here. Using the real path would create the
+ * database file as a side effect of *importing* this module — a surprising
+ * side effect for a module that is only supposed to describe the tool
+ * catalogue.
  */
-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"],
-    },
-  },
-]);
+export const MCP_TOOLS = Object.freeze(
+  createTaskMcpToolDefinitions(
+    new TaskStoreBackend(createSQLiteTaskPort(new SQLiteTaskStore(":memory:"))),
+  ),
+);