@selfagency/beans-mcp 0.1.3 → 0.4.2

package/README.md

@@ -12,6 +12,14 @@ MCP (Model Context Protocol) server for [Beans](https://github.com/hmans/beans)
 npx @selfagency/beans-mcp /path/to/workspace
 ```
 
+### Versioning
+
+`@selfagency/beans-mcp` tracks upstream [Beans](https://github.com/hmans/beans) versions.
+For example, Beans `v0.4.2` maps to `@selfagency/beans-mcp@0.4.2`.
+
+At startup, the server compares its own package version against the installed `beans`
+CLI version. If they differ, it prints a warning to stderr and continues startup.
+
 ### Parameters
 
 - `--workspace-root` or positional arg: Workspace root path
@@ -23,12 +31,12 @@ npx @selfagency/beans-mcp /path/to/workspace
 ## Summary of public MCP tools
 
 - `beans_init` — Initialize the workspace (optional `prefix`).
-- `beans_view` — Fetch full bean details by `beanId`.
+- `beans_view` — Fetch full bean details by `beanId` or `beanIds`.
 - `beans_create` — Create a new bean (title/type + optional fields).
-- `beans_update` — Consolidated metadata updates (status/type/priority/parent/clearParent/blocking/blockedBy).
-- `beans_delete` — Delete a bean (`beanId`, optional `force`).
+- `beans_update` — Consolidated metadata + body updates (status/type/priority/parent/clearParent/blocking/blockedBy/body/bodyAppend/bodyReplace) plus optional optimistic concurrency hint (`ifMatch`).
+- `beans_delete` — Delete one or many beans (`beanId` or `beanIds`, optional `force`).
 - `beans_reopen` — Reopen a completed or scrapped bean to an active status.
-- `beans_query` — Unified list/search/filter/sort/llm_context/open_config operations.
+- `beans_query` — Unified list/search/filter/sort/ready/llm_context/open_config operations.
 - `beans_bean_file` — Read/edit/create/delete files under `.beans`.
 - `beans_output` — Read extension output logs or show guidance.
 
@@ -37,6 +45,7 @@ npx @selfagency/beans-mcp /path/to/workspace
 - The `beans_query` tool is intentionally broad: prefer it for listing, searching, filtering or sorting beans, and for generating Copilot instructions (`operation: 'llm_context'`).
 - All file and log operations validate paths to keep them within the workspace or the VS Code log directory.
 - `beans_update` replaces many fine-grained update tools; callers should use it to keep the public tool surface small and predictable.
+- Version mismatches are warning-only and non-blocking by design.
 
 ## Examples
 
@@ -62,6 +71,12 @@ Request:
 { "beanId": "bean-abc" }
 ```
 
+Request (multiple beans):
+
+```json
+{ "beanIds": ["bean-abc", "bean-def"] }
+```
+
 Response (structuredContent):
 
 ```json
@@ -114,10 +129,26 @@ Request (change status and add blocking):
 {
   "beanId": "bean-abc",
   "status": "in-progress",
-  "blocking": ["bean-def"]
+  "blocking": ["bean-def"],
+  "ifMatch": "etag-value"
 }
 ```
 
+Request (atomic body modifications):
+
+```json
+{
+  "beanId": "bean-abc",
+  "bodyReplace": [
+    { "old": "- [ ] Task 1", "new": "- [x] Task 1" },
+    { "old": "- [ ] Task 2", "new": "- [x] Task 2" }
+  ],
+  "bodyAppend": "## Summary\n\nAll checklist items completed."
+}
+```
+
+> Note: `body` (full replacement) cannot be combined with `bodyAppend` or `bodyReplace` in the same request.
+
 Response (structuredContent):
 
 ```json
@@ -144,6 +175,26 @@ Response:
 { "deleted": true, "beanId": "bean-old" }
 ```
 
+Batch request:
+
+```json
+{ "beanIds": ["bean-old", "bean-older"], "force": false }
+```
+
+Batch response (summary):
+
+```json
+{
+  "requestedCount": 2,
+  "deletedCount": 2,
+  "failedCount": 0,
+  "results": [
+    { "beanId": "bean-old", "deleted": true },
+    { "beanId": "bean-older", "deleted": true }
+  ]
+}
+```
+
 ### beans_reopen
 
 Request:
@@ -199,6 +250,12 @@ Sort (modes: `status-priority-type-title`, `updated`, `created`, `id`):
 { "operation": "sort", "mode": "updated" }
 ```
 
+Ready (actionable beans only):
+
+```json
+{ "operation": "ready" }
+```
+
 LLM context (generate Copilot instructions; optional write-to-workspace):
 
 ```json
@@ -211,7 +268,7 @@ Response (structuredContent):
 {
   "graphqlSchema": "...",
   "generatedInstructions": "...",
-  "instructionsPath": "/workspace/.github/instructions/tasks.instructions.md"
+  "instructionsPath": "/workspace/.github/instructions/beans-prime.instructions.md"
 }
 ```
 

package/{dist/beans-mcp-server.cjs → beans-mcp-server.cjs}

@@ -22747,7 +22747,7 @@ var init_utils = __esm({
 });
 
 // src/internal/graphql.ts
-var LIST_BEANS_QUERY, CREATE_BEAN_MUTATION, UPDATE_BEAN_MUTATION, DELETE_BEAN_MUTATION;
+var LIST_BEANS_QUERY, CREATE_BEAN_MUTATION, UPDATE_BEAN_MUTATION, UPDATE_BEAN_MUTATION_WITH_IF_MATCH, DELETE_BEAN_MUTATION;
 var init_graphql = __esm({
   "src/internal/graphql.ts"() {
     "use strict";
@@ -22765,6 +22765,11 @@ var init_graphql = __esm({
   mutation($id: ID!, $input: UpdateBeanInput!) {
     updateBean(id: $id, input: $input) { id slug path title body status type priority tags parentId blockingIds blockedByIds createdAt updatedAt etag }
   }
+`;
+    UPDATE_BEAN_MUTATION_WITH_IF_MATCH = `
+  mutation($id: ID!, $input: UpdateBeanInput!, $ifMatch: String!) {
+    updateBean(id: $id, input: $input, ifMatch: $ifMatch) { id slug path title body status type priority tags parentId blockingIds blockedByIds createdAt updatedAt etag }
+  }
 `;
     DELETE_BEAN_MUTATION = `
   mutation($id: ID!) {
@@ -22922,10 +22927,50 @@ Output: ${stdout.slice(0, 1e3)}`
         if (updates.body !== void 0) {
           updateInput.body = updates.body;
         }
-        const { data, errors } = await this.executeGraphQL(UPDATE_BEAN_MUTATION, {
-          id: beanId,
-          input: updateInput
-        });
+        const bodyMod = {};
+        if (updates.bodyAppend !== void 0) {
+          bodyMod.append = updates.bodyAppend;
+        }
+        if (Array.isArray(updates.bodyReplace) && updates.bodyReplace.length > 0) {
+          bodyMod.replace = updates.bodyReplace;
+        }
+        if (Object.keys(bodyMod).length > 0) {
+          updateInput.bodyMod = bodyMod;
+        }
+        let data;
+        let errors;
+        if (updates.ifMatch) {
+          try {
+            const res = await this.executeGraphQL(UPDATE_BEAN_MUTATION_WITH_IF_MATCH, {
+              id: beanId,
+              input: updateInput,
+              ifMatch: updates.ifMatch
+            });
+            data = res.data;
+            errors = res.errors;
+          } catch (error48) {
+            const message = error48.message || "";
+            const unsupportedIfMatch = /unknown argument.*ifMatch|unknown field.*ifMatch|ifMatch.*not defined|field .*updateBean.* argument .*ifMatch/i.test(
+              message
+            );
+            if (!unsupportedIfMatch) {
+              throw error48;
+            }
+            const fallback = await this.executeGraphQL(UPDATE_BEAN_MUTATION, {
+              id: beanId,
+              input: updateInput
+            });
+            data = fallback.data;
+            errors = fallback.errors;
+          }
+        } else {
+          const res = await this.executeGraphQL(UPDATE_BEAN_MUTATION, {
+            id: beanId,
+            input: updateInput
+          });
+          data = res.data;
+          errors = res.errors;
+        }
         if (errors && errors.length > 0) {
           throw new Error(`GraphQL error: ${errors.map((e) => e.message).join(", ")}`);
         }
@@ -22945,6 +22990,21 @@ Output: ${stdout.slice(0, 1e3)}`
         const content = await (0, import_promises.readFile)(configPath, "utf8");
         return { configPath, content };
       }
+      async primeInstructions() {
+        const { stdout } = await execFileAsync(this.cliPath, ["prime"], {
+          cwd: this.workspaceRoot,
+          env: this.getSafeEnv(),
+          maxBuffer: 10 * 1024 * 1024,
+          timeout: 3e4
+        });
+        return stdout.trim();
+      }
+      async writeInstructions(instructions) {
+        const instructionsPath = (0, import_node_path2.join)(this.workspaceRoot, ".github", "instructions", "beans-prime.instructions.md");
+        await (0, import_promises.mkdir)((0, import_node_path2.dirname)(instructionsPath), { recursive: true });
+        await (0, import_promises.writeFile)(instructionsPath, instructions, "utf8");
+        return instructionsPath;
+      }
       async graphqlSchema() {
         const { stdout } = await execFileAsync(this.cliPath, ["graphql", "--schema"], {
           cwd: this.workspaceRoot,
@@ -31072,6 +31132,10 @@ var EMPTY_COMPLETION_RESULT = {
   }
 };
 
+// src/server/BeansMcpServer.ts
+var import_node_child_process2 = require("child_process");
+var import_node_util2 = require("util");
+
 // src/internal/queryHelpers.ts
 function sortBeansInternal(beans, mode) {
   const sorted = [...beans];
@@ -31127,15 +31191,23 @@ async function handleQueryOperation(backend, params) {
   const { operation, mode, statuses, types, search, tags, writeToWorkspaceInstructions, includeClosed } = params;
   if (operation === "llm_context") {
     const graphqlSchema = typeof backend.graphqlSchema === "function" ? await backend.graphqlSchema() : "";
-    const instructionsPath = writeToWorkspaceInstructions && typeof backend.writeInstructions === "function" ? await backend.writeInstructions("") : null;
+    let generatedInstructions = "";
+    if (typeof backend.primeInstructions === "function") {
+      try {
+        generatedInstructions = await backend.primeInstructions();
+      } catch {
+        generatedInstructions = "";
+      }
+    }
+    const instructionsPath = writeToWorkspaceInstructions && typeof backend.writeInstructions === "function" ? await backend.writeInstructions(generatedInstructions) : null;
     return {
       content: [
         {
           type: "text",
-          text: JSON.stringify({ graphqlSchema, generatedInstructions: "", instructionsPath }, null, 2)
+          text: JSON.stringify({ graphqlSchema, generatedInstructions, instructionsPath }, null, 2)
         }
       ],
-      structuredContent: { graphqlSchema, generatedInstructions: "", instructionsPath }
+      structuredContent: { graphqlSchema, generatedInstructions, instructionsPath }
     };
   }
   if (operation === "open_config") {
@@ -31181,6 +31253,31 @@ async function handleQueryOperation(backend, params) {
       structuredContent: { query: search, count: beans2.length, beans: beans2 }
     };
   }
+  if (operation === "ready") {
+    const allBeans = await backend.list();
+    const byId = new Map(allBeans.map((bean) => [bean.id, bean]));
+    const candidates = await backend.list({ status: normalizedStatuses, type: normalizedTypes, search });
+    const readyBeans = candidates.filter((bean) => {
+      if (bean.status !== "todo") {
+        return false;
+      }
+      const blockedBy = bean.blockedByIds || [];
+      if (blockedBy.length === 0) {
+        return true;
+      }
+      return blockedBy.every((blockerId) => {
+        const blocker = byId.get(blockerId);
+        if (!blocker) {
+          return false;
+        }
+        return blocker.status === "completed" || blocker.status === "scrapped";
+      });
+    });
+    return {
+      content: [{ type: "text", text: JSON.stringify({ count: readyBeans.length, beans: readyBeans }, null, 2) }],
+      structuredContent: { count: readyBeans.length, beans: readyBeans }
+    };
+  }
   const beans = await backend.list({ status: normalizedStatuses, type: normalizedTypes, search });
   const sorted = sortBeansInternal(beans, mode ?? "status-priority-type-title");
   return {
@@ -31203,7 +31300,7 @@ init_utils();
 // package.json
 var package_default = {
   name: "@selfagency/beans-mcp",
-  version: "0.1.3",
+  version: "0.4.2",
   private: false,
   description: "MCP (Model Context Protocol) server for Beans issue tracker",
   author: {
@@ -31219,6 +31316,7 @@ var package_default = {
     type: "git",
     url: "git+https://github.com/selfagency/beans-mcp.git"
   },
+  mcpName: "io.github.selfagency/beans-mcp",
   keywords: [
     "beans",
     "mcp",
@@ -31257,18 +31355,18 @@ var package_default = {
   devDependencies: {
     "@modelcontextprotocol/sdk": "^1.27.1",
     "@octokit/rest": "^22.0.1",
-    "@types/node": "^20.19.0",
-    "@vitest/coverage-v8": "^4.0.18",
-    "@vitest/ui": "4.0.18",
+    "@types/node": "25.5.0",
+    "@vitest/coverage-v8": "^4.1.0",
+    "@vitest/ui": "4.1.0",
     husky: "^9.1.7",
-    "lint-staged": "^16.2.7",
+    "lint-staged": "^16.3.3",
     ora: "^9.3.0",
-    oxfmt: "^0.35.0",
-    oxlint: "^1.50.0",
-    "oxlint-tsgolint": "^0.15.0",
+    oxfmt: "^0.40.0",
+    oxlint: "^1.55.0",
+    "oxlint-tsgolint": "^0.16.0",
     tsup: "8.5.1",
     typescript: "^5.9.3",
-    vitest: "4.0.18",
+    vitest: "4.1.0",
     zod: "4.3.6",
     zx: "^8.8.5"
   },
@@ -31284,6 +31382,45 @@ var package_default = {
 };
 
 // src/server/BeansMcpServer.ts
+var execFileAsync2 = (0, import_node_util2.promisify)(import_node_child_process2.execFile);
+var PACKAGE_VERSION = package_default.version ?? "0.0.0-dev";
+function getSafeCliEnv(env) {
+  const whitelist = ["PATH", "HOME", "USER", "LANG", "LC_ALL", "LC_CTYPE", "SHELL"];
+  const safeEnv = {};
+  for (const key of whitelist) {
+    if (env[key]) {
+      safeEnv[key] = env[key];
+    }
+  }
+  for (const key in env) {
+    if (key.startsWith("BEANS_")) {
+      safeEnv[key] = env[key];
+    }
+  }
+  return safeEnv;
+}
+function extractVersionFromOutput(output) {
+  const trimmed = output.trim();
+  if (!trimmed) {
+    return null;
+  }
+  const match = trimmed.match(/(?:^|[^\d])v?(\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?)/);
+  return match?.[1] ?? null;
+}
+async function detectBeansCliVersion(cliPath, workspaceRoot) {
+  try {
+    const { stdout, stderr } = await execFileAsync2(cliPath, ["version"], {
+      cwd: workspaceRoot,
+      env: getSafeCliEnv(process.env),
+      maxBuffer: 1024 * 1024,
+      timeout: 5e3
+    });
+    return extractVersionFromOutput(`${stdout}
+${stderr}`);
+  } catch {
+    return null;
+  }
+}
 async function getBeanById(backend, beanId) {
   try {
     const beans = await backend.list();
@@ -31303,7 +31440,35 @@ function initHandler(backend) {
   };
 }
 function viewHandler(backend) {
-  return async ({ beanId }) => makeTextAndStructured({ bean: await getBeanById(backend, beanId) });
+  return async ({ beanId, beanIds }) => {
+    const ids = Array.isArray(beanIds) && beanIds.length > 0 ? beanIds : beanId ? [beanId] : [];
+    if (ids.length === 0) {
+      throw new Error("Either beanId or beanIds must be provided");
+    }
+    if (ids.length === 1) {
+      const bean = await getBeanById(backend, ids[0]);
+      return makeTextAndStructured({ bean });
+    }
+    const beans = await backend.list();
+    const byId = new Map(beans.map((b) => [b.id, b]));
+    const found = ids.map((id) => byId.get(id)).filter(Boolean);
+    const missingBeanIds = ids.filter((id) => !byId.has(id));
+    return makeTextAndStructured({ beans: found, missingBeanIds, count: found.length, requestedCount: ids.length });
+  };
+}
+async function checkVersionCompatibility(cliPath, workspaceRoot, detector) {
+  const detectedBeansVersion = await detector(cliPath, workspaceRoot);
+  if (!detectedBeansVersion) {
+    console.error(
+      `[beans-mcp] warning: unable to determine Beans CLI version from \`${cliPath}\`; proceeding without version compatibility checks.`
+    );
+    return;
+  }
+  if (detectedBeansVersion !== PACKAGE_VERSION) {
+    console.error(
+      `[beans-mcp] warning: version mismatch detected (beans=${detectedBeansVersion}, beans-mcp=${PACKAGE_VERSION}); continuing startup.`
+    );
+  }
 }
 function createHandler(backend) {
   return async (input) => makeTextAndStructured({ bean: await backend.create(input) });
@@ -31339,17 +31504,56 @@ function updateHandler(backend) {
       clearParent: input.clearParent,
       blocking: input.blocking,
       blockedBy: input.blockedBy,
-      body: input.body
+      body: input.body,
+      bodyAppend: input.bodyAppend,
+      bodyReplace: input.bodyReplace,
+      ifMatch: input.ifMatch
     })
   });
 }
 function deleteHandler(backend) {
-  return async ({ beanId, force }) => {
-    const bean = await getBeanById(backend, beanId);
-    if (!force && bean.status !== "draft" && bean.status !== "scrapped") {
-      throw new Error("Only draft and scrapped beans are deletable unless force=true");
+  return async ({ beanId, beanIds, force }) => {
+    const ids = Array.isArray(beanIds) && beanIds.length > 0 ? beanIds : beanId ? [beanId] : [];
+    if (ids.length === 0) {
+      throw new Error("Either beanId or beanIds must be provided");
+    }
+    if (ids.length === 1) {
+      const bean = await getBeanById(backend, ids[0]);
+      if (!force && bean.status !== "draft" && bean.status !== "scrapped") {
+        throw new Error("Only draft and scrapped beans are deletable unless force=true");
+      }
+      return makeTextAndStructured(await backend.delete(ids[0]));
     }
-    return makeTextAndStructured(await backend.delete(beanId));
+    const beans = await backend.list();
+    const byId = new Map(beans.map((b) => [b.id, b]));
+    const results = [];
+    for (const id of ids) {
+      const bean = byId.get(id);
+      if (!bean) {
+        results.push({ beanId: id, deleted: false, error: "Bean not found" });
+        continue;
+      }
+      if (!force && bean.status !== "draft" && bean.status !== "scrapped") {
+        results.push({
+          beanId: id,
+          deleted: false,
+          error: "Only draft and scrapped beans are deletable unless force=true"
+        });
+        continue;
+      }
+      try {
+        await backend.delete(id);
+        results.push({ beanId: id, deleted: true });
+      } catch (error48) {
+        results.push({ beanId: id, deleted: false, error: error48.message });
+      }
+    }
+    return makeTextAndStructured({
+      results,
+      requestedCount: ids.length,
+      deletedCount: results.filter((r) => r.deleted).length,
+      failedCount: results.filter((r) => !r.deleted).length
+    });
   };
 }
 function queryHandler(backend) {
@@ -31410,7 +31614,12 @@ function registerTools(server, backend) {
     {
       title: "View Bean",
       description: "Fetch full bean details by ID.",
-      inputSchema: external_exports3.object({ beanId: external_exports3.string().min(1).max(MAX_ID_LENGTH) }),
+      inputSchema: external_exports3.object({
+        beanId: external_exports3.string().min(1).max(MAX_ID_LENGTH).optional(),
+        beanIds: external_exports3.array(external_exports3.string().min(1).max(MAX_ID_LENGTH)).optional()
+      }).refine((input) => Boolean(input.beanId) || Array.isArray(input.beanIds) && input.beanIds.length > 0, {
+        message: "Either beanId or beanIds must be provided"
+      }),
       annotations: {
         readOnlyHint: true,
         destructiveHint: false,
@@ -31499,8 +31708,21 @@ function registerTools(server, backend) {
         clearParent: external_exports3.boolean().optional(),
         blocking: external_exports3.array(external_exports3.string().max(MAX_ID_LENGTH)).optional(),
         blockedBy: external_exports3.array(external_exports3.string().max(MAX_ID_LENGTH)).optional(),
-        body: external_exports3.string().max(MAX_DESCRIPTION_LENGTH).optional()
-      }),
+        body: external_exports3.string().max(MAX_DESCRIPTION_LENGTH).optional(),
+        bodyAppend: external_exports3.string().max(MAX_DESCRIPTION_LENGTH).optional(),
+        bodyReplace: external_exports3.array(
+          external_exports3.object({
+            old: external_exports3.string().max(MAX_DESCRIPTION_LENGTH),
+            new: external_exports3.string().max(MAX_DESCRIPTION_LENGTH)
+          })
+        ).optional(),
+        ifMatch: external_exports3.string().max(MAX_METADATA_LENGTH).optional()
+      }).refine(
+        (input) => !(input.body !== void 0 && (input.bodyAppend !== void 0 || input.bodyReplace !== void 0)),
+        {
+          message: "body cannot be combined with bodyAppend/bodyReplace"
+        }
+      ),
       annotations: {
         readOnlyHint: false,
         destructiveHint: false,
@@ -31516,8 +31738,11 @@ function registerTools(server, backend) {
       title: "Delete Bean",
       description: "Delete a bean (intended for draft/scrapped beans).",
       inputSchema: external_exports3.object({
-        beanId: external_exports3.string().min(1).max(MAX_ID_LENGTH),
+        beanId: external_exports3.string().min(1).max(MAX_ID_LENGTH).optional(),
+        beanIds: external_exports3.array(external_exports3.string().min(1).max(MAX_ID_LENGTH)).optional(),
         force: external_exports3.boolean().default(false)
+      }).refine((input) => Boolean(input.beanId) || Array.isArray(input.beanIds) && input.beanIds.length > 0, {
+        message: "Either beanId or beanIds must be provided"
       }),
       annotations: {
         readOnlyHint: false,
@@ -31534,7 +31759,7 @@ function registerTools(server, backend) {
       title: "Query Beans",
       description: "Unified query tool for refresh, filter, search, and sort operations.",
       inputSchema: external_exports3.object({
-        operation: external_exports3.enum(["refresh", "filter", "search", "sort", "llm_context", "open_config"]).default("refresh"),
+        operation: external_exports3.enum(["refresh", "filter", "search", "sort", "ready", "llm_context", "open_config"]).default("refresh"),
         mode: external_exports3.enum(["status-priority-type-title", "updated", "created", "id"]).optional(),
         statuses: external_exports3.array(external_exports3.string().max(MAX_METADATA_LENGTH)).nullable().optional(),
         types: external_exports3.array(external_exports3.string().max(MAX_METADATA_LENGTH)).nullable().optional(),
@@ -31616,6 +31841,12 @@ var MutableBackend = class {
   openConfig() {
     return this.inner.openConfig();
   }
+  primeInstructions() {
+    return this.inner.primeInstructions?.() ?? Promise.resolve("");
+  }
+  writeInstructions(instructions) {
+    return this.inner.writeInstructions?.(instructions) ?? Promise.resolve(null);
+  }
   graphqlSchema() {
     return this.inner.graphqlSchema();
   }
@@ -31653,7 +31884,7 @@ async function createBeansMcpServer(opts) {
   const backend = opts.backend || new BeansCliBackend2(opts.workspaceRoot, opts.cliPath || "beans", opts.logDir);
   const server = new McpServer({
     name: opts.name || "beans-mcp-server",
-    version: opts.version || "0.1.0"
+    version: opts.version || PACKAGE_VERSION
   });
   registerTools(server, backend);
   return { server, backend };
@@ -31725,17 +31956,17 @@ function parseCliArgs(argv) {
   }
   return { workspaceRoot, workspaceExplicit, cliPath, port, logDir };
 }
-async function startBeansMcpServer(argv, _resolveRoots) {
+async function startBeansMcpServer(argv, _resolveRoots, _detectBeansVersion) {
   const { BeansCliBackend: BeansCliBackend2 } = await Promise.resolve().then(() => (init_backend(), backend_exports));
   const { StdioServerTransport: StdioServerTransport2 } = await Promise.resolve().then(() => (init_stdio2(), stdio_exports));
   const { workspaceRoot, workspaceExplicit, cliPath, port, logDir } = parseCliArgs(argv);
+  let effectiveWorkspaceRoot = workspaceRoot;
   process.env.BEANS_VSCODE_MCP_PORT = String(port);
   process.env.BEANS_MCP_PORT = String(port);
   try {
-    const version2 = package_default.version ?? "0.0.0-dev";
     const workspaceLabel = workspaceExplicit ? workspaceRoot : "(auto from roots)";
     console.error(
-      `[beans-mcp] v${version2} starting (port=${port}, workspace=${workspaceLabel}, cli=${cliPath}, logDir=${logDir})`
+      `[beans-mcp] v${PACKAGE_VERSION} starting (port=${port}, workspace=${workspaceLabel}, cli=${cliPath}, logDir=${logDir})`
     );
   } catch {
   }
@@ -31752,13 +31983,17 @@ async function startBeansMcpServer(argv, _resolveRoots) {
     const resolver = _resolveRoots ?? resolveWorkspaceFromRoots;
     const rootPath = await resolver(server);
     if (rootPath) {
-      mutable.setInner(new BeansCliBackend2(rootPath, cliPath));
+      mutable.setInner(new BeansCliBackend2(rootPath, cliPath, logDir));
+      effectiveWorkspaceRoot = rootPath;
       try {
         console.error(`[beans-mcp] workspace resolved from roots: ${rootPath}`);
       } catch {
       }
     }
   }
+  const beansVersionDetector = _detectBeansVersion ?? detectBeansCliVersion;
+  void checkVersionCompatibility(cliPath, effectiveWorkspaceRoot, beansVersionDetector).catch(() => {
+  });
 }
 
 // src/cli.ts