Beans MCP

MCP文档知识

提供方 The Self Agency LLC · 包名 @selfagency/beans-mcp@latest

文档知识 stdio · 本地进程 无需鉴权 社区 / 第三方 VS Code
查看接入方式

MCP (Model Context Protocol) server for Beans issue tracker. Provides programmatic and CLI interfaces for AI-powered interactions with Beans workspaces.

一句话选型结论

按资料字段整理

Beans MCP 属于文档知识类 MCP 服务器,stdio · 本地进程,无需鉴权,可直接接入 VS Code,有可直接执行的安装命令。接入前先确认权限范围;涉及写入、删除或付款的操作,建议先在测试环境验证。

分类文档知识 传输方式stdio · 本地进程 鉴权无需鉴权 部署方式本地部署
GitHub 星标 0 仓库热度,无公开仓库时显示未标注
工具数 13 暴露给模型的工具数量
资源 / 提示词 0 / 0 资源与提示词模板数量
维护方 社区 / 第三方 核验等级 仅资料核对

工具与能力

文档知识
数量来自来源目录的标注,具体工具清单以官方文档为准
工具数量13暴露给模型可调用的工具个数
资源数量0可读取的资源条目
提示词数量0内置提示词模板数量

能力标签

支持客户端

适用场景

beansissue-trackerissuesmarkdownmemory问题跟踪TypeScript本地部署

安装与配置

stdio · 本地进程 无需鉴权
客户端在本机拉起子进程,数据不出本机
npx -y @selfagency/beans-mcp@latest /path/to/your/repo

这条命令只是入口,具体启动参数请按官方文档补齐,不要直接照搬到别的服务器。

  1. 1
    准备运行环境

    stdio 服务在本地起进程,需要先装好 Node.js,再按安装命令拉取依赖。

  2. 2
    安装服务

    复制上面的安装命令执行;命令里带占位符的位置,换成自己的密钥或路径。

  3. 3
    写入客户端配置

    在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,让新配置生效。

  4. 4
    验证是否可用

    连接成功后客户端会列出约 13 个工具,随便调一个只读工具确认能返回结果。

典型使用场景

3 类
按分类与标签整理的常见用法,具体以官方文档为准
文档检索问答

在你的文档库里按问题找答案。

知识库读写

把新资料写进知识库,随用随取。

内容整理

把零散资料归纳成结构化笔记。

选择建议

选之前先看这几条
按条目字段给出的判断,不替你决定用不用

值得选的地方

  • 资料标注 13 个工具,覆盖面较广,能满足多种调用。
  • 有现成的安装命令,不用自己找入口,照着跑就能起服务。
  • 已适配 VS Code,换客户端不用重新研究配置。
  • 资料标注无需鉴权,装好就能连。

先想清楚的地方

  • stdio 方式要求本地装好运行时(如 Node.js),换机器要重新装一遍。
  • 版本更新与行为细节以官方仓库为准。

更适合

  • 需要在文档知识场景里让模型直接调用外部能力的人。
  • 已经在用 VS Code 的用户,接入路径最短。
  • 想先快速试一下、能接受在本地或自有环境跑服务的人。

不太适合

  • 完全不想在本地装环境的人。
  • 需要厂商级 SLA 和技术支持的生产环境。

同类对比

6 个同类
同分类里挑最接近的几条,字段以各自详情页为准
MCP 服务器工具数传输方式部署方式安装命令最后核验
Beans MCP当前 13 stdio · 本地进程 本地部署 有 2026-05-18
dify 未标注 stdio · 本地进程 本地部署 有 2026-04-11
open-webui 未标注 stdio · 本地进程 本地部署 有 2026-04-11
JeecgBoot 未标注 stdio · 本地进程 本地部署 有 2026-04-11
Cherry Studio 未标注 未标注 未标注 无 2026-05-17
mempalace 未标注 stdio · 本地进程 本地部署 有 2026-04-11

服务器档案

文档知识
字段来自项目仓库与公开索引,中文说明由本站标注
提供方The Self Agency LLC上游标注的维护方 The Self Agency LLC
分类文档知识本站按上游分类展示
连接方式stdio · 本地进程客户端在本机拉起子进程,数据不出本机
鉴权方式无需鉴权远程服务建议用最小权限凭据
维护方社区 / 第三方核验等级 仅资料核对
包名 / 运行时@selfagency/beans-mcp@latest · Node.js本地安装时用到的包标识与运行时
部署类型本地部署上游给出的部署形态
最近核验2026-05-18上游最后核验时间

详细介绍

13.7 KB
来自项目仓库与上游目录的原文,未做删改

@自营/豆类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 在你的消费项目中。

许可证

麻省理工学院

常见问题

8 问
答案由本站依据条目字段整理,不引用上游原文
Beans MCP 怎么安装?

在客户端按下面的安装命令接入:npx -y @selfagency/beans-mcp@latest /path/to/your/repo。对应的包名是 @selfagency/beans-mcp@latest。装完在客户端配置里引用同一个包或端点。

Beans MCP 怎么在 VS Code 里配置?

它的传输方式是stdio · 本地进程,在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,配置才会生效。

Beans MCP 收费吗?

本站不代收费用,也没有标注具体价格。是否收费取决于服务本身和背后的接口额度,正式使用前按官方说明确认。

Beans MCP 需要 API Key 吗?

资料标注为无需认证,装好就能连;如果实际调用时报鉴权错误,按官方文档补上凭据。

Beans MCP 支持哪些客户端?

资料标注支持 VS Code;其他客户端只要能配置 MCP Server,也能用同样的命令或地址接入。

Beans MCP 能提供哪些能力?

资料显示约 13 个工具;能力标签包括 问题跟踪、TypeScript、VS Code、工作区管理。具体工具清单以官方文档为准。

Beans MCP 需要什么运行环境?

运行时为 Node.js;属于本地进程,需要在本机装好运行环境。

Beans MCP 是本地还是远程?

它是本地进程(stdio),由客户端在本机拉起。传输方式为stdio · 本地进程。

热门专题

按标签挑服务器
全部专题 →

服务器信息以作者仓库与官方文档为准;分类、传输方式与鉴权方式的中文说明为中文整理,最近核验 2026-05-18。