@selfagency/beans-mcp 0.5.0 → 0.6.1

package/beans-mcp-server.cjs

@@ -22905,6 +22905,26 @@ Output: ${stdout.slice(0, 1e3)}`
         });
         return { initialized: true };
       }
+      async archive() {
+        const { stdout } = await execFileAsync(this.cliPath, ["archive", "--json"], {
+          cwd: this.workspaceRoot,
+          env: this.getSafeEnv(),
+          maxBuffer: 10 * 1024 * 1024,
+          timeout: 3e4
+        });
+        this.invalidateCache();
+        if (!stdout.trim()) {
+          return { archived: true };
+        }
+        try {
+          return JSON.parse(stdout);
+        } catch {
+          return { archived: true, output: stdout.trim() };
+        }
+      }
+      async queryGraphql(query, variables) {
+        return this.executeGraphQL(query, variables);
+      }
       async list(options) {
         const filter = {};
         if (options?.status && options.status.length > 0) {
@@ -23059,32 +23079,39 @@ Output: ${stdout.slice(0, 1e3)}`
         return { deleted: true, beanId };
       }
       async bulkCreate(beans, defaultParent) {
-        const results = [];
-        for (const item of beans) {
-          try {
-            const bean = await this.create({
+        const settled = await Promise.allSettled(
+          beans.map(
+            async (item) => this.create({
               ...item,
               parent: item.parent ?? defaultParent
-            });
-            results.push({ bean });
-          } catch (error48) {
-            results.push({ error: error48.message });
-          }
-        }
-        return results;
+            })
+          )
+        );
+        return settled.map(
+          (result) => result.status === "fulfilled" ? { bean: result.value } : { error: result.reason instanceof Error ? result.reason.message : String(result.reason) }
+        );
       }
       async bulkUpdate(beans, defaultParent) {
-        const results = [];
-        for (const { beanId, ...updates } of beans) {
-          try {
+        const settled = await Promise.allSettled(
+          beans.map(async ({ beanId, ...updates }) => {
             const resolvedParent = updates.parent ?? (updates.clearParent ? void 0 : defaultParent);
             const bean = await this.update(beanId, { ...updates, parent: resolvedParent });
-            results.push({ beanId, bean });
-          } catch (error48) {
-            results.push({ beanId, error: error48.message });
+            return { beanId, bean };
+          })
+        );
+        return settled.map((result, index) => {
+          const beanId = beans[index]?.beanId;
+          if (!beanId) {
+            return { beanId: "unknown", error: "Unknown bean id" };
           }
-        }
-        return results;
+          if (result.status === "fulfilled") {
+            return result.value;
+          }
+          return {
+            beanId,
+            error: result.reason instanceof Error ? result.reason.message : String(result.reason)
+          };
+        });
       }
       async openConfig() {
         const configPath = (0, import_node_path2.join)(this.workspaceRoot, ".beans.yml");
@@ -23119,9 +23146,12 @@ Output: ${stdout.slice(0, 1e3)}`
         const outputPath = (0, import_node_path2.resolve)(
           process.env.BEANS_VSCODE_OUTPUT_LOG || (0, import_node_path2.join)(this.workspaceRoot, ".vscode", "logs", "beans-output.log")
         );
-        const isWithinWorkspace = isPathWithinRoot(this.workspaceRoot, outputPath);
+        const canonicalOutputPath = await (0, import_promises.realpath)(outputPath).catch(() => outputPath);
+        const canonicalWorkspaceRoot = await (0, import_promises.realpath)(this.workspaceRoot).catch(() => (0, import_node_path2.resolve)(this.workspaceRoot));
+        const isWithinWorkspace = isPathWithinRoot(canonicalWorkspaceRoot, canonicalOutputPath);
         const vscodeLogDir = process.env.BEANS_VSCODE_LOG_DIR || this.logDir ? (0, import_node_path2.resolve)(process.env.BEANS_VSCODE_LOG_DIR || this.logDir || "") : void 0;
-        const isWithinVscodeLogDir = vscodeLogDir ? isPathWithinRoot(vscodeLogDir, outputPath) : false;
+        const canonicalVscodeLogDir = vscodeLogDir ? await (0, import_promises.realpath)(vscodeLogDir).catch(() => (0, import_node_path2.resolve)(vscodeLogDir)) : void 0;
+        const isWithinVscodeLogDir = canonicalVscodeLogDir ? isPathWithinRoot(canonicalVscodeLogDir, canonicalOutputPath) : false;
         if (!isWithinWorkspace && !isWithinVscodeLogDir) {
           throw new Error("Output log path must stay within the workspace or VS Code log directory");
         }
@@ -23200,6 +23230,105 @@ Output: ${stdout.slice(0, 1e3)}`
       escapeForYamlDoubleQuoted(value) {
         return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
       }
+      shouldQuoteFrontmatterValue(value) {
+        return !/^[A-Za-z0-9._-]+$/.test(value);
+      }
+      parseFrontmatterLine(line) {
+        const separatorIndex = line.indexOf(":");
+        if (separatorIndex <= 0) {
+          return null;
+        }
+        const key = line.slice(0, separatorIndex).trim();
+        if (key.length === 0) {
+          return null;
+        }
+        for (const character of key) {
+          const isAlphaNumericUnderscore = character >= "a" && character <= "z" || character >= "A" && character <= "Z" || character >= "0" && character <= "9" || character === "_";
+          if (!isAlphaNumericUnderscore) {
+            return null;
+          }
+        }
+        const rawValue = line.slice(separatorIndex + 1).trimStart();
+        return { key, rawValue };
+      }
+      buildFrontmatterIndex(frontmatterLines) {
+        const indexByKey = /* @__PURE__ */ new Map();
+        frontmatterLines.forEach((line, index) => {
+          const parsed = this.parseFrontmatterLine(line);
+          if (!parsed) {
+            return;
+          }
+          indexByKey.set(parsed.key, index);
+        });
+        return indexByKey;
+      }
+      serializeFrontmatterValue(key, value) {
+        if (Array.isArray(value)) {
+          return JSON.stringify(value);
+        }
+        if (key === "title") {
+          return this.normalizeFrontmatterTitleValue(value);
+        }
+        if (this.shouldQuoteFrontmatterValue(value)) {
+          return `"${this.escapeForYamlDoubleQuoted(value)}"`;
+        }
+        return value;
+      }
+      deserializeFrontmatterValue(value) {
+        const trimmed = value.trim();
+        if (trimmed.startsWith("[") && trimmed.endsWith("]")) {
+          try {
+            const parsed = JSON.parse(trimmed);
+            if (Array.isArray(parsed) && parsed.every((item) => typeof item === "string")) {
+              return parsed;
+            }
+          } catch {
+          }
+        }
+        if (trimmed.startsWith('"') && trimmed.endsWith('"') || trimmed.startsWith("'") && trimmed.endsWith("'")) {
+          return trimmed.slice(1, -1).replaceAll('\\"', '"').replaceAll("\\\\", "\\").replaceAll("''", "'");
+        }
+        return trimmed;
+      }
+      splitFrontmatterDocument(content) {
+        const crlfOpen = content.startsWith("---\r\n");
+        const lfOpen = content.startsWith("---\n");
+        const eol = crlfOpen ? "\r\n" : "\n";
+        if (!crlfOpen && !lfOpen) {
+          return { eol: "\n", hasFrontmatter: false, frontmatterLines: [], body: content };
+        }
+        const openEnd = `---${eol}`.length;
+        const closeMarker = `${eol}---`;
+        const closeIdx = content.indexOf(closeMarker, openEnd);
+        if (closeIdx === -1) {
+          return { eol, hasFrontmatter: false, frontmatterLines: [], body: content };
+        }
+        const frontmatter = content.slice(openEnd, closeIdx);
+        const body = content.slice(closeIdx + closeMarker.length);
+        return {
+          eol,
+          hasFrontmatter: true,
+          frontmatterLines: frontmatter.length > 0 ? frontmatter.split(eol) : [],
+          body
+        };
+      }
+      parseFrontmatterFields(frontmatterLines) {
+        const fields = {};
+        for (const line of frontmatterLines) {
+          const parsed = this.parseFrontmatterLine(line);
+          if (!parsed) {
+            continue;
+          }
+          const { valuePart } = this.splitYamlInlineComment(parsed.rawValue);
+          fields[parsed.key] = this.deserializeFrontmatterValue(valuePart);
+        }
+        return fields;
+      }
+      async writeFileAtomically(absolutePath, content) {
+        const tempPath = `${absolutePath}.tmp-${process.pid}-${Date.now()}`;
+        await (0, import_promises.writeFile)(tempPath, content, "utf8");
+        await (0, import_promises.rename)(tempPath, absolutePath);
+      }
       /**
        * Normalise a raw YAML title value to a double-quoted scalar.
        * Handles: empty, already double-quoted, single-quoted (unescaping `''`),
@@ -23270,14 +23399,66 @@ Output: ${stdout.slice(0, 1e3)}`
         await (0, import_promises.writeFile)(absolutePath, fixed, "utf8");
         return { path: absolutePath, bytes: Buffer.byteLength(fixed, "utf8") };
       }
+      async updateBeanFrontmatter(relativePath, updates) {
+        const absolutePath = this.resolveBeanFilePath(relativePath);
+        const content = await (0, import_promises.readFile)(absolutePath, "utf8");
+        const { eol, hasFrontmatter, frontmatterLines, body } = this.splitFrontmatterDocument(content);
+        const updatedFields = Object.entries(updates).filter(([, value]) => value !== void 0).map(([key]) => key);
+        if (updatedFields.length === 0) {
+          throw new Error("At least one frontmatter field update is required");
+        }
+        const nextLines = [...frontmatterLines];
+        let indexByKey = this.buildFrontmatterIndex(nextLines);
+        for (const [key, value] of Object.entries(updates)) {
+          if (value === void 0) {
+            continue;
+          }
+          const existingIndex = indexByKey.get(key);
+          if (value === null) {
+            if (existingIndex !== void 0) {
+              nextLines.splice(existingIndex, 1);
+              indexByKey = this.buildFrontmatterIndex(nextLines);
+            }
+            continue;
+          }
+          const serialized = `${key}: ${this.serializeFrontmatterValue(key, value)}`;
+          if (existingIndex !== void 0) {
+            const existingLine = nextLines[existingIndex] ?? "";
+            const existingParsed = this.parseFrontmatterLine(existingLine);
+            const commentPart = existingParsed ? this.splitYamlInlineComment(existingParsed.rawValue).commentPart : "";
+            nextLines[existingIndex] = `${serialized}${commentPart}`;
+          } else {
+            nextLines.push(serialized);
+            indexByKey.set(key, nextLines.length - 1);
+          }
+        }
+        const frontmatterBlock = nextLines.length > 0 ? nextLines.join(eol) : "";
+        const nextContent = hasFrontmatter ? `---${eol}${frontmatterBlock}${eol}---${body}` : `---${eol}${frontmatterBlock}${eol}---${eol}${body}`;
+        const fixed = this.quoteFrontmatterTitles(nextContent);
+        await this.writeFileAtomically(absolutePath, fixed);
+        return {
+          path: absolutePath,
+          bytes: Buffer.byteLength(fixed, "utf8"),
+          updatedFields,
+          frontmatter: this.parseFrontmatterFields(this.splitFrontmatterDocument(fixed).frontmatterLines)
+        };
+      }
       async createBeanFile(relativePath, content, options) {
         const absolutePath = this.resolveBeanFilePath(relativePath);
         const fixed = this.quoteFrontmatterTitles(content);
         await (0, import_promises.mkdir)((0, import_node_path2.dirname)(absolutePath), { recursive: true });
-        await (0, import_promises.writeFile)(absolutePath, fixed, {
-          encoding: "utf8",
-          flag: options?.overwrite ? "w" : "wx"
-        });
+        try {
+          await (0, import_promises.writeFile)(absolutePath, fixed, {
+            encoding: "utf8",
+            flag: options?.overwrite ? "w" : "wx"
+          });
+        } catch (error48) {
+          const maybeNodeError = error48;
+          if (maybeNodeError.code === "EEXIST" && !options?.overwrite) {
+            throw new Error("Bean file already exists. Pass overwrite=true to replace it.");
+          }
+          throw error48;
+        }
         return {
           path: absolutePath,
           bytes: Buffer.byteLength(fixed, "utf8"),
@@ -31368,14 +31549,16 @@ var import_node_util2 = require("util");
 // package.json
 var package_default = {
   name: "@selfagency/beans-mcp",
-  version: "0.5.0",
+  version: "0.6.1",
   private: false,
   description: "MCP (Model Context Protocol) server for Beans issue tracker",
-  author: {
-    name: "Daniel Sieradski",
-    email: "daniel@self.agency",
-    url: "https://self.agency"
-  },
+  keywords: [
+    "ai",
+    "beans",
+    "issue-tracker",
+    "mcp",
+    "model-context-protocol"
+  ],
   homepage: "https://github.com/selfagency/beans-mcp",
   bugs: {
     url: "https://github.com/selfagency/beans-mcp/issues"
@@ -31384,15 +31567,12 @@ var package_default = {
     type: "git",
     url: "git+https://github.com/selfagency/beans-mcp.git"
   },
-  mcpName: "io.github.selfagency/beans-mcp",
-  keywords: [
-    "beans",
-    "mcp",
-    "model-context-protocol",
-    "issue-tracker",
-    "ai"
-  ],
   license: "MIT",
+  author: {
+    name: "Daniel Sieradski",
+    email: "daniel@self.agency",
+    url: "https://self.agency"
+  },
   type: "module",
   exports: {
     ".": {
@@ -31407,46 +31587,57 @@ var package_default = {
   bin: {
     "beans-mcp": "dist/beans-mcp-server.cjs"
   },
+  files: [
+    "dist",
+    "skills",
+    "README.md",
+    "LICENSE.txt"
+  ],
   scripts: {
     build: "tsup",
+    postbuild: "node ./scripts/write-dist-package.js",
+    "docs:build": "vitepress build docs",
+    "docs:dev": "vitepress dev docs",
+    "docs:preview": "vitepress preview docs",
     format: "oxfmt",
-    "lint:fix": "oxlint --fix",
     lint: "oxlint",
-    postbuild: "node ./scripts/write-dist-package.js",
+    "lint:fix": "oxlint --fix",
     prepare: "husky",
     release: "zx ./scripts/release.js",
+    test: "vitest run",
     "test:coverage": "vitest run --coverage",
     "test:watch": "vitest",
-    test: "vitest run",
     "type-check": "tsc --noEmit"
   },
+  "lint-staged": {
+    "src/**/*.ts": [
+      "pnpm run lint:fix",
+      "pnpm run format"
+    ]
+  },
   devDependencies: {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@octokit/rest": "^22.0.1",
-    "@types/node": "25.5.2",
-    "@vitest/coverage-v8": "^4.1.2",
-    "@vitest/ui": "4.1.2",
+    "@types/node": "25.6.0",
+    "@vitest/coverage-v8": "^4.1.4",
+    "@vitest/ui": "4.1.4",
     husky: "^9.1.7",
     "lint-staged": "^16.4.0",
     ora: "^9.3.0",
-    oxfmt: "^0.43.0",
-    oxlint: "^1.58.0",
-    "oxlint-tsgolint": "^0.20.0",
+    oxfmt: "^0.45.0",
+    oxlint: "^1.60.0",
+    "oxlint-tsgolint": "^0.21.1",
     tsup: "8.5.1",
-    typescript: "6.0.2",
-    vitest: "4.1.2",
+    typescript: "6.0.3",
+    vitepress: "^1.6.4",
+    vitest: "4.1.4",
     zod: "4.3.6",
     zx: "^8.8.5"
   },
   engines: {
     node: ">=18"
   },
-  "lint-staged": {
-    "src/**/*.ts": [
-      "pnpm run lint:fix",
-      "pnpm run format"
-    ]
-  }
+  mcpName: "io.github.selfagency/beans-mcp"
 };
 
 // src/internal/queryHelpers.ts
@@ -31611,6 +31802,8 @@ var MAX_PATH_LENGTH = 1024;
 init_utils();
 var execFileAsync2 = (0, import_node_util2.promisify)(import_node_child_process2.execFile);
 var PACKAGE_VERSION = package_default.version ?? "0.0.0-dev";
+var CLOSED_STATUSES = /* @__PURE__ */ new Set(["completed", "scrapped"]);
+var BEAN_ID_HINT = "Missing required field `beanId`. Did you mean `beanId`?";
 function getSafeCliEnv(env) {
   const whitelist = ["PATH", "HOME", "USER", "LANG", "LC_ALL", "LC_CTYPE", "SHELL"];
   const safeEnv = {};
@@ -31631,7 +31824,8 @@ function extractVersionFromOutput(output) {
   if (!trimmed) {
     return null;
   }
-  const match = trimmed.match(/(?:^|[^\d])v?(\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?)/);
+  const versionRegex = /(?:^|[^\d])v?(\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?)/;
+  const match = versionRegex.exec(trimmed);
   return match?.[1] ?? null;
 }
 async function detectBeansCliVersion(cliPath, workspaceRoot) {
@@ -31648,10 +31842,10 @@ ${stderr}`);
     return null;
   }
 }
-async function getBeanById(backend, beanId) {
+async function getBeanById(backend, beanId, beans) {
   try {
-    const beans = await backend.list();
-    const found = beans.find((b) => b.id === beanId);
+    const allBeans = beans ?? await backend.list();
+    const found = allBeans.find((b) => b.id === beanId);
     if (!found) {
       throw new Error(`Bean not found: ${beanId}`);
     }
@@ -31660,12 +31854,111 @@ async function getBeanById(backend, beanId) {
     throw new Error(`Failed to fetch bean ${beanId}: ${error48.message}`);
   }
 }
+function collectDescendantBeans(beans, rootBeanId) {
+  const byParent = /* @__PURE__ */ new Map();
+  const byId = new Map(beans.map((bean) => [bean.id, bean]));
+  for (const bean of beans) {
+    if (!bean.parentId) {
+      continue;
+    }
+    const children = byParent.get(bean.parentId) ?? [];
+    children.push(bean.id);
+    byParent.set(bean.parentId, children);
+  }
+  const queue = [...byParent.get(rootBeanId) ?? []];
+  const visited = /* @__PURE__ */ new Set();
+  const descendants = [];
+  while (queue.length > 0) {
+    const currentId = queue.shift();
+    if (!currentId || visited.has(currentId)) {
+      continue;
+    }
+    visited.add(currentId);
+    const currentBean = byId.get(currentId);
+    if (!currentBean) {
+      continue;
+    }
+    descendants.push(currentBean);
+    const children = byParent.get(currentId);
+    if (children && children.length > 0) {
+      queue.push(...children);
+    }
+  }
+  return descendants;
+}
+async function cascadeStatusToDescendants(backend, rootBeanId, targetStatus, options) {
+  const beans = options?.beans ?? await backend.list();
+  const descendants = collectDescendantBeans(beans, rootBeanId);
+  const updatedBeanIds = [];
+  const skippedBeanIds = [];
+  const errors = [];
+  const toUpdate = [];
+  for (const bean of descendants) {
+    if (options?.onlyCurrentStatuses && !options.onlyCurrentStatuses.has(bean.status)) {
+      skippedBeanIds.push(bean.id);
+      continue;
+    }
+    toUpdate.push(bean);
+  }
+  const settled = await Promise.allSettled(
+    toUpdate.map(async (bean) => backend.update(bean.id, { status: targetStatus }))
+  );
+  settled.forEach((result, index) => {
+    const bean = toUpdate[index];
+    if (!bean) {
+      return;
+    }
+    if (result.status === "fulfilled") {
+      updatedBeanIds.push(bean.id);
+      return;
+    }
+    errors.push({
+      beanId: bean.id,
+      error: result.reason instanceof Error ? result.reason.message : String(result.reason)
+    });
+  });
+  return {
+    totalDescendants: descendants.length,
+    updatedBeanIds,
+    skippedBeanIds,
+    errors
+  };
+}
+function completeMarkdownTasks(body) {
+  const lines = body.split(/\r?\n/);
+  let totalTaskCount = 0;
+  let updatedTaskCount = 0;
+  const taskLinePattern = /^\s*(?:[-*+]|\d+\.)\s+\[[ xX]\]/;
+  const uncheckedTaskLinePattern = /^(\s*(?:[-*+]|\d+\.)\s+\[)\s(\].*)$/;
+  const nextLines = lines.map((line) => {
+    if (!taskLinePattern.test(line)) {
+      return line;
+    }
+    totalTaskCount += 1;
+    const uncheckedMatch = uncheckedTaskLinePattern.exec(line);
+    if (!uncheckedMatch) {
+      return line;
+    }
+    updatedTaskCount += 1;
+    return `${uncheckedMatch[1]}x${uncheckedMatch[2]}`;
+  });
+  const nextBody = nextLines.join("\n");
+  return { nextBody, totalTaskCount, updatedTaskCount };
+}
 function initHandler(backend) {
   return async ({ prefix }) => {
     const result = await backend.init(prefix);
     return makeTextAndStructured(result);
   };
 }
+function archiveHandler(backend) {
+  return async () => {
+    if (typeof backend.archive !== "function") {
+      throw new TypeError("Archive is not supported by the current backend");
+    }
+    return makeTextAndStructured(await backend.archive());
+  };
+}
 function viewHandler(backend) {
   return async ({ beanId, beanIds }) => {
     const ids = Array.isArray(beanIds) && beanIds.length > 0 ? beanIds : beanId ? [beanId] : [];
@@ -31703,7 +31996,14 @@ async function checkVersionCompatibility(cliPath, workspaceRoot, detector) {
   }
 }
 function createHandler(backend) {
-  return async (input) => makeTextAndStructured({ bean: await backend.create(input) });
+  return async (input) => {
+    const bean = await backend.create(input);
+    const warnings = input.description !== void 0 ? ["`description` is deprecated; use `body` instead."] : void 0;
+    return makeTextAndStructured({
+      bean,
+      ...warnings ? { warnings } : {}
+    });
+  };
 }
 function editHandler(backend) {
   return async ({
@@ -31717,18 +32017,30 @@ function reopenHandler(backend) {
     requiredCurrentStatus,
     targetStatus
   }) => {
-    const bean = await getBeanById(backend, beanId);
-    if (bean.status !== requiredCurrentStatus) {
-      throw new Error(`Bean ${beanId} is not ${requiredCurrentStatus}`);
+    const beans = await backend.list();
+    const bean = await getBeanById(backend, beanId, beans);
+    if (bean.status === requiredCurrentStatus) {
+      const updatedParentBean = await backend.update(beanId, { status: targetStatus });
+      const cascade = await cascadeStatusToDescendants(backend, beanId, targetStatus, {
+        onlyCurrentStatuses: CLOSED_STATUSES,
+        beans
+      });
+      return makeTextAndStructured({
+        bean: updatedParentBean,
+        cascade: {
+          totalDescendants: cascade.totalDescendants,
+          updatedBeanIds: cascade.updatedBeanIds,
+          skippedBeanIds: cascade.skippedBeanIds,
+          errors: cascade.errors
+        }
+      });
     }
-    return makeTextAndStructured({
-      bean: await backend.update(beanId, { status: targetStatus })
-    });
+    throw new Error(`Bean ${beanId} is not ${requiredCurrentStatus}`);
   };
 }
 function updateHandler(backend) {
-  return async (input) => makeTextAndStructured({
-    bean: await backend.update(input.beanId, {
+  return async (input) => {
+    const updatedBean = await backend.update(input.beanId, {
       status: input.status,
       type: input.type,
       priority: input.priority,
@@ -31740,8 +32052,37 @@ function updateHandler(backend) {
       bodyAppend: input.bodyAppend,
       bodyReplace: input.bodyReplace,
       ifMatch: input.ifMatch
-    })
-  });
+    });
+    const closeStatus = input.status;
+    const shouldCascadeClose = Boolean(closeStatus && CLOSED_STATUSES.has(closeStatus));
+    const cascade = shouldCascadeClose ? await cascadeStatusToDescendants(backend, input.beanId, closeStatus, {
+      beans: await backend.list()
+    }) : null;
+    return makeTextAndStructured({
+      bean: updatedBean,
+      ...cascade ? {
+        cascade: {
+          totalDescendants: cascade.totalDescendants,
+          updatedBeanIds: cascade.updatedBeanIds,
+          skippedBeanIds: cascade.skippedBeanIds,
+          errors: cascade.errors
+        }
+      } : {}
+    });
+  };
+}
+function completeTasksHandler(backend) {
+  return async ({ beanId }) => {
+    const bean = await getBeanById(backend, beanId);
+    const { nextBody, totalTaskCount, updatedTaskCount } = completeMarkdownTasks(bean.body || "");
+    const updatedBean = updatedTaskCount > 0 ? await backend.update(beanId, { body: nextBody }) : bean;
+    return makeTextAndStructured({
+      bean: updatedBean,
+      totalTaskCount,
+      updatedTaskCount,
+      unchangedTaskCount: totalTaskCount - updatedTaskCount
+    });
+  };
 }
 function deleteHandler(backend) {
   return async ({ beanId, beanIds, force }) => {
@@ -31795,11 +32136,17 @@ function deleteHandler(backend) {
 function bulkCreateHandler(backend) {
   return async (input) => {
     const results = await backend.bulkCreate(input.beans, input.parent);
+    const deprecatedDescriptionCount = input.beans.filter((bean) => bean.description !== void 0).length;
     return makeTextAndStructured({
       results,
       requestedCount: input.beans.length,
       successCount: results.filter((r) => r.bean).length,
-      failedCount: results.filter((r) => r.error).length
+      failedCount: results.filter((r) => r.error).length,
+      ...deprecatedDescriptionCount > 0 ? {
+        warnings: [
+          `Found ${deprecatedDescriptionCount} bean(s) using deprecated field \`description\`; use \`body\` instead.`
+        ]
+      } : {}
     });
   };
 }
@@ -31815,14 +32162,24 @@ function bulkUpdateHandler(backend) {
   };
 }
 function queryHandler(backend) {
-  return async (opts) => handleQueryOperation(backend, opts);
+  return async (opts) => {
+    if (opts.operation === "graphql") {
+      if (typeof backend.queryGraphql !== "function") {
+        throw new TypeError("GraphQL passthrough is not supported by the current backend");
+      }
+      const result = await backend.queryGraphql(opts.graphql || "", opts.variables);
+      return makeTextAndStructured({ data: result.data, errors: result.errors ?? [] });
+    }
+    return handleQueryOperation(backend, opts);
+  };
 }
 function beanFileHandler(backend) {
   return async ({
     operation,
     path,
     content,
-    overwrite
+    overwrite,
+    fields
   }) => {
     if (operation === "read") {
       return makeTextAndStructured(await backend.readBeanFile(path));
@@ -31833,6 +32190,9 @@ function beanFileHandler(backend) {
     if (operation === "create") {
       return makeTextAndStructured(await backend.createBeanFile(path, content || "", { overwrite }));
     }
+    if (operation === "update_frontmatter") {
+      return makeTextAndStructured(await backend.updateBeanFrontmatter(path, fields || {}));
+    }
     if (operation === "delete") {
       return makeTextAndStructured(await backend.deleteBeanFile(path));
     }
@@ -31867,6 +32227,21 @@ function registerTools(server, backend) {
     },
     initHandler(backend)
   );
+  server.registerTool(
+    "beans_archive",
+    {
+      title: "Archive Beans",
+      description: "Archive completed or scrapped beans, equivalent to the beans CLI archive command.",
+      inputSchema: external_exports3.object({}),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false
+      }
+    },
+    archiveHandler(backend)
+  );
   server.registerTool(
     "beans_view",
     {
@@ -31876,7 +32251,7 @@ function registerTools(server, backend) {
         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"
+        message: `Either beanId or beanIds must be provided. ${BEAN_ID_HINT}`
       }),
       annotations: {
         readOnlyHint: true,
@@ -31916,7 +32291,7 @@ function registerTools(server, backend) {
       title: "Edit Bean Metadata",
       description: "Update bean metadata fields (status/type/priority/parent/blocking).",
       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(),
         status: external_exports3.string().max(MAX_METADATA_LENGTH).optional(),
         type: external_exports3.string().max(MAX_METADATA_LENGTH).optional(),
         priority: external_exports3.string().max(MAX_METADATA_LENGTH).optional(),
@@ -31924,7 +32299,11 @@ 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()
-      }),
+      }).superRefine((input, ctx) => {
+        if (!input.beanId) {
+          ctx.addIssue({ code: external_exports3.ZodIssueCode.custom, path: ["beanId"], message: BEAN_ID_HINT });
+        }
+      }).transform((input) => ({ ...input, beanId: input.beanId })),
       annotations: {
         readOnlyHint: false,
         destructiveHint: false,
@@ -31940,10 +32319,14 @@ function registerTools(server, backend) {
       title: "Reopen Bean",
       description: "Reopen a completed or scrapped bean into a non-closed status.",
       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(),
         requiredCurrentStatus: external_exports3.enum(["completed", "scrapped"]),
         targetStatus: external_exports3.string().max(MAX_METADATA_LENGTH).default("todo")
-      }),
+      }).superRefine((input, ctx) => {
+        if (!input.beanId) {
+          ctx.addIssue({ code: external_exports3.ZodIssueCode.custom, path: ["beanId"], message: BEAN_ID_HINT });
+        }
+      }).transform((input) => ({ ...input, beanId: input.beanId })),
       annotations: {
         readOnlyHint: false,
         destructiveHint: false,
@@ -31959,7 +32342,7 @@ function registerTools(server, backend) {
       title: "Update Bean",
       description: "Update bean metadata fields (status/type/priority/parent/blocking). Consolidated replacement for per-field update tools.",
       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(),
         status: external_exports3.string().max(MAX_METADATA_LENGTH).optional(),
         type: external_exports3.string().max(MAX_METADATA_LENGTH).optional(),
         priority: external_exports3.string().max(MAX_METADATA_LENGTH).optional(),
@@ -31976,12 +32359,16 @@ function registerTools(server, backend) {
           })
         ).optional(),
         ifMatch: external_exports3.string().max(MAX_METADATA_LENGTH).optional()
+      }).superRefine((input, ctx) => {
+        if (!input.beanId) {
+          ctx.addIssue({ code: external_exports3.ZodIssueCode.custom, path: ["beanId"], message: BEAN_ID_HINT });
+        }
       }).refine(
         (input) => !(input.body !== void 0 && (input.bodyAppend !== void 0 || input.bodyReplace !== void 0)),
         {
           message: "body cannot be combined with bodyAppend/bodyReplace"
         }
-      ),
+      ).transform((input) => ({ ...input, beanId: input.beanId })),
       annotations: {
         readOnlyHint: false,
         destructiveHint: false,
@@ -32001,7 +32388,7 @@ function registerTools(server, backend) {
         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"
+        message: `Either beanId or beanIds must be provided. ${BEAN_ID_HINT}`
       }),
       annotations: {
         readOnlyHint: false,
@@ -32040,7 +32427,7 @@ function registerTools(server, backend) {
     bulkCreateHandler(backend)
   );
   const beanUpdateItemSchema = external_exports3.object({
-    beanId: external_exports3.string().min(1).max(MAX_ID_LENGTH),
+    beanId: external_exports3.string().min(1).max(MAX_ID_LENGTH).optional(),
     status: external_exports3.string().max(MAX_METADATA_LENGTH).optional(),
     type: external_exports3.string().max(MAX_METADATA_LENGTH).optional(),
     priority: external_exports3.string().max(MAX_METADATA_LENGTH).optional(),
@@ -32052,10 +32439,14 @@ function registerTools(server, backend) {
     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()
+  }).superRefine((input, ctx) => {
+    if (!input.beanId) {
+      ctx.addIssue({ code: external_exports3.ZodIssueCode.custom, path: ["beanId"], message: BEAN_ID_HINT });
+    }
   }).refine(
     (input) => !(input.body !== void 0 && (input.bodyAppend !== void 0 || input.bodyReplace !== void 0)),
     { message: "body cannot be combined with bodyAppend/bodyReplace" }
-  );
+  ).transform((input) => ({ ...input, beanId: input.beanId }));
   server.registerTool(
     "beans_bulk_update",
     {
@@ -32074,25 +32465,56 @@ function registerTools(server, backend) {
     },
     bulkUpdateHandler(backend)
   );
+  server.registerTool(
+    "beans_complete_tasks",
+    {
+      title: "Complete Markdown Tasks",
+      description: "Mark all markdown checklist tasks within a bean as completed.",
+      inputSchema: external_exports3.object({
+        beanId: external_exports3.string().min(1).max(MAX_ID_LENGTH).optional()
+      }).superRefine((input, ctx) => {
+        if (!input.beanId) {
+          ctx.addIssue({ code: external_exports3.ZodIssueCode.custom, path: ["beanId"], message: BEAN_ID_HINT });
+        }
+      }).transform((input) => ({ ...input, beanId: input.beanId })),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+      }
+    },
+    completeTasksHandler(backend)
+  );
   server.registerTool(
     "beans_query",
     {
       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", "ready", "llm_context", "open_config"]).default("refresh"),
+        operation: external_exports3.enum(["refresh", "filter", "search", "sort", "ready", "llm_context", "open_config", "graphql"]).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(),
         search: external_exports3.string().max(MAX_TITLE_LENGTH).optional(),
         includeClosed: external_exports3.boolean().optional(),
         tags: external_exports3.array(external_exports3.string().max(MAX_METADATA_LENGTH)).nullable().optional(),
+        graphql: external_exports3.string().max(MAX_DESCRIPTION_LENGTH).optional(),
+        variables: external_exports3.record(external_exports3.string(), external_exports3.unknown()).optional(),
         writeToWorkspaceInstructions: external_exports3.boolean().optional()
+      }).superRefine((input, ctx) => {
+        if (input.operation === "graphql" && (!input.graphql || input.graphql.trim().length === 0)) {
+          ctx.addIssue({
+            code: external_exports3.ZodIssueCode.custom,
+            path: ["graphql"],
+            message: "graphql query string is required when operation is graphql"
+          });
+        }
       }),
       annotations: {
-        readOnlyHint: true,
+        readOnlyHint: false,
         destructiveHint: false,
-        idempotentHint: true,
+        idempotentHint: false,
         openWorldHint: false
       }
     },
@@ -32104,10 +32526,33 @@ function registerTools(server, backend) {
       title: "Bean File Operations",
       description: "Read, create, edit, or delete files under .beans (operation param).",
       inputSchema: external_exports3.object({
-        operation: external_exports3.enum(["read", "edit", "create", "delete"]),
+        operation: external_exports3.enum(["read", "edit", "create", "delete", "update_frontmatter"]),
         path: external_exports3.string().min(1).max(MAX_PATH_LENGTH),
         content: external_exports3.string().max(MAX_DESCRIPTION_LENGTH).optional(),
-        overwrite: external_exports3.boolean().optional()
+        overwrite: external_exports3.boolean().optional(),
+        fields: external_exports3.object({
+          title: external_exports3.string().max(MAX_TITLE_LENGTH).optional(),
+          status: external_exports3.string().max(MAX_METADATA_LENGTH).optional(),
+          type: external_exports3.string().max(MAX_METADATA_LENGTH).optional(),
+          priority: external_exports3.string().max(MAX_METADATA_LENGTH).optional(),
+          parent_id: external_exports3.string().max(MAX_ID_LENGTH).nullable().optional(),
+          tags: external_exports3.array(external_exports3.string().max(MAX_METADATA_LENGTH)).nullable().optional(),
+          blocking_ids: external_exports3.array(external_exports3.string().max(MAX_ID_LENGTH)).nullable().optional(),
+          blocked_by_ids: external_exports3.array(external_exports3.string().max(MAX_ID_LENGTH)).nullable().optional(),
+          pr: external_exports3.string().max(MAX_TITLE_LENGTH).nullable().optional(),
+          branch: external_exports3.string().max(MAX_TITLE_LENGTH).nullable().optional()
+        }).optional()
+      }).superRefine((input, ctx) => {
+        if (input.operation === "update_frontmatter") {
+          const fieldCount = Object.values(input.fields || {}).filter((value) => value !== void 0).length;
+          if (fieldCount === 0) {
+            ctx.addIssue({
+              code: external_exports3.ZodIssueCode.custom,
+              path: ["fields"],
+              message: "At least one frontmatter field update is required"
+            });
+          }
+        }
       }),
       annotations: {
         readOnlyHint: false,
@@ -32147,6 +32592,18 @@ var MutableBackend = class {
   init(prefix) {
     return this.inner.init(prefix);
   }
+  archive() {
+    if (typeof this.inner.archive === "function") {
+      return this.inner.archive();
+    }
+    throw new TypeError("Archive is not supported by backend");
+  }
+  queryGraphql(query, variables) {
+    if (typeof this.inner.queryGraphql === "function") {
+      return this.inner.queryGraphql(query, variables);
+    }
+    throw new TypeError("GraphQL passthrough is not supported by backend");
+  }
   list(opts) {
     return this.inner.list(opts);
   }
@@ -32186,6 +32643,9 @@ var MutableBackend = class {
   editBeanFile(path, content) {
     return this.inner.editBeanFile(path, content);
   }
+  updateBeanFrontmatter(path, updates) {
+    return this.inner.updateBeanFrontmatter(path, updates);
+  }
   createBeanFile(path, content, opts) {
     return this.inner.createBeanFile(path, content, opts);
   }
@@ -32252,6 +32712,16 @@ function parseCliArgs(argv) {
   const envPort = Number.parseInt(process.env.BEANS_VSCODE_MCP_PORT || process.env.BEANS_MCP_PORT || "", 10);
   let port = Number.isInteger(envPort) && envPort > 0 ? envPort : DEFAULT_MCP_PORT;
   let logDir;
+  const parseStrictPositiveInt = (raw, flagName) => {
+    if (!/^\d+$/.test(raw)) {
+      throw new Error(`Invalid value for ${flagName}: ${raw}`);
+    }
+    const parsed = Number.parseInt(raw, 10);
+    if (!Number.isInteger(parsed) || parsed <= 0) {
+      throw new Error(`Invalid value for ${flagName}: ${raw}`);
+    }
+    return parsed;
+  };
   for (let i = 0; i < argv.length; i += 1) {
     const arg = argv[i];
     if ((arg === "--workspace" || arg === "--workspace-root") && argv[i + 1]) {
@@ -32265,10 +32735,7 @@ function parseCliArgs(argv) {
       }
       i += 1;
     } else if (arg === "--port" && argv[i + 1]) {
-      const parsedPort = Number.parseInt(argv[i + 1], 10);
-      if (Number.isInteger(parsedPort) && parsedPort > 0) {
-        port = parsedPort;
-      }
+      port = parseStrictPositiveInt(argv[i + 1], "--port");
       i += 1;
     } else if (arg === "--log-dir" && argv[i + 1]) {
       logDir = argv[i + 1];