关于 beans-mcp
beans-mcp 是面向 Beans 问题跟踪器的 MCP 服务，让 AI Agent 和程序化客户端管理工作区中的事项。它提供批量操作、搜索筛选及文件访问，并通过 Beans CLI 执行操作。
主要功能
- 01创建、更新和删除事项
- 02批量创建与更新事项
- 03按状态、类型或文本查询
- 04读取和编辑 .beans 文件
- 05查看扩展输出日志
适用场景
- 01在工作区中维护项目任务
- 02批量调整事项状态和父级
- 03搜索并筛选待处理问题
- 04读取事项文件或扩展日志
MCP 相关
它将 Beans CLI 的问题跟踪操作作为 MCP 工具提供，包括事项管理、查询、文件操作和日志读取。服务可通过命令行启动并指定工作区。
配置
本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。
工具
14收录的工具列表 · 更新于 1 周前
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| prefix | string | 否 | Bean ID 的可选工作区前缀 |
详细介绍
@voxslopuli/beans-mcp 🫘
适用于 Beans 问题跟踪器的 MCP（Model Context Protocol）服务。提供程序化接口和命令行接口，支持与 Beans 工作区进行 AI 驱动的交互。
🤖 在 VS Code 中试用与 GitHub Copilot 完全集成的 Beans！安装 selfagency.beans-vscode 扩展。
用法
npx @voxslopuli/beans-mcp /path/to/workspace
捆绑的 beans CLI
beans CLI 二进制文件通过平台专用的可选依赖项捆绑
（@voxslopuli/beans-cli-darwin-arm64、-darwin-x64、-linux-arm64、
-linux-x64、-win32-x64），并固定为受支持的 Beans 版本（0.4.2）。
启动时，服务会先解析捆绑的二进制文件；如果无法找到，则回退到 PATH 中的
beans 命令。显式指定的 --cli-path 始终优先。
Beans 发布新版本时，要发布新的平台软件包：
# 1. Bump beansCli.version + optionalDependencies in package.json
pnpm fetch-beans-binaries --version <beans-version>
# 2. Verify staged binaries in build/beans-cli/, then publish
pnpm publish-beans-cli # add --dry-run to preview
或者，在 GitHub Actions 上运行 Release beans CLI packages 工作流。
版本控制
@voxslopuli/beans-mcp 使用独立的软件包版本控制。与
Beans CLI 的兼容性单独跟踪。
启动时，服务会将已安装的 beans CLI 版本与硬编码的受支持 Beans 版本 0.4.2 进行比较。
如果版本不同，它会向 stderr 输出警告并继续启动。
参数
--workspace-root或位置参数：工作区根路径--cli-path：Beans CLI 路径--port：MCP 服务端口（默认值：39173）--log-dir：日志目录-h、--help：打印用法并退出
MCP 公共工具概要
| 工具 | 描述 |
|---|---|
beans_init | 初始化工作区（可选 prefix）。 |
beans_archive | 归档已完成或已废弃的 bean。 |
beans_view | 通过 beanId 或 beanIds 获取 bean 的完整详情。 |
beans_create | 创建新的 bean（标题/类型 + 可选正文/父项）。 |
beans_bulk_create | 一次调用创建多个 bean，可选将它们置于同一个父项下。 |
beans_update | 集中更新元数据和正文（状态/类型/优先级/父项/清除父项/阻塞/被阻塞项/正文/追加正文/替换正文），并可选提供乐观并发提示（ifMatch）。 |
beans_bulk_update | 一次调用更新多个 bean，可选将它们重新分配到同一个父项下。 |
beans_complete_tasks | 将 bean 中所有 Markdown 检查清单任务标记为已完成。 |
beans_delete | 删除一个或多个 bean（beanId 或 beanIds，可选 force）。 |
beans_reopen | 重新打开已完成或已废弃的 bean，使其恢复为活动状态。 |
beans_query | 统一执行列表/搜索/筛选/排序/就绪状态操作，并支持 GraphQL 透传。 |
beans_bean_file | 读取/编辑/创建/删除 .beans 下的文件。 |
beans_output | 读取扩展程序输出日志或显示指引。 |
备注
- `beans_query` 工具的用途较广：列出、搜索、筛选或排序 beans，以及生成 Copilot 指令（`operation: 'llm_context'`）时，优先使用它。 - 所有文件和日志操作都会验证路径，确保路径位于工作区或 VS Code 日志目录内。路径中的 `.beans/` 前缀会被自动移除——传入 `some-bean.md` 或 `.beans/some-bean.md`，结果相同。 - `beans_update` 取代了许多细粒度的更新工具；调用方应使用它，以保持公开工具接口精简且可预测。 - `beans_archive` 提供与 CLI 一致的归档功能，可归档已完成或已废弃的 beans。 - 通过 `beans_update` 关闭父 bean（`status: completed` 或 `status: scrapped`）时，所有后代 bean 的状态也会级联更新为相同状态。 - 通过 `beans_reopen` 重新打开父 bean 时，目标状态会级联应用于已关闭的后代 bean（`completed` / `scrapped`）。 - `beans_bulk_create` 和 `beans_bulk_update` 采用尽力而为的方式：依次处理各项，并返回包含成功或错误条目的逐项结果数组，而非以原子方式失败。 - 写入时，Frontmatter 中的 `title:` 值会自动加上双引号。请传入原始标题——加引号和转义会自动处理。 - `beans_bean_file` 支持通过 `update_frontmatter` 仅对 Frontmatter 进行原子写入；支持的字段包括 `pr` 和 `branch`。 - 未筛选的列表结果会进行缓存，缓存采用较短的突发 TTL 和基于时间戳探测的刷新策略。变更工具（`beans_create`、`beans_update`、`beans_delete` 等）会立即使缓存失效。 - `beans-mcp` 与 Beans CLI 之间的版本不匹配只会产生警告，不会阻止操作；这是有意设计的。 - 当工具输入中缺少 `beanId` 时，验证错误会附带提示：`Did you mean \`beanId\`?`。beans_init
请求：
{ "prefix": "project" }
响应（structuredContent）：
{ "initialized": true }
beans_view
请求：
{ "beanId": "bean-abc" }
请求（多个 bean）：
{ "beanIds": ["bean-abc", "bean-def"] }
响应（structuredContent）：
{
"bean": {
"id": "bean-abc",
"title": "Fix login timeout",
"status": "todo",
"type": "bug",
"priority": "critical",
"body": "...markdown...",
"createdAt": "2025-12-01T12:00:00Z",
"updatedAt": "2025-12-02T08:00:00Z"
}
}
beans_archive
请求：
{}
响应（示例）：
{ "archived": true, "archivedCount": 3 }
beans_create
请求：
{
"title": "Add dark mode",
"type": "feature",
"status": "todo",
"priority": "normal",
"body": "Implement theme toggle and styles",
"parent": "epic-123"
}
description被接受为body的弃用别名。
响应（structuredContent）：
{
"bean": {
"id": "new-1",
"title": "Add dark mode",
"status": "todo",
"type": "feature"
}
}
beans_bulk_create
请求：
{
"parent": "epic-123",
"beans": [
{ "title": "Design mockups", "type": "task" },
{ "title": "Implement API", "type": "task", "priority": "high" },
{ "title": "Write tests", "type": "task", "parent": "epic-456" }
]
}
顶层的 parent 会作为默认值应用于未指定自身 parent 的 bean。此处，Design mockups 和 Implement API 被分配给 epic-123；Write tests 则覆盖该值，改为分配给 epic-456。
响应（structuredContent）：
{
"requestedCount": 3,
"successCount": 3,
"failedCount": 0,
"results": [
{ "bean": { "id": "task-1", "title": "Design mockups" } },
{ "bean": { "id": "task-2", "title": "Implement API" } },
{ "bean": { "id": "task-3", "title": "Write tests" } }
]
}
beans_bulk_update
请求（将一批任务移至进行中状态并分配给某个父项）：
{
"parent": "epic-123",
"beans": [
{ "beanId": "task-1", "status": "in-progress" },
{ "beanId": "task-2", "status": "in-progress" },
{ "beanId": "task-3", "status": "in-progress", "parent": "epic-456" }
]
}
响应（structuredContent）：
{
"requestedCount": 3,
"successCount": 3,
"failedCount": 0,
"results": [
{ "beanId": "task-1", "bean": { "id": "task-1", "status": "in-progress" } },
{ "beanId": "task-2", "bean": { "id": "task-2", "status": "in-progress" } },
{ "beanId": "task-3", "bean": { "id": "task-3", "status": "in-progress" } }
]
}
两种批量工具都采用尽力而为的方式：逐项报告部分失败，而不会中止整个批次。
beans_update
请求（更改状态并添加阻塞项）：
{
"beanId": "bean-abc",
"status": "in-progress",
"blocking": ["bean-def"],
"ifMatch": "etag-value"
}
请求（原子性地修改正文）：
{
"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."
}
注意：
body（完整替换）不能与bodyAppend或bodyReplace在同一个请求中组合使用。
响应（structuredContent）：
{
"bean": {
"id": "bean-abc",
"status": "in-progress",
"blockingIds": ["bean-def"]
}
}
beans_delete
请求：
{ "beanId": "bean-old", "force": false }
响应：
{ "deleted": true, "beanId": "bean-old" }
批量请求：
{ "beanIds": ["bean-old", "bean-older"], "force": false }
批量响应（摘要）：
{
"requestedCount": 2,
"deletedCount": 2,
"failedCount": 0,
"results": [
{ "beanId": "bean-old", "deleted": true },
{ "beanId": "bean-older", "deleted": true }
]
}
beans_reopen
请求：
{
"beanId": "bean-closed",
"requiredCurrentStatus": "completed",
"targetStatus": "todo"
}
响应：
{ "bean": { "id": "bean-closed", "status": "todo" } }
beans_complete_tasks
请求：
{ "beanId": "bean-abc" }
响应：
{
"bean": {
"id": "bean-abc",
"status": "todo"
},
"totalTaskCount": 5,
"updatedTaskCount": 3,
"unchangedTaskCount": 2
}
beans_query examples
刷新（列出所有 bean）：
{ "operation": "refresh" }
响应（部分）：
{ "count": 12, "beans": [] }
筛选（状态／类型／标签）：
{
"operation": "filter",
"statuses": ["in-progress", "todo"],
"types": ["bug", "feature"],
"tags": ["auth"]
}
搜索（全文）：
{ "operation": "search", "search": "authentication", "includeClosed": false }
排序（模式：status-priority-type-title、updated、created、id）：
{ "operation": "sort", "mode": "updated" }
就绪（仅限可执行的 bean）：
{ "operation": "ready" }
大模型上下文（生成 Copilot 指令；可选写入工作区）：
{ "operation": "llm_context", "writeToWorkspaceInstructions": true }
响应（structuredContent）：
{
"graphqlSchema": "...",
"generatedInstructions": "...",
"instructionsPath": "/workspace/.github/instructions/beans-prime.instructions.md"
}
原始 GraphQL 直通（CLI 与 beans query 保持一致）：
{
"operation": "graphql",
"graphql": "{ beans(filter: { type: [\"bug\"] }) { id title status } }"
}
带变量：
{
"operation": "graphql",
"graphql": "query($q: String!) { beans(filter: { search: $q }) { id title } }",
"variables": { "q": "authentication" }
}
beans_bean_file
请求（读取）：
{ "operation": "read", "path": "beans-vscode-123--title.md" }
响应：
{
"path": "/workspace/.beans/beans-vscode-123--title.md",
"content": "---\n...frontmatter...\n---\n# Title\n"
}
请求（原子性地更新 frontmatter）：
{
"operation": "update_frontmatter",
"path": "beans-vscode-123--title.md",
"fields": {
"status": "in-progress",
"pr": "123",
"branch": "feature/cascade-status-and-skills-npm"
}
}
响应：
{
"path": "/workspace/.beans/beans-vscode-123--title.md",
"bytes": 256,
"updatedFields": ["status", "pr", "branch"],
"frontmatter": {
"status": "in-progress",
"pr": "123",
"branch": "feature/cascade-status-and-skills-npm"
}
}
beans_output
请求（读取最后 200 行）：
{ "operation": "read", "lines": 200 }
响应：
{
"path": "/workspace/.vscode/logs/beans-output.log",
"content": "...log lines...",
"linesReturned": 200
}
编程方式使用
安装
npm install beans-mcp
示例
import { createBeansMcpServer, parseCliArgs } from '@voxslopuli/beans-mcp';
const server = await createBeansMcpServer({
workspaceRoot: '/path/to/workspace',
cliPath: 'beans', // or path to beans CLI
});
// Connect to stdio transport or your own transport
API
createBeansMcpServer(opts)
创建并初始化 Beans MCP 服务实例。
选项：
workspaceRoot（string）：Beans 工作区的路径cliPath（string，可选）：Beans CLI 可执行文件的路径（默认值：'beans'）name（string，可选）：服务名称（默认值：'beans-mcp-server'）version（string，可选）：服务版本logDir（string，可选）：服务日志目录backend（BackendInterface，可选）：自定义后端实现
返回值： { server: McpServer; backend: BackendInterface }
startBeansMcpServer(argv)
与 CLI 兼容的服务启动入口。
实用函数
parseCliArgs(argv: string[])：解析 CLI 参数isPathWithinRoot(root: string, target: string): boolean：检查路径是否位于根目录内sortBeans(beans, mode)：按指定模式对 bean 排序
类型和架构
导出 GraphQL 架构、Zod 验证架构，以及 Beans 记录和操作的 TypeScript 类型。
Agent Skills（skills-npm、skills.sh）
此软件包在 skills/ 下内置了一个 Agent Skill，同时也以适用于更广泛的开放技能生态系统的格式发布该技能，可通过 skills.sh 查看。
- 软件包中的技能路径：
skills/beans-mcp/SKILL.md - 已发布的技能文件：
https://beans-mcp.voxslopuli.org/.well-known/agent-skills/beans-mcp/SKILL.md - 已发布的发现索引：
https://beans-mcp.voxslopuli.org/.well-known/agent-skills/index.json - 兼容扫描以下路径的发现工具：
node_modules/**/skills/*/SKILL.md
这意味着你可以在基于 npm 的工作流（例如 skills-npm）中使用它，也可以将生态系统工具指向已发布的技能文件和发现索引，供 skills.sh 等技能目录使用。
若要将已安装的 npm 软件包中的技能符号链接到你的 Agent 工作区，可以在使用该技能的项目中使用 skills-npm。
许可证
MIT
评论
一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。