@自营/豆类mcp🫘
MCP(模型上下文协议)服务器 豆 问题跟踪器。为与Beans工作区的AI交互提供编程和CLI接口。
文档: beans-mcp.self代理商
> 🤖 在VS Code中尝试与GitHub Copilot完全集成的Beans!安装 self-agency.beans-vscode 扩展。
用法```bash
npx @selfagency/beans-mcp /path/to/workspace
### 版本控制
`@selfagency/beans-mcp` 有自己的包版本控制。与的兼容性
豆 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` |归档已完成/报废的豆子。 |
| `beans_view` |按以下方式获取全豆详细信息 `beanId` 或 `beanIds`. |
| `beans_create` |创建一个新的bean(标题/类型+可选的主体/父对象)。 |
| `beans_bulk_create` |在一次调用中创建多个bean,可以选择在共享父级下创建。 |
| `beans_update` |合并元数据+正文更新(状态/类型/优先级/父级/清除父级/阻塞/阻塞由/body/bodyAppend/bodyReplace)以及可选的乐观并发提示(`ifMatch`). |
| `beans_bulk_update` |在一次调用中更新多个bean,可以选择将它们重新分配给共享父级。 |
| `beans_complete_tasks` |将bean中的所有markdown检查表任务标记为已完成。 |
| `beans_delete` |删除一个或多个bean(`beanId` 或 `beanIds`,可选 `force`). |
| `beans_reopen` |将已完成或报废的bean重新打开到活动状态。 |
| `beans_query` |使用GraphQL passthrough统一列表/搜索/过滤/排序/就绪操作。 |
| `beans_bean_file` |读取/编辑/创建/删除以下文件 `.beans`. |
| `beans_output` |阅读扩展输出日志或显示指导。 |
Notes
- 这 `beans_query` 该工具故意设计得很宽泛:更喜欢它用于列出、搜索、过滤或排序bean,以及生成Copilot指令(`operation: 'llm_context'`).
- 所有文件和日志操作都会验证路径,以将其保存在工作区或VS Code日志目录中。这 `.beans/` 前缀会自动从路径中删除——您可以传递 `some-bean.md` 或 `.beans/some-bean.md` 结果是一样的。
- `beans_update` 取代了许多细粒度的更新工具;调用者应该使用它来保持公共工具表面较小且可预测。
- `beans_archive` 为归档已完成/报废的bean提供CLI奇偶校验。
- 通过以下方式关闭父bean `beans_update` (`status: completed` 或 `status: scrapped`)将相同的状态逐级传递给所有后代。
- 通过以下方式重新打开父bean `beans_reopen` 将目标状态级联到已关闭的子体(`completed` / `scrapped`).
- `beans_bulk_create` 和 `beans_bulk_update` 尽最大努力:它们按顺序处理每个项目,并返回每个项目的结果数组,其中包含成功/错误条目,而不是原子性地失败。
- 前言 `title:` 值在写入时自动双引号。传递原始标题——为您处理引用和转义。
- `beans_bean_file` 支持 `update_frontmatter` 因为原子前体只写;支持的字段包括 `pr` 和 `branch`.
- 未过滤的列表结果使用短突发TTL和时间戳探测刷新策略进行缓存。突变工具(`beans_create`, `beans_update`, `beans_delete`等等)立即使缓存无效。
- 版本不匹配 `beans-mcp` Beans CLI的设计是仅警告和非阻塞的。
- 当 `beanId` 工具输入中缺少,验证错误包括提示: `Did you mean \`是吗?\`.
## 示例
beans_init
请求:```json
{ "prefix": "project" }
响应(结构化内容):```json
{ "initialized": true }
beans_view
请求:```json
{ "beanId": "bean-abc" }
请求(多个bean):```json
{ "beanIds": ["bean-abc", "bean-def"] }
响应(结构化内容):```json
{
"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
请求:```json
{}
响应(示例):```json
{ "archived": true, "archivedCount": 3 }
beans_create
请求:```json
{
"title": "Add dark mode",
"type": "feature",
"status": "todo",
"priority": "normal",
"body": "Implement theme toggle and styles",
"parent": "epic-123"
}
> `description` 被接受为已弃用的别名 `body`.
响应(结构化内容):```json
{
"bean": {
"id": "new-1",
"title": "Add dark mode",
"status": "todo",
"type": "feature"
}
}
beans_bulk_create
请求:```json
{
"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` 作为默认值应用于任何未指定自己的bean `parent`在这里 `Design mockups` 和 `Implement API` 被分配给 `epic-123`; `Write tests` 覆盖与 `epic-456`.
响应(结构化内容):```json
{
"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
请求(将一批任务移动到正在进行中,并将其分配给父任务):```json
{
"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" }
]
}
响应(结构化内容):```json
{
"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
请求(更改状态并添加阻止):```json
{
"beanId": "bean-abc",
"status": "in-progress",
"blocking": ["bean-def"],
"ifMatch": "etag-value"
}
请求(原子体修改):```json
{
"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 在同一个请求中。
响应(结构化内容):```json
{
"bean": {
"id": "bean-abc",
"status": "in-progress",
"blockingIds": ["bean-def"]
}
}
beans_delete
请求:```json
{ "beanId": "bean-old", "force": false }
答复:```json
{ "deleted": true, "beanId": "bean-old" }
批量请求:```json
{ "beanIds": ["bean-old", "bean-older"], "force": false }
批量响应(摘要):```json
{
"requestedCount": 2,
"deletedCount": 2,
"failedCount": 0,
"results": [
{ "beanId": "bean-old", "deleted": true },
{ "beanId": "bean-older", "deleted": true }
]
}
beans_reopen
请求:```json
{
"beanId": "bean-closed",
"requiredCurrentStatus": "completed",
"targetStatus": "todo"
}
答复:```json
{ "bean": { "id": "bean-closed", "status": "todo" } }
beans_complete_tasks
请求:```json
{ "beanId": "bean-abc" }
答复:```json
{
"bean": {
"id": "bean-abc",
"status": "todo"
},
"totalTaskCount": 5,
"updatedTaskCount": 3,
"unchangedTaskCount": 2
}
beans_query examples
刷新(列出所有bean):```json
{ "operation": "refresh" }
回复(部分):```json
{ "count": 12, "beans": [] }
筛选器(状态/类型/标签):```json
{
"operation": "filter",
"statuses": ["in-progress", "todo"],
"types": ["bug", "feature"],
"tags": ["auth"]
}
搜索(全文):```json
{ "operation": "search", "search": "authentication", "includeClosed": false }
排序(模式: `status-priority-type-title`, `updated`, `created`, `id`):```json
{ "operation": "sort", "mode": "updated" }
准备就绪(仅限可操作的bean):```json
{ "operation": "ready" }
LLM上下文(生成复制指令;可选写入工作区):```json
{ "operation": "llm_context", "writeToWorkspaceInstructions": true }
响应(结构化内容):```json
{
"graphqlSchema": "...",
"generatedInstructions": "...",
"instructionsPath": "/workspace/.github/instructions/beans-prime.instructions.md"
}
原始GraphQL传递(CLI与 `beans query`):```json
{
"operation": "graphql",
"graphql": "{ beans(filter: { type: [\"bug\"] }) { id title status } }"
}
变量:```json
{
"operation": "graphql",
"graphql": "query($q: String!) { beans(filter: { search: $q }) { id title } }",
"variables": { "q": "authentication" }
}
beans_bean_file
请求(阅读):```json
{ "operation": "read", "path": "beans-vscode-123--title.md" }
答复:```json
{
"path": "/workspace/.beans/beans-vscode-123--title.md",
"content": "---\n...frontmatter...\n---\n# Title\n"
}
请求(原子前沿物质更新):```json
{
"operation": "update_frontmatter",
"path": "beans-vscode-123--title.md",
"fields": {
"status": "in-progress",
"pr": "123",
"branch": "feature/cascade-status-and-skills-npm"
}
}
答复:```json
{
"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行):```json
{ "operation": "read", "lines": 200 }
答复:```json
{
"path": "/workspace/.vscode/logs/beans-output.log",
"content": "...log lines...",
"linesReturned": 200
}
## 程序化使用
### 安装```bash
npm install beans-mcp
示例```typescript
import { 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
```
API
创建BeansMcpServer(选项)
创建并初始化Beans MCP服务器实例。
选项:
workspaceRoot(string):Beans工作区的路径cliPath(字符串,可选):Beans CLI可执行文件的路径(默认:“Beans”)name(字符串,可选):服务器名称(默认值:“beans mcp Server”)version(字符串,可选):服务器版本logDir(字符串,可选):服务器日志目录backend(后端接口,可选):自定义后端实现
退货:
{ server: McpServer; backend: BackendInterface }
startBeansMcpServer(argv)
用于启动服务器的CLI兼容入口点。
工具函数
parseCliArgs(argv: string[]):解析CLI参数isPathWithinRoot(root: string, target: string): boolean:检查路径是否包含在根目录中sortBeans(beans, mode):按指定模式对bean进行排序
类型和模式
导出用于Beans记录和操作的GraphQL模式、Zod验证模式和TypeScript类型。
代理技能(skills-npm, skills.sh)
此软件包附带了内置的代理技能 skills/ 并以适合更广泛的开放技能生态系统的格式发布该技能 技能s.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 在你的消费项目中。
许可证
麻省理工学院
