用于 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.
MCP server for Linear project management and issue tracking
Remote MCP server for supportsheep: run AI interviews and manage support content for your blog.
Kaiku is an issue tracker with a wiki, built so that people and AI agents work in the same place. Its hosted MCP server lets an agent search, read, file and update issues, comment and answer questions, read and write wiki pages, and attach files — with the permissions of the person whose token it uses. Create a token in Settings → Connect over MCP and send it as Authorization: Bearer <token> (or in X-Api-Key); the token says which workspace.
