用于 Beans 问题追踪器的 MCP（模型上下文协议）服务器。提供程序化与 CLI 接口，支持与 Beans 工作区进行 AI 驱动的交互。
🤖 在 VS Code 中尝试 Beans 与 GitHub Copilot 的完整集成！安装 selfagency.beans-vscode 扩展。
npx @selfagency/beans-mcp /path/to/workspace@selfagency/beans-mcp 拥有自己的包版本号。与 Beans CLI 的兼容性单独跟踪。
启动时，服务器会对比已安装的 beans CLI 版本与硬编码的支持版本：0.4.2。如果两者不同，会在 stderr 输出警告，然后继续启动。
--workspace-root 或位置参数：工作区根路径
--cli-path：Beans CLI 路径
--port：MCP 服务器端口（默认：39173）
--log-dir：日志目录
-h、--help：打印用法并退出
Related MCP server: jira-cli-mcp
工具 | 描述 |
| 初始化工作区（可选 |
| 归档已完成/废弃的 beans。 |
| 通过 |
| 创建新 bean（标题/类型 + 可选 body/parent）。 |
| 一次调用创建多个 beans，可选共享父级。 |
| 合并元数据 + body 更新（status/type/priority/parent/clearParent/blocking/blockedBy/body/bodyAppend/bodyReplace），外加可选乐观并发提示（ |
| 一次调用更新多个 beans，可选将其重新分配至共享父级。 |
| 将 bean 内的所有 Markdown 清单任务标记为已完成。 |
| 删除一个或多个 beans（ |
| 将已完成或废弃的 bean 重新打开为活动状态。 |
| 统一的列表/搜索/筛选/排序/就绪操作，支持 GraphQL 透传。 |
| 读取/编辑/创建/删除 |
| 读取扩展输出日志或显示指南。 |
beans_query 工具特意设计得很宽泛：优先用于列举、搜索、筛选或排序 beans，以及生成 Copilot 指令（operation: 'llm_context'）。
所有文件与日志操作都会验证路径，确保其位于工作区或 VS Code 日志目录内。.beans/ 前缀会自动从路径中移除——你可以传入 some-bean.md 或 .beans/some-bean.md，结果相同。
beans_update 取代了许多细粒度更新工具；调用方应使用它来保持公开工具表面小而可预测。
beans_archive 提供归档已完成/废弃 beans 的 CLI 对等操作。
通过 beans_update 关闭父 bean（status: completed 或 status: scrapped）会级联相同状态至所有后代。
通过 beans_reopen 重新打开父 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 时，验证错误会包含提示：你的意思是 \beanId` 吗？`
请求：
{ "prefix": "project" }响应（结构化内容）：
{ "initialized": true }请求：
{ "beanId": "bean-abc" }请求（多个 beans）：
{ "beanIds": ["bean-abc", "bean-def"] }响应（结构化内容）：
{
"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"
}
}请求：
{}响应（示例）：
{ "archived": true, "archivedCount": 3 }请求：
{
"title": "Add dark mode",
"type": "feature",
"status": "todo",
"priority": "normal",
"body": "Implement theme toggle and styles",
"parent": "epic-123"
}
description被接受为body的废弃别名。
响应（结构化内容）：
{
"bean": {
"id": "new-1",
"title": "Add dark mode",
"status": "todo",
"type": "feature"
}
}请求：
{
"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 覆盖。
响应（结构化内容）：
{
"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" } }
]
}请求（将一批任务移至进行中并分配给一个父级）：
{
"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" }
]
}响应（结构化内容）：
{
"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" } }
]
}两个批量工具都是尽力而为的：部分失败会按条目报告，而非中止整个批次。
请求（更改状态并添加阻塞）：
{
"beanId": "bean-abc",
"status": "in-progress",
"blocking": ["bean-def"],
"ifMatch": "etag-value"
}请求（原子性 body 修改）：
{
"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在同一请求中组合使用。
响应（结构化内容）：
{
"bean": {
"id": "bean-abc",
"status": "in-progress",
"blockingIds": ["bean-def"]
}
}请求：
{ "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 }
]
}请求：
{
"beanId": "bean-closed",
"requiredCurrentStatus": "completed",
"targetStatus": "todo"
}响应：
{ "bean": { "id": "bean-closed", "status": "todo" } }请求：
{ "beanId": "bean-abc" }响应：
{
"bean": {
"id": "bean-abc",
"status": "todo"
},
"totalTaskCount": 5,
"updatedTaskCount": 3,
"unchangedTaskCount": 2
}刷新（列出所有 beans）：
{ "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" }就绪（仅可操作的 beans）：
{ "operation": "ready" }LLM 上下文（生成 Copilot 指令；可选写入工作区）：
{ "operation": "llm_context", "writeToWorkspaceInstructions": true }响应（结构化内容）：
{
"graphqlSchema": "...",
"generatedInstructions": "...",
"instructionsPath": "/workspace/.github/instructions/beans-prime.instructions.md"
}原始 GraphQL 透传（与 beans query 的 CLI 对等）：
{
"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" }
}请求（读取）：
{ "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"
}
}请求（读取最后 200 行）：
{ "operation": "read", "lines": 200 }响应：
{
"path": "/workspace/.vscode/logs/beans-output.log",
"content": "...log lines...",
"linesReturned": 200
}npm install beans-mcpimport { createBeansMcpServer, parseCliArgs } from '@selfagency/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创建并初始化一个 Beans MCP 服务器实例。
选项：
workspaceRoot（字符串）：Beans 工作区路径
cliPath（字符串，可选）：Beans CLI 可执行文件路径（默认：'beans'）
name（字符串，可选）：服务器名称（默认：'beans-mcp-server'）
version（字符串，可选）：服务器版本
logDir（字符串，可选）：服务器日志目录
backend（BackendInterface，可选）：自定义后端实现
返回： { server: McpServer; backend: BackendInterface }
用于启动服务器的 CLI 兼容入口点。
parseCliArgs(argv: string[])：解析 CLI 参数
isPathWithinRoot(root: string, target: string): boolean：检查路径是否包含在根目录内
sortBeans(beans, mode)：按指定模式对 beans 排序
导出 GraphQL 模式、Zod 验证模式以及 Beans 记录和操作的 TypeScript 类型。
skills-npm、skills.sh）此包附带一个内置代理技能，位于 skills/ 下，并且还以适合 skills.sh 展示的更广泛开放技能生态系统的格式发布了该技能。
包内技能路径：skills/beans-mcp/SKILL.md
已发布的技能工件：https://beans-mcp.self.agency/.well-known/agent-skills/beans-mcp/SKILL.md
已发布的发现索引：https://beans-mcp.self.agency/.well-known/agent-skills/index.json
兼容扫描 node_modules/**/skills/*/SKILL.md 的发现工具
这意味着你可以将其与基于 npm 的工作流（如 skills-npm）一起使用，同时也可以将生态系统工具指向由技能目录（如 skills.sh）使用的已发布技能工件和发现索引。
要将已安装的 npm 打包技能符号链接到你的代理工作区，可以在消费项目中使用 skills-npm。
MIT
This server cannot be deployed
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Official Fibery MCP server: query and update your workspace from any AI client via OAuth.
Official Duck Framework MCP server for AI-assisted development and project scaffolding.
Remote MCP server for supportsheep: run AI interviews and manage support content for your blog.
