Beads 的 MCP Server 集成指南在無 Shell 環(huán)境中讓 Coding Agent 使用 bd 管理任務(wù)【免費(fèi)下載鏈接】beadsBeads - A memory upgrade for your coding agent項(xiàng)目地址: https://gitcode.com/GitHub_Trending/beads1/beadsBeadsbd是一個(gè)為編碼代理Coding Agent設(shè)計(jì)的事務(wù)型 Issue 追蹤器與代理記憶系統(tǒng)正常情況下通過 CLI Hooks 接入 Claude Code、Cursor 等具備 Shell 訪問能力的環(huán)境。但在 Claude Desktop、Sourcegraph Amp 等僅 MCPModel Context Protocol環(huán)境中沒有 Shell 可用此時(shí)需要依賴本倉庫 integrations/beads-mcp 提供的beads-mcpMCP Server。本文將以 docs/integrations/mcp-server.md 為主線結(jié)合 beads-mcp 源碼 完整講解 MCP Server 的安裝、配置、工具集、上下文工程優(yōu)化、多倉庫路由與排障方法。讀完本文你將掌握如何在 MCP-only 環(huán)境中把 Beads 的查、建、認(rèn)領(lǐng)、依賴、評(píng)論能力接入任意 MCP 客戶端并理解其底層如何把 MCP 工具翻譯成bd命令。何時(shí)該用 MCP Server何時(shí)該用 CLI Hooks先明確選擇邊界有 Shell 的環(huán)境優(yōu)先用 CLI Hooks因?yàn)?CLI 直連bd更省上下文約 1–2k tokens且延遲更低無 Shell 的 MCP-only 環(huán)境才使用 MCP Server。典型場(chǎng)景包括Claude Desktop無 Shell 訪問能力Sourcegraph Amp無 Shell 的 MCP 環(huán)境其他任何只暴露 MCP 協(xié)議、不允許執(zhí)行 CLI 的宿主。beads-mcp的定位在 README 中寫得很清楚它通過 Model Context Protocol 讓 AI 代理用bdCLI 管理任務(wù)是 CLI 不可用時(shí)的替代接入方式。MCP 方案存在協(xié)議層開銷上下文 10–50k tokens因此僅在必要時(shí)選用。安裝 beads-mcpbeads-mcp是一個(gè)發(fā)布到 PyPI 的 Python 包項(xiàng)目元數(shù)據(jù)見 pyproject.toml當(dāng)前版本 1.2.2要求 Python ≥ 3.10依賴fastmcp、pydantic、pydantic-settings提供beads-mcp控制臺(tái)入口對(duì)應(yīng)beads_mcp.server:main。使用 uv 安裝推薦uv tool install beads-mcp使用 pip 安裝pip install beads-mcp安裝后確認(rèn)可執(zhí)行文件可用which beads-mcp前置條件MCP Server 本身只是翻譯層實(shí)際讀寫操作全部委托給bdCLI。因此目標(biāo)機(jī)器上必須已安裝bd參考 scripts/install.sh 的安裝方式。從源碼看config.pybeads-mcp啟動(dòng)時(shí)會(huì)先查找 PATH 中的bd找不到再回退到~/.local/bin/bd并在校驗(yàn)失敗時(shí)給出安裝指引。開發(fā)模式安裝需要調(diào)試 MCP Server 自身時(shí)可在倉庫內(nèi)開發(fā)安裝git clone https://gitcode.com/GitHub_Trending/beads1/beads cd beads/integrations/beads-mcp uv sync然后在 MCP 客戶端配置中用uv啟動(dòng){ mcpServers: { beads: { command: uv, args: [--directory, /path/to/beads-mcp, run, beads-mcp] } } }各 MCP 客戶端的配置方法beads-mcp通過 stdio 傳輸運(yùn)行server.py 中mcp.run_async(transportstdio)所有客戶端配置本質(zhì)上都是讓宿主拉起beads-mcp進(jìn)程。Claude DesktopmacOS編輯~/Library/Application Support/Claude/claude_desktop_config.json{ mcpServers: { beads: { command: beads-mcp } } }Claude DesktopWindows編輯%APPDATA%\Claude\claude_desktop_config.json內(nèi)容同上。Sourcegraph Amp在 MCP 設(shè)置中添加{ beads: { command: beads-mcp, args: [] } }VS Code / GitHub Copilot在項(xiàng)目根目錄創(chuàng)建.vscode/mcp.json{ servers: { beads: { command: beads-mcp } } }對(duì)全部項(xiàng)目生效將配置寫入 VS Code 用戶級(jí) MCP 配置各平臺(tái)路徑如下平臺(tái)路徑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 用戶級(jí) MCP 需要 VS Code 1.96 并啟用 MCP 支持。GitHub Copilot 的完整接入教程見 docs/integrations/github-copilot.md。環(huán)境變量全部可選beads-mcp通過環(huán)境變量注入配置config.py 中Config(BaseSettings)逐項(xiàng)讀取并校驗(yàn)環(huán)境變量作用默認(rèn)值BEADS_PATHbd可執(zhí)行文件路徑先查 PATH回退~/.local/bin/bdBEADS_DIR.beads目錄路徑推薦自動(dòng)發(fā)現(xiàn)從工作目錄向上查找BEADS_DB數(shù)據(jù)庫文件路徑已棄用優(yōu)先用BEADS_DIR自動(dòng)發(fā)現(xiàn)BEADS_WORKING_DIRbd命令的工作目錄用于多倉庫場(chǎng)景$PWD或當(dāng)前目錄BEADS_ACTOR審計(jì)追蹤中的操作者名稱$USERBEADS_NO_AUTO_FLUSH禁用自動(dòng) JSONL 同步falseBEADS_NO_AUTO_IMPORT禁用自動(dòng) JSONL 導(dǎo)入false這些變量會(huì)被客戶端BdCliClient拼成bd的全局參數(shù)--actor、--no-auto-flush、--no-auto-import詳見 bd_client.py。數(shù)據(jù)庫路由的優(yōu)先級(jí)是BEADS_DIRBEADS_DB 自動(dòng)發(fā)現(xiàn)。可用工具全景beads-mcp把bd的核心能力封裝為 MCP 工具。官方文檔列出的工具總覽工具說明ready顯示可認(rèn)領(lǐng)的工作無阻塞依賴list帶篩選地列出 Issueshow查看 Issue 詳情、依賴與反向依賴create創(chuàng)建新 Issueclaim原子化認(rèn)領(lǐng) Issueupdate更新 Issueclose/reopen關(guān)閉 / 重新打開 Issuedep管理依賴關(guān)系comment/comments添加 / 列出評(píng)論note追加到 Issue 的 notes 字段blocked顯示被阻塞的 Issue 及其阻塞者stats/context數(shù)據(jù)庫統(tǒng)計(jì) / 工作區(qū)上下文admin管理運(yùn)維操作discover_tools/get_tool_info工具發(fā)現(xiàn)與 Schema 查詢注意MCP 沒有同步sync工具——同步仍由 CLI 完成bd dolt push/bd dolt pull。這是因?yàn)?Dolt 后端同步涉及服務(wù)器進(jìn)程與認(rèn)證不適合放在無 Shell 的 MCP 通道里。常用工具的完整參數(shù)從 server.py 的get_tool_info實(shí)現(xiàn)可提取每個(gè)工具的完整參數(shù)這也是 MCP 內(nèi)get_tool_info(tool_name)的返回內(nèi)容readylimit1–100默認(rèn) 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標(biāo)題不區(qū)分大小寫子串搜索、unassigned、limit默認(rèn) 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默認(rèn) 2、issue_type默認(rèn) task、assignee、labels、deps依賴 ID 列表、brief默認(rèn) true返回精簡(jiǎn)確認(rèn)而非完整 Issue、workspace_root。示例create(titleFix auth bug, priority1, issue_typebug)。claimissue_id必填、brief默認(rèn) true。示例claim(issue_idbd-a1b2)。底層對(duì)應(yīng)bd update id --claim在一次比較并交換CAS操作中同時(shí)設(shè)置 assignee in_progress已被認(rèn)領(lǐng)會(huì)失敗bd_client.py。updateissue_id必填、status、priority、assignee、title、description、brief默認(rèn) true。示例update(issue_idbd-a1b2, statusblocked)。特殊路由statusclosed會(huì)自動(dòng)轉(zhuǎn)向close工具、statusopen自動(dòng)轉(zhuǎn)向reopen工具以確保審批工作流被遵守。closeissue_id必填、reason默認(rèn) 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默認(rèn) blocks。示例dep(issue_idbd-f1a2, depends_on_idbd-a1b2, dep_typeblocks)。常見類型blocks硬阻塞、related軟關(guān)聯(lián)、parent-child史詩/子任務(wù)、discovered-from工作中發(fā)現(xiàn)的新任務(wù)。完整依賴類型集合定義在 internal/types/types.go由bdCLI 校驗(yàn)MCP 層以字符串透?jìng)饕员３纸怦頼odels.py。comment/commentscomment(issue_id, text)追加一條帶時(shí)間戳的持久化評(píng)論人類無需閱讀代理轉(zhuǎn)錄即可了解進(jìn)展comments(issue_id)按時(shí)間順序列出評(píng)論——注意show只報(bào)告comment_count而不返回評(píng)論正文。notenote(issue_id, text)向 Issue 的 notes 字段追加文本。注釋強(qiáng)調(diào)逐輪工作記錄優(yōu)先用comment因?yàn)樵u(píng)論是累積的時(shí)間戳軌跡而 notes 是會(huì)被整體替換的單個(gè)字段。blockedbrief、brief_deps。返回被阻塞的 Issue 及阻塞來源。statsworkspace_root可選。返回總數(shù)、open、in_progress、closed、blocked、ready 數(shù)量及平均交付周期小時(shí)。adminaction必填為validate/repair/schema/debug/migration/pollution之一另帶checks、fix_all、fix、clean參數(shù)validate數(shù)據(jù)庫健康檢查orphans/duplicates/pollution/conflictsfix_allTrue自動(dòng)修復(fù)repair修復(fù)指向不存在 Issue 的孤兒依賴fixTrue執(zhí)行刪除schema展示當(dāng)前數(shù)據(jù)庫表結(jié)構(gòu)、schema 版本與示例 IDdebug輸出工作目錄與全部BEADS_*環(huán)境變量migration輸出遷移計(jì)劃與數(shù)據(jù)庫狀態(tài)供代理在遷移前分析pollution檢測(cè)混入生產(chǎn)庫的測(cè)試 Issue標(biāo)題以 test/benchmark/sample/tmp/temp 開頭、連續(xù)編號(hào)、快速創(chuàng)建等模式cleanTrue刪除。contextactionset/show/init省略時(shí)按參數(shù)推斷有workspace_root則 set否則 show、workspace_root、prefix。context(actionset, workspace_root...)設(shè)置持久化工作區(qū)context(actioninit, ...)在已設(shè)上下文后初始化bd。discover_tools/get_tool_info前者返回僅含工具名與一句話說明的輕量目錄約 500 字節(jié)后者返回指定工具的完整參數(shù)、返回值與示例。資源beads://quickstartbd快速上手指南資源代理可先讀取它理解如何使用對(duì)應(yīng)bd quickstart實(shí)現(xiàn)于 server.py 的mcp.resource注冊(cè)。使用方式自然語言驅(qū)動(dòng)配置完成后無需特殊語法代理直接用自然語言即可。例如Create an issue for fixing the login bug with priority 1MCP Server 會(huì)將其翻譯為適當(dāng)?shù)腷d命令。翻譯映射關(guān)系在 bd_client.py 中逐方法對(duì)應(yīng)例如beads_list_issues拼出bd list --status ... --priority ... --type ... --assignee ... --label ... --limit ...并追加全局--json標(biāo)志解析輸出beads_create_issue拼出bd create title -p priority -t type [-d description] [-l label] [--deps ...]claim對(duì)應(yīng)bd update id --claimcomment/note使用不輸出 JSON 的bd comment/bd note文本子命令。每個(gè)子進(jìn)程都以stdinDEVNULL啟動(dòng)并顯式傳入cwd避免繼承 MCP 自身的 stdio 通道這是 MCP 協(xié)議下 subprocess 調(diào)用的關(guān)鍵細(xì)節(jié)。上下文工程為代理省 Token 的設(shè)計(jì)beads-mcp在 v0.24.0 起引入了一套上下文工程優(yōu)化把 MCP 方案的上下文開銷從約 10–50k tokens 壓到約 2–5k tokens這是其核心設(shè)計(jì)亮點(diǎn)見 server.py 頭部注釋。惰性工具 Schema 加載discover_tools()只返回工具名與簡(jiǎn)介約 500 字節(jié)get_tool_info(name)按需返回單個(gè)工具的完整 Schema。代理不必在會(huì)話開始時(shí)加載全部工具 Schema。最小化 Issue 模型約 80% 縮減列表類操作默認(rèn)返回IssueMinimalid、title、status、priority、type、assignee、labels、依賴計(jì)數(shù)而非完整Issue。需要完整細(xì)節(jié)含依賴時(shí)再調(diào)用show(issue_id)。模型定義見 models.pyIssueMinimal、BriefIssue4 字段約小 95%、BriefDep5 字段約小 90%、OperationResult寫操作確認(rèn)約小 97%。大結(jié)果集自動(dòng)壓實(shí)Compaction當(dāng)結(jié)果數(shù)超過閾值時(shí)返回CompactedResultcompactedtrue、total_count、前 N 條preview和提示文本而不是完整列表。兩個(gè)閾值可用環(huán)境變量覆蓋server.py 的_get_compaction_settingsBEADS_MCP_COMPACTION_THRESHOLD觸發(fā)壓實(shí)的條數(shù)默認(rèn) 20須 ≥1BEADS_MCP_PREVIEW_COUNT預(yù)覽條數(shù)默認(rèn) 5須 ≥1 且 ≤ 閾值。按需截?cái)嗝枋鰉ax_description_length參數(shù)可按需截?cái)?Issue 描述避免長(zhǎng)文本撐爆上下文。精簡(jiǎn)字段投影fields參數(shù)只返回指定字段VALID_ISSUE_FIELDS白名單校驗(yàn)brief/brief_deps提供不同粒度的緊湊格式。多倉庫與多項(xiàng)目支持一個(gè) MCP Server 實(shí)例可以服務(wù)多個(gè) Beads 項(xiàng)目采用類似 LSPLanguage Server Protocol的架構(gòu)MCP Server單個(gè)實(shí)例 ↓ Per-Project Dolt Servers每個(gè)工作區(qū)一個(gè) ↓ Dolt 數(shù)據(jù)庫完全隔離推薦配置單一 MCP Server 自動(dòng)路由。MCP Server 自動(dòng)檢測(cè)當(dāng)前工作區(qū)的 Beads 項(xiàng)目并路由到對(duì)應(yīng)的 per-project Dolt server每個(gè)項(xiàng)目擁有獨(dú)立、隔離的 Dolt 數(shù)據(jù)庫避免跨項(xiàng)目污染與 git worktree 沖突一份 MCP 配置即可服務(wù)無限數(shù)量的項(xiàng)目。替代方案不推薦為每個(gè)項(xiàng)目啟動(dòng)一個(gè) MCP 實(shí)例用BEADS_WORKING_DIR固定工作區(qū)。風(fēng)險(xiǎn)是代理可能選錯(cuò) MCP server導(dǎo)致命令作用在錯(cuò)誤的數(shù)據(jù)庫上因此官方明確不推薦。按請(qǐng)求路由workspace_root參數(shù)每個(gè)工具都接受可選workspace_root參數(shù)做顯式項(xiàng)目定位。底層機(jī)制server.py 的with_workspace裝飾器 tools.py 的ContextVar每次工具調(diào)用把workspace_root寫入請(qǐng)求級(jí)ContextVar調(diào)用結(jié)束立即重置從而支持并發(fā)請(qǐng)求互不串?dāng)_未傳參時(shí)按workspace_root參數(shù) 持久化BEADS_WORKING_DIR 環(huán)境變量 自動(dòng)發(fā)現(xiàn)的順序回退。工作區(qū)發(fā)現(xiàn)邏輯tools.py 的_find_beads_db_in_tree與 Go CLI 保持一致從當(dāng)前目錄逐級(jí)向上查找.beads支持.beads/redirect重定向文件agent/worker 共享數(shù)據(jù)庫的場(chǎng)景、symlink 解析realpath、git worktree 邊界不越過當(dāng)前 repo/worktree、子模塊獨(dú)立.beads判定。后端類型檢測(cè)server.py 的_detect_backend通過metadata.json區(qū)分 sqlite / dolt-embedded / dolt-server。連接池tools.py 的_connection_pool按規(guī)范化后的工作區(qū)路徑緩存客戶端每次復(fù)用前做健康檢查失效連接自動(dòng)丟棄并以指數(shù)退避0.1s、0.2s、0.4s重連首次連接每個(gè)工作區(qū)會(huì)做一次bd版本檢查要求 ≥ 0.9.0。并發(fā)注意工具實(shí)現(xiàn)內(nèi)禁止用asyncio.create_task()派生后臺(tái)任務(wù)——ContextVar不會(huì)傳播到被派生的任務(wù)可能造成跨項(xiàng)目數(shù)據(jù)泄漏。工具邏輯應(yīng)保持同步或用順序await。CLI Hooks 與 MCP 的取舍方面CLI HooksMCP Server上下文開銷約 1–2k tokens10–50k tokens經(jīng)上下文工程優(yōu)化后可降至約 2–5k延遲直接調(diào)用走 MCP 協(xié)議配置Hooks 配置MCP 配置可用性需要 ShellMCP 環(huán)境即可從源碼層面印證CLI 場(chǎng)景下bd直接執(zhí)行且輸出即所得MCP 場(chǎng)景則每一條命令都要經(jīng)過 stdio 協(xié)議往返、JSON 解析與 Pydantic 校驗(yàn)bd_client.py 的_run_command即完成這一過程。CLI 集成的具體配置見 docs/integrations/claude-code.md完整安裝指引見 docs/getting-started/installation.md。排障指南Server 無法啟動(dòng)確認(rèn)beads-mcp在 PATH 中which beads-mcp如果找不到# 重新安裝 pip uninstall beads-mcp pip install beads-mcp另外檢查bdCLI 是否已安裝且可執(zhí)行beads-mcp啟動(dòng)時(shí)會(huì)校驗(yàn)BEADS_PATH指向可執(zhí)行文件見 config.py。工具不出現(xiàn)重啟 Claude Desktop檢查 MCP 配置 JSON 語法驗(yàn)證 server 路徑是否正確。權(quán)限錯(cuò)誤# 檢查目錄權(quán)限 ls -la .beads/ # 必要時(shí)初始化 bd init --quiet版本兼容問題若 MCP 工具在 Claude Code 中不加載通常是歷史版本問題v0.24.0 之前因Issue自引用 Pydantic 模型dependencies: list[Issue]生成根級(jí)$refSchema 導(dǎo)致工具加載失敗v0.24.0 起通過拆分IssueBaseLinkedIssue打破循環(huán)引用修復(fù)。升級(jí)方式pip install --upgrade beads-mcp另外bd版本低于 0.9.0 時(shí) MCP Server 會(huì)直接拒絕連接并提示升級(jí)bd_client.py 的_check_version。關(guān)聯(lián)閱讀Claude Code 集成有 Shell 環(huán)境下的 CLI 集成方式GitHub Copilot 集成VS Code / Copilot 完整接入教程安裝指南bdCLI 完整安裝說明beads-mcp README包的獨(dú)立文檔含多倉庫架構(gòu)圖、開發(fā)與測(cè)試指引beads-mcp 測(cè)試套件覆蓋客戶端、生命周期、多項(xiàng)目切換、工作區(qū)自動(dòng)檢測(cè)等場(chǎng)景的集成測(cè)試。【免費(fèi)下載鏈接】beadsBeads - A memory upgrade for your coding agent項(xiàng)目地址: https://gitcode.com/GitHub_Trending/beads1/beads創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考