Beads 的 MCP Server 集成指南在无 Shell 环境中让 Coding Agent 使用 bd 管理任务【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beadsBeadsbd是一个为编码代理Coding Agent设计的事务型 Issue 追踪器与代理记忆系统正常情况下通过 CLI Hooks 接入 Claude Code、Cursor 等具备 Shell 访问能力的环境。但在 Claude Desktop、Sourcegraph Amp 等仅 MCPModel Context Protocol环境中没有 Shell 可用此时需要依赖本仓库 integrations/beads-mcp 提供的beads-mcpMCP Server。本文将以 docs/integrations/mcp-server.md 为主线结合 beads-mcp 源码 完整讲解 MCP Server 的安装、配置、工具集、上下文工程优化、多仓库路由与排障方法。读完本文你将掌握如何在 MCP-only 环境中把 Beads 的查、建、认领、依赖、评论能力接入任意 MCP 客户端并理解其底层如何把 MCP 工具翻译成bd命令。何时该用 MCP Server何时该用 CLI Hooks先明确选择边界有 Shell 的环境优先用 CLI Hooks因为 CLI 直连bd更省上下文约 1–2k tokens且延迟更低无 Shell 的 MCP-only 环境才使用 MCP Server。典型场景包括Claude Desktop无 Shell 访问能力Sourcegraph Amp无 Shell 的 MCP 环境其他任何只暴露 MCP 协议、不允许执行 CLI 的宿主。beads-mcp的定位在 README 中写得很清楚它通过 Model Context Protocol 让 AI 代理用bdCLI 管理任务是 CLI 不可用时的替代接入方式。MCP 方案存在协议层开销上下文 10–50k tokens因此仅在必要时选用。安装 beads-mcpbeads-mcp是一个发布到 PyPI 的 Python 包项目元数据见 pyproject.toml当前版本 1.2.2要求 Python ≥ 3.10依赖fastmcp、pydantic、pydantic-settings提供beads-mcp控制台入口对应beads_mcp.server:main。使用 uv 安装推荐uv tool install beads-mcp使用 pip 安装pip install beads-mcp安装后确认可执行文件可用which beads-mcp前置条件MCP Server 本身只是翻译层实际读写操作全部委托给bdCLI。因此目标机器上必须已安装bd参考 scripts/install.sh 的安装方式。从源码看config.pybeads-mcp启动时会先查找 PATH 中的bd找不到再回退到~/.local/bin/bd并在校验失败时给出安装指引。开发模式安装需要调试 MCP Server 自身时可在仓库内开发安装git clone https://gitcode.com/GitHub_Trending/beads1/beads cd beads/integrations/beads-mcp uv sync然后在 MCP 客户端配置中用uv启动{ mcpServers: { beads: { command: uv, args: [--directory, /path/to/beads-mcp, run, beads-mcp] } } }各 MCP 客户端的配置方法beads-mcp通过 stdio 传输运行server.py 中mcp.run_async(transportstdio)所有客户端配置本质上都是让宿主拉起beads-mcp进程。Claude DesktopmacOS编辑~/Library/Application Support/Claude/claude_desktop_config.json{ mcpServers: { beads: { command: beads-mcp } } }Claude DesktopWindows编辑%APPDATA%\Claude\claude_desktop_config.json内容同上。Sourcegraph Amp在 MCP 设置中添加{ beads: { command: beads-mcp, args: [] } }VS Code / GitHub Copilot在项目根目录创建.vscode/mcp.json{ servers: { beads: { command: beads-mcp } } }对全部项目生效将配置写入 VS Code 用户级 MCP 配置各平台路径如下平台路径macOS~/Library/Application Support/Code/User/mcp.jsonLinux~/.config/Code/User/mcp.jsonWindows%APPDATA%\Code\User\mcp.json{ servers: { beads: { command: beads-mcp, args: [] } } }注意VS Code 用户级 MCP 需要 VS Code 1.96 并启用 MCP 支持。GitHub Copilot 的完整接入教程见 docs/integrations/github-copilot.md。环境变量全部可选beads-mcp通过环境变量注入配置config.py 中Config(BaseSettings)逐项读取并校验环境变量作用默认值BEADS_PATHbd可执行文件路径先查 PATH回退~/.local/bin/bdBEADS_DIR.beads目录路径推荐自动发现从工作目录向上查找BEADS_DB数据库文件路径已弃用优先用BEADS_DIR自动发现BEADS_WORKING_DIRbd命令的工作目录用于多仓库场景$PWD或当前目录BEADS_ACTOR审计追踪中的操作者名称$USERBEADS_NO_AUTO_FLUSH禁用自动 JSONL 同步falseBEADS_NO_AUTO_IMPORT禁用自动 JSONL 导入false这些变量会被客户端BdCliClient拼成bd的全局参数--actor、--no-auto-flush、--no-auto-import详见 bd_client.py。数据库路由的优先级是BEADS_DIRBEADS_DB 自动发现。可用工具全景beads-mcp把bd的核心能力封装为 MCP 工具。官方文档列出的工具总览工具说明ready显示可认领的工作无阻塞依赖list带筛选地列出 Issueshow查看 Issue 详情、依赖与反向依赖create创建新 Issueclaim原子化认领 Issueupdate更新 Issueclose/reopen关闭 / 重新打开 Issuedep管理依赖关系comment/comments添加 / 列出评论note追加到 Issue 的 notes 字段blocked显示被阻塞的 Issue 及其阻塞者stats/context数据库统计 / 工作区上下文admin管理运维操作discover_tools/get_tool_info工具发现与 Schema 查询注意MCP 没有同步sync工具——同步仍由 CLI 完成bd dolt push/bd dolt pull。这是因为 Dolt 后端同步涉及服务器进程与认证不适合放在无 Shell 的 MCP 通道里。常用工具的完整参数从 server.py 的get_tool_info实现可提取每个工具的完整参数这也是 MCP 内get_tool_info(tool_name)的返回内容readylimit1–100默认 10、priority0–4、issue_typetask/bug/feature/epic/chore/decision/merge-request 或自定义、assignee、labelsAND、labels_anyOR、unassigned、sort_policyhybrid/priority/oldest、brief、fields、max_description_length。示例ready(limit5, priority1, unassignedTrue)。liststatusopen/in_progress/blocked/deferred/closed 或自定义、priority、issue_type、assignee、labels、labels_any、query标题不区分大小写子串搜索、unassigned、limit默认 20、brief、fields、max_description_length。示例list(statusopen, labels[bug], queryauth)。showissue_id必填如bd-a1b2、brief、brief_deps完整 Issue 紧凑依赖、fields、max_description_length。示例show(issue_idbd-a1b2, brief_depsTrue)。createtitle必填、description、priority0–4默认 2、issue_type默认 task、assignee、labels、deps依赖 ID 列表、brief默认 true返回精简确认而非完整 Issue、workspace_root。示例create(titleFix auth bug, priority1, issue_typebug)。claimissue_id必填、brief默认 true。示例claim(issue_idbd-a1b2)。底层对应bd update id --claim在一次比较并交换CAS操作中同时设置 assignee in_progress已被认领会失败bd_client.py。updateissue_id必填、status、priority、assignee、title、description、brief默认 true。示例update(issue_idbd-a1b2, statusblocked)。特殊路由statusclosed会自动转向close工具、statusopen自动转向reopen工具以确保审批工作流被遵守。closeissue_id必填、reason默认 Completed。示例close(issue_idbd-a1b2, reasonFixed in PR #123)。reopenissue_ids必填列表、reason可选。示例reopen(issue_ids[bd-a1b2], reasonNeed more work)。depissue_id依赖方、depends_on_id被依赖方、dep_type默认 blocks。示例dep(issue_idbd-f1a2, depends_on_idbd-a1b2, dep_typeblocks)。常见类型blocks硬阻塞、related软关联、parent-child史诗/子任务、discovered-from工作中发现的新任务。完整依赖类型集合定义在 internal/types/types.go由bdCLI 校验MCP 层以字符串透传以保持解耦models.py。comment/commentscomment(issue_id, text)追加一条带时间戳的持久化评论人类无需阅读代理转录即可了解进展comments(issue_id)按时间顺序列出评论——注意show只报告comment_count而不返回评论正文。notenote(issue_id, text)向 Issue 的 notes 字段追加文本。注释强调逐轮工作记录优先用comment因为评论是累积的时间戳轨迹而 notes 是会被整体替换的单个字段。blockedbrief、brief_deps。返回被阻塞的 Issue 及阻塞来源。statsworkspace_root可选。返回总数、open、in_progress、closed、blocked、ready 数量及平均交付周期小时。adminaction必填为validate/repair/schema/debug/migration/pollution之一另带checks、fix_all、fix、clean参数validate数据库健康检查orphans/duplicates/pollution/conflictsfix_allTrue自动修复repair修复指向不存在 Issue 的孤儿依赖fixTrue执行删除schema展示当前数据库表结构、schema 版本与示例 IDdebug输出工作目录与全部BEADS_*环境变量migration输出迁移计划与数据库状态供代理在迁移前分析pollution检测混入生产库的测试 Issue标题以 test/benchmark/sample/tmp/temp 开头、连续编号、快速创建等模式cleanTrue删除。contextactionset/show/init省略时按参数推断有workspace_root则 set否则 show、workspace_root、prefix。context(actionset, workspace_root...)设置持久化工作区context(actioninit, ...)在已设上下文后初始化bd。discover_tools/get_tool_info前者返回仅含工具名与一句话说明的轻量目录约 500 字节后者返回指定工具的完整参数、返回值与示例。资源beads://quickstartbd快速上手指南资源代理可先读取它理解如何使用对应bd quickstart实现于 server.py 的mcp.resource注册。使用方式自然语言驱动配置完成后无需特殊语法代理直接用自然语言即可。例如Create an issue for fixing the login bug with priority 1MCP Server 会将其翻译为适当的bd命令。翻译映射关系在 bd_client.py 中逐方法对应例如beads_list_issues拼出bd list --status ... --priority ... --type ... --assignee ... --label ... --limit ...并追加全局--json标志解析输出beads_create_issue拼出bd create title -p priority -t type [-d description] [-l label] [--deps ...]claim对应bd update id --claimcomment/note使用不输出 JSON 的bd comment/bd note文本子命令。每个子进程都以stdinDEVNULL启动并显式传入cwd避免继承 MCP 自身的 stdio 通道这是 MCP 协议下 subprocess 调用的关键细节。上下文工程为代理省 Token 的设计beads-mcp在 v0.24.0 起引入了一套上下文工程优化把 MCP 方案的上下文开销从约 10–50k tokens 压到约 2–5k tokens这是其核心设计亮点见 server.py 头部注释。惰性工具 Schema 加载discover_tools()只返回工具名与简介约 500 字节get_tool_info(name)按需返回单个工具的完整 Schema。代理不必在会话开始时加载全部工具 Schema。最小化 Issue 模型约 80% 缩减列表类操作默认返回IssueMinimalid、title、status、priority、type、assignee、labels、依赖计数而非完整Issue。需要完整细节含依赖时再调用show(issue_id)。模型定义见 models.pyIssueMinimal、BriefIssue4 字段约小 95%、BriefDep5 字段约小 90%、OperationResult写操作确认约小 97%。大结果集自动压实Compaction当结果数超过阈值时返回CompactedResultcompactedtrue、total_count、前 N 条preview和提示文本而不是完整列表。两个阈值可用环境变量覆盖server.py 的_get_compaction_settingsBEADS_MCP_COMPACTION_THRESHOLD触发压实的条数默认 20须 ≥1BEADS_MCP_PREVIEW_COUNT预览条数默认 5须 ≥1 且 ≤ 阈值。按需截断描述max_description_length参数可按需截断 Issue 描述避免长文本撑爆上下文。精简字段投影fields参数只返回指定字段VALID_ISSUE_FIELDS白名单校验brief/brief_deps提供不同粒度的紧凑格式。多仓库与多项目支持一个 MCP Server 实例可以服务多个 Beads 项目采用类似 LSPLanguage Server Protocol的架构MCP Server单个实例 ↓ Per-Project Dolt Servers每个工作区一个 ↓ Dolt 数据库完全隔离推荐配置单一 MCP Server 自动路由。MCP Server 自动检测当前工作区的 Beads 项目并路由到对应的 per-project Dolt server每个项目拥有独立、隔离的 Dolt 数据库避免跨项目污染与 git worktree 冲突一份 MCP 配置即可服务无限数量的项目。替代方案不推荐为每个项目启动一个 MCP 实例用BEADS_WORKING_DIR固定工作区。风险是代理可能选错 MCP server导致命令作用在错误的数据库上因此官方明确不推荐。按请求路由workspace_root参数每个工具都接受可选workspace_root参数做显式项目定位。底层机制server.py 的with_workspace装饰器 tools.py 的ContextVar每次工具调用把workspace_root写入请求级ContextVar调用结束立即重置从而支持并发请求互不串扰未传参时按workspace_root参数 持久化BEADS_WORKING_DIR 环境变量 自动发现的顺序回退。工作区发现逻辑tools.py 的_find_beads_db_in_tree与 Go CLI 保持一致从当前目录逐级向上查找.beads支持.beads/redirect重定向文件agent/worker 共享数据库的场景、symlink 解析realpath、git worktree 边界不越过当前 repo/worktree、子模块独立.beads判定。后端类型检测server.py 的_detect_backend通过metadata.json区分 sqlite / dolt-embedded / dolt-server。连接池tools.py 的_connection_pool按规范化后的工作区路径缓存客户端每次复用前做健康检查失效连接自动丢弃并以指数退避0.1s、0.2s、0.4s重连首次连接每个工作区会做一次bd版本检查要求 ≥ 0.9.0。并发注意工具实现内禁止用asyncio.create_task()派生后台任务——ContextVar不会传播到被派生的任务可能造成跨项目数据泄漏。工具逻辑应保持同步或用顺序await。CLI Hooks 与 MCP 的取舍方面CLI HooksMCP Server上下文开销约 1–2k tokens10–50k tokens经上下文工程优化后可降至约 2–5k延迟直接调用走 MCP 协议配置Hooks 配置MCP 配置可用性需要 ShellMCP 环境即可从源码层面印证CLI 场景下bd直接执行且输出即所得MCP 场景则每一条命令都要经过 stdio 协议往返、JSON 解析与 Pydantic 校验bd_client.py 的_run_command即完成这一过程。CLI 集成的具体配置见 docs/integrations/claude-code.md完整安装指引见 docs/getting-started/installation.md。排障指南Server 无法启动确认beads-mcp在 PATH 中which beads-mcp如果找不到# 重新安装 pip uninstall beads-mcp pip install beads-mcp另外检查bdCLI 是否已安装且可执行beads-mcp启动时会校验BEADS_PATH指向可执行文件见 config.py。工具不出现重启 Claude Desktop检查 MCP 配置 JSON 语法验证 server 路径是否正确。权限错误# 检查目录权限 ls -la .beads/ # 必要时初始化 bd init --quiet版本兼容问题若 MCP 工具在 Claude Code 中不加载通常是历史版本问题v0.24.0 之前因Issue自引用 Pydantic 模型dependencies: list[Issue]生成根级$refSchema 导致工具加载失败v0.24.0 起通过拆分IssueBaseLinkedIssue打破循环引用修复。升级方式pip install --upgrade beads-mcp另外bd版本低于 0.9.0 时 MCP Server 会直接拒绝连接并提示升级bd_client.py 的_check_version。关联阅读Claude Code 集成有 Shell 环境下的 CLI 集成方式GitHub Copilot 集成VS Code / Copilot 完整接入教程安装指南bdCLI 完整安装说明beads-mcp README包的独立文档含多仓库架构图、开发与测试指引beads-mcp 测试套件覆盖客户端、生命周期、多项目切换、工作区自动检测等场景的集成测试。【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Beads 的 MCP Server 集成指南：在无 Shell 环境中让 Coding Agent 使用 bd 管理任务
Beads 的 MCP Server 集成指南在无 Shell 环境中让 Coding Agent 使用 bd 管理任务【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beadsBeadsbd是一个为编码代理Coding Agent设计的事务型 Issue 追踪器与代理记忆系统正常情况下通过 CLI Hooks 接入 Claude Code、Cursor 等具备 Shell 访问能力的环境。但在 Claude Desktop、Sourcegraph Amp 等仅 MCPModel Context Protocol环境中没有 Shell 可用此时需要依赖本仓库 integrations/beads-mcp 提供的beads-mcpMCP Server。本文将以 docs/integrations/mcp-server.md 为主线结合 beads-mcp 源码 完整讲解 MCP Server 的安装、配置、工具集、上下文工程优化、多仓库路由与排障方法。读完本文你将掌握如何在 MCP-only 环境中把 Beads 的查、建、认领、依赖、评论能力接入任意 MCP 客户端并理解其底层如何把 MCP 工具翻译成bd命令。何时该用 MCP Server何时该用 CLI Hooks先明确选择边界有 Shell 的环境优先用 CLI Hooks因为 CLI 直连bd更省上下文约 1–2k tokens且延迟更低无 Shell 的 MCP-only 环境才使用 MCP Server。典型场景包括Claude Desktop无 Shell 访问能力Sourcegraph Amp无 Shell 的 MCP 环境其他任何只暴露 MCP 协议、不允许执行 CLI 的宿主。beads-mcp的定位在 README 中写得很清楚它通过 Model Context Protocol 让 AI 代理用bdCLI 管理任务是 CLI 不可用时的替代接入方式。MCP 方案存在协议层开销上下文 10–50k tokens因此仅在必要时选用。安装 beads-mcpbeads-mcp是一个发布到 PyPI 的 Python 包项目元数据见 pyproject.toml当前版本 1.2.2要求 Python ≥ 3.10依赖fastmcp、pydantic、pydantic-settings提供beads-mcp控制台入口对应beads_mcp.server:main。使用 uv 安装推荐uv tool install beads-mcp使用 pip 安装pip install beads-mcp安装后确认可执行文件可用which beads-mcp前置条件MCP Server 本身只是翻译层实际读写操作全部委托给bdCLI。因此目标机器上必须已安装bd参考 scripts/install.sh 的安装方式。从源码看config.pybeads-mcp启动时会先查找 PATH 中的bd找不到再回退到~/.local/bin/bd并在校验失败时给出安装指引。开发模式安装需要调试 MCP Server 自身时可在仓库内开发安装git clone https://gitcode.com/GitHub_Trending/beads1/beads cd beads/integrations/beads-mcp uv sync然后在 MCP 客户端配置中用uv启动{ mcpServers: { beads: { command: uv, args: [--directory, /path/to/beads-mcp, run, beads-mcp] } } }各 MCP 客户端的配置方法beads-mcp通过 stdio 传输运行server.py 中mcp.run_async(transportstdio)所有客户端配置本质上都是让宿主拉起beads-mcp进程。Claude DesktopmacOS编辑~/Library/Application Support/Claude/claude_desktop_config.json{ mcpServers: { beads: { command: beads-mcp } } }Claude DesktopWindows编辑%APPDATA%\Claude\claude_desktop_config.json内容同上。Sourcegraph Amp在 MCP 设置中添加{ beads: { command: beads-mcp, args: [] } }VS Code / GitHub Copilot在项目根目录创建.vscode/mcp.json{ servers: { beads: { command: beads-mcp } } }对全部项目生效将配置写入 VS Code 用户级 MCP 配置各平台路径如下平台路径macOS~/Library/Application Support/Code/User/mcp.jsonLinux~/.config/Code/User/mcp.jsonWindows%APPDATA%\Code\User\mcp.json{ servers: { beads: { command: beads-mcp, args: [] } } }注意VS Code 用户级 MCP 需要 VS Code 1.96 并启用 MCP 支持。GitHub Copilot 的完整接入教程见 docs/integrations/github-copilot.md。环境变量全部可选beads-mcp通过环境变量注入配置config.py 中Config(BaseSettings)逐项读取并校验环境变量作用默认值BEADS_PATHbd可执行文件路径先查 PATH回退~/.local/bin/bdBEADS_DIR.beads目录路径推荐自动发现从工作目录向上查找BEADS_DB数据库文件路径已弃用优先用BEADS_DIR自动发现BEADS_WORKING_DIRbd命令的工作目录用于多仓库场景$PWD或当前目录BEADS_ACTOR审计追踪中的操作者名称$USERBEADS_NO_AUTO_FLUSH禁用自动 JSONL 同步falseBEADS_NO_AUTO_IMPORT禁用自动 JSONL 导入false这些变量会被客户端BdCliClient拼成bd的全局参数--actor、--no-auto-flush、--no-auto-import详见 bd_client.py。数据库路由的优先级是BEADS_DIRBEADS_DB 自动发现。可用工具全景beads-mcp把bd的核心能力封装为 MCP 工具。官方文档列出的工具总览工具说明ready显示可认领的工作无阻塞依赖list带筛选地列出 Issueshow查看 Issue 详情、依赖与反向依赖create创建新 Issueclaim原子化认领 Issueupdate更新 Issueclose/reopen关闭 / 重新打开 Issuedep管理依赖关系comment/comments添加 / 列出评论note追加到 Issue 的 notes 字段blocked显示被阻塞的 Issue 及其阻塞者stats/context数据库统计 / 工作区上下文admin管理运维操作discover_tools/get_tool_info工具发现与 Schema 查询注意MCP 没有同步sync工具——同步仍由 CLI 完成bd dolt push/bd dolt pull。这是因为 Dolt 后端同步涉及服务器进程与认证不适合放在无 Shell 的 MCP 通道里。常用工具的完整参数从 server.py 的get_tool_info实现可提取每个工具的完整参数这也是 MCP 内get_tool_info(tool_name)的返回内容readylimit1–100默认 10、priority0–4、issue_typetask/bug/feature/epic/chore/decision/merge-request 或自定义、assignee、labelsAND、labels_anyOR、unassigned、sort_policyhybrid/priority/oldest、brief、fields、max_description_length。示例ready(limit5, priority1, unassignedTrue)。liststatusopen/in_progress/blocked/deferred/closed 或自定义、priority、issue_type、assignee、labels、labels_any、query标题不区分大小写子串搜索、unassigned、limit默认 20、brief、fields、max_description_length。示例list(statusopen, labels[bug], queryauth)。showissue_id必填如bd-a1b2、brief、brief_deps完整 Issue 紧凑依赖、fields、max_description_length。示例show(issue_idbd-a1b2, brief_depsTrue)。createtitle必填、description、priority0–4默认 2、issue_type默认 task、assignee、labels、deps依赖 ID 列表、brief默认 true返回精简确认而非完整 Issue、workspace_root。示例create(titleFix auth bug, priority1, issue_typebug)。claimissue_id必填、brief默认 true。示例claim(issue_idbd-a1b2)。底层对应bd update id --claim在一次比较并交换CAS操作中同时设置 assignee in_progress已被认领会失败bd_client.py。updateissue_id必填、status、priority、assignee、title、description、brief默认 true。示例update(issue_idbd-a1b2, statusblocked)。特殊路由statusclosed会自动转向close工具、statusopen自动转向reopen工具以确保审批工作流被遵守。closeissue_id必填、reason默认 Completed。示例close(issue_idbd-a1b2, reasonFixed in PR #123)。reopenissue_ids必填列表、reason可选。示例reopen(issue_ids[bd-a1b2], reasonNeed more work)。depissue_id依赖方、depends_on_id被依赖方、dep_type默认 blocks。示例dep(issue_idbd-f1a2, depends_on_idbd-a1b2, dep_typeblocks)。常见类型blocks硬阻塞、related软关联、parent-child史诗/子任务、discovered-from工作中发现的新任务。完整依赖类型集合定义在 internal/types/types.go由bdCLI 校验MCP 层以字符串透传以保持解耦models.py。comment/commentscomment(issue_id, text)追加一条带时间戳的持久化评论人类无需阅读代理转录即可了解进展comments(issue_id)按时间顺序列出评论——注意show只报告comment_count而不返回评论正文。notenote(issue_id, text)向 Issue 的 notes 字段追加文本。注释强调逐轮工作记录优先用comment因为评论是累积的时间戳轨迹而 notes 是会被整体替换的单个字段。blockedbrief、brief_deps。返回被阻塞的 Issue 及阻塞来源。statsworkspace_root可选。返回总数、open、in_progress、closed、blocked、ready 数量及平均交付周期小时。adminaction必填为validate/repair/schema/debug/migration/pollution之一另带checks、fix_all、fix、clean参数validate数据库健康检查orphans/duplicates/pollution/conflictsfix_allTrue自动修复repair修复指向不存在 Issue 的孤儿依赖fixTrue执行删除schema展示当前数据库表结构、schema 版本与示例 IDdebug输出工作目录与全部BEADS_*环境变量migration输出迁移计划与数据库状态供代理在迁移前分析pollution检测混入生产库的测试 Issue标题以 test/benchmark/sample/tmp/temp 开头、连续编号、快速创建等模式cleanTrue删除。contextactionset/show/init省略时按参数推断有workspace_root则 set否则 show、workspace_root、prefix。context(actionset, workspace_root...)设置持久化工作区context(actioninit, ...)在已设上下文后初始化bd。discover_tools/get_tool_info前者返回仅含工具名与一句话说明的轻量目录约 500 字节后者返回指定工具的完整参数、返回值与示例。资源beads://quickstartbd快速上手指南资源代理可先读取它理解如何使用对应bd quickstart实现于 server.py 的mcp.resource注册。使用方式自然语言驱动配置完成后无需特殊语法代理直接用自然语言即可。例如Create an issue for fixing the login bug with priority 1MCP Server 会将其翻译为适当的bd命令。翻译映射关系在 bd_client.py 中逐方法对应例如beads_list_issues拼出bd list --status ... --priority ... --type ... --assignee ... --label ... --limit ...并追加全局--json标志解析输出beads_create_issue拼出bd create title -p priority -t type [-d description] [-l label] [--deps ...]claim对应bd update id --claimcomment/note使用不输出 JSON 的bd comment/bd note文本子命令。每个子进程都以stdinDEVNULL启动并显式传入cwd避免继承 MCP 自身的 stdio 通道这是 MCP 协议下 subprocess 调用的关键细节。上下文工程为代理省 Token 的设计beads-mcp在 v0.24.0 起引入了一套上下文工程优化把 MCP 方案的上下文开销从约 10–50k tokens 压到约 2–5k tokens这是其核心设计亮点见 server.py 头部注释。惰性工具 Schema 加载discover_tools()只返回工具名与简介约 500 字节get_tool_info(name)按需返回单个工具的完整 Schema。代理不必在会话开始时加载全部工具 Schema。最小化 Issue 模型约 80% 缩减列表类操作默认返回IssueMinimalid、title、status、priority、type、assignee、labels、依赖计数而非完整Issue。需要完整细节含依赖时再调用show(issue_id)。模型定义见 models.pyIssueMinimal、BriefIssue4 字段约小 95%、BriefDep5 字段约小 90%、OperationResult写操作确认约小 97%。大结果集自动压实Compaction当结果数超过阈值时返回CompactedResultcompactedtrue、total_count、前 N 条preview和提示文本而不是完整列表。两个阈值可用环境变量覆盖server.py 的_get_compaction_settingsBEADS_MCP_COMPACTION_THRESHOLD触发压实的条数默认 20须 ≥1BEADS_MCP_PREVIEW_COUNT预览条数默认 5须 ≥1 且 ≤ 阈值。按需截断描述max_description_length参数可按需截断 Issue 描述避免长文本撑爆上下文。精简字段投影fields参数只返回指定字段VALID_ISSUE_FIELDS白名单校验brief/brief_deps提供不同粒度的紧凑格式。多仓库与多项目支持一个 MCP Server 实例可以服务多个 Beads 项目采用类似 LSPLanguage Server Protocol的架构MCP Server单个实例 ↓ Per-Project Dolt Servers每个工作区一个 ↓ Dolt 数据库完全隔离推荐配置单一 MCP Server 自动路由。MCP Server 自动检测当前工作区的 Beads 项目并路由到对应的 per-project Dolt server每个项目拥有独立、隔离的 Dolt 数据库避免跨项目污染与 git worktree 冲突一份 MCP 配置即可服务无限数量的项目。替代方案不推荐为每个项目启动一个 MCP 实例用BEADS_WORKING_DIR固定工作区。风险是代理可能选错 MCP server导致命令作用在错误的数据库上因此官方明确不推荐。按请求路由workspace_root参数每个工具都接受可选workspace_root参数做显式项目定位。底层机制server.py 的with_workspace装饰器 tools.py 的ContextVar每次工具调用把workspace_root写入请求级ContextVar调用结束立即重置从而支持并发请求互不串扰未传参时按workspace_root参数 持久化BEADS_WORKING_DIR 环境变量 自动发现的顺序回退。工作区发现逻辑tools.py 的_find_beads_db_in_tree与 Go CLI 保持一致从当前目录逐级向上查找.beads支持.beads/redirect重定向文件agent/worker 共享数据库的场景、symlink 解析realpath、git worktree 边界不越过当前 repo/worktree、子模块独立.beads判定。后端类型检测server.py 的_detect_backend通过metadata.json区分 sqlite / dolt-embedded / dolt-server。连接池tools.py 的_connection_pool按规范化后的工作区路径缓存客户端每次复用前做健康检查失效连接自动丢弃并以指数退避0.1s、0.2s、0.4s重连首次连接每个工作区会做一次bd版本检查要求 ≥ 0.9.0。并发注意工具实现内禁止用asyncio.create_task()派生后台任务——ContextVar不会传播到被派生的任务可能造成跨项目数据泄漏。工具逻辑应保持同步或用顺序await。CLI Hooks 与 MCP 的取舍方面CLI HooksMCP Server上下文开销约 1–2k tokens10–50k tokens经上下文工程优化后可降至约 2–5k延迟直接调用走 MCP 协议配置Hooks 配置MCP 配置可用性需要 ShellMCP 环境即可从源码层面印证CLI 场景下bd直接执行且输出即所得MCP 场景则每一条命令都要经过 stdio 协议往返、JSON 解析与 Pydantic 校验bd_client.py 的_run_command即完成这一过程。CLI 集成的具体配置见 docs/integrations/claude-code.md完整安装指引见 docs/getting-started/installation.md。排障指南Server 无法启动确认beads-mcp在 PATH 中which beads-mcp如果找不到# 重新安装 pip uninstall beads-mcp pip install beads-mcp另外检查bdCLI 是否已安装且可执行beads-mcp启动时会校验BEADS_PATH指向可执行文件见 config.py。工具不出现重启 Claude Desktop检查 MCP 配置 JSON 语法验证 server 路径是否正确。权限错误# 检查目录权限 ls -la .beads/ # 必要时初始化 bd init --quiet版本兼容问题若 MCP 工具在 Claude Code 中不加载通常是历史版本问题v0.24.0 之前因Issue自引用 Pydantic 模型dependencies: list[Issue]生成根级$refSchema 导致工具加载失败v0.24.0 起通过拆分IssueBaseLinkedIssue打破循环引用修复。升级方式pip install --upgrade beads-mcp另外bd版本低于 0.9.0 时 MCP Server 会直接拒绝连接并提示升级bd_client.py 的_check_version。关联阅读Claude Code 集成有 Shell 环境下的 CLI 集成方式GitHub Copilot 集成VS Code / Copilot 完整接入教程安装指南bdCLI 完整安装说明beads-mcp README包的独立文档含多仓库架构图、开发与测试指引beads-mcp 测试套件覆盖客户端、生命周期、多项目切换、工作区自动检测等场景的集成测试。【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考