Beans MCP

@自营/豆类mcp🫘

MCP（模型上下文协议）服务器 豆 问题跟踪器。为与Beans工作区的AI交互提供编程和CLI接口。

文档： beans-mcp.self代理商

🤖 在VS Code中尝试与GitHub Copilot完全集成的Beans！安装 self-agency.beans-vscode 扩展。

用法

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工具概述

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

请求：

{ "prefix": "project" }

响应（结构化内容）：

{ "initialized": true }

beans_view

请求：

{ "beanId": "bean-abc" }

请求（多个bean）：

{ "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"
  }
}

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.

响应（结构化内容）：

{
  "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 作为默认值应用于任何未指定自己的bean parent在这里 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" } }
  ]
}

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" }
  ]
}

响应（结构化内容）：

{
  "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 在同一个请求中。

响应（结构化内容）：

{
  "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" }

LLM上下文（生成复制指令；可选写入工作区）：

{ "operation": "llm_context", "writeToWorkspaceInstructions": true }

响应（结构化内容）：

{
  "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"
}

请求（原子前沿物质更新）：

{
  "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 '@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 在你的消费项目中。

许可证

麻省理工学院