@selfagency/beans-mcp 0.1.4 → 0.4.2

package/index.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,
@@ -31089,6 +31149,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];
@@ -31144,15 +31208,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") {
@@ -31198,6 +31270,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 {
@@ -31220,7 +31317,7 @@ init_utils();
 // package.json
 var package_default = {
   name: "@selfagency/beans-mcp",
-  version: "0.1.4",
+  version: "0.4.2",
   private: false,
   description: "MCP (Model Context Protocol) server for Beans issue tracker",
   author: {
@@ -31275,18 +31372,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"
   },
@@ -31302,6 +31399,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();
@@ -31321,7 +31457,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) });
@@ -31357,17 +31521,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) {
@@ -31428,7 +31631,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,
@@ -31517,8 +31725,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,
@@ -31534,8 +31755,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,
@@ -31552,7 +31776,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(),
@@ -31634,6 +31858,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();
   }
@@ -31671,7 +31901,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 };
@@ -31743,17 +31973,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 {
   }
@@ -31770,13 +32000,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/index.ts

package/index.d.ts

@@ -69,12 +69,20 @@ interface BackendInterface {
         blocking?: string[];
         blockedBy?: string[];
         body?: string;
+        bodyAppend?: string;
+        bodyReplace?: Array<{
+            old: string;
+            new: string;
+        }>;
+        ifMatch?: string;
     }): Promise<BeanRecord>;
     delete(beanId: string): Promise<Record<string, unknown>>;
     openConfig(): Promise<{
         configPath: string;
         content: string;
     }>;
+    primeInstructions?(): Promise<string>;
+    writeInstructions?(instructions: string): Promise<string | null>;
     graphqlSchema(): Promise<string>;
     readOutputLog(options?: {
         lines?: number;
@@ -146,12 +154,20 @@ declare class BeansCliBackend implements BackendInterface {
         blocking?: string[];
         blockedBy?: string[];
         body?: string;
+        bodyAppend?: string;
+        bodyReplace?: Array<{
+            old: string;
+            new: string;
+        }>;
+        ifMatch?: string;
     }): Promise<BeanRecord>;
     delete(beanId: string): Promise<Record<string, unknown>>;
     openConfig(): Promise<{
         configPath: string;
         content: string;
     }>;
+    primeInstructions(): Promise<string>;
+    writeInstructions(instructions: string): Promise<string>;
     graphqlSchema(): Promise<string>;
     readOutputLog(options?: {
         lines?: number;
@@ -202,7 +218,9 @@ declare function parseCliArgs(argv: string[]): {
 };
 declare function startBeansMcpServer(argv: string[], 
 /** For testing only: override the roots resolver so tests can cover the setInner branch. */
-_resolveRoots?: (server: McpServer) => Promise<string | null>): Promise<void>;
+_resolveRoots?: (server: McpServer) => Promise<string | null>, 
+/** For testing only: override Beans CLI version detection. */
+_detectBeansVersion?: (cliPath: string, workspaceRoot: string) => Promise<string | null>): Promise<void>;
 
 /**
  * Check whether `target` is contained within `root` after resolving both paths.