Repository navigation
feat: Claude Desktop 一鍵安裝擴充套件（finmind.mcpb） - #26
Merged
Merged
Conversation
用戶反映 PowerShell 找得到 uvx 但 Claude Desktop 找不到，手動查路徑、
改 JSON 對一般用戶太複雜。改提供 Claude Desktop 擴充套件：下載 .mcpb
點兩下、貼 token 即可，不需安裝 Python、不需編輯設定檔、不碰 PATH。
新增檔案：
- mcpb/manifest.json：manifest v0.4，server.type = "uv"（由 Claude Desktop
自行以 uv 準備 Python 與相依套件）；user_config.finmind_token（必填、
sensitive）經 env 傳成 FINMIND_TOKEN；列出 5 個 tool。刻意不宣告
compatibility.runtimes.python，避免 Claude Desktop 檢查系統 Python 後拒裝
- mcpb/pyproject.toml：相依 finmind-mcp==<版本>，打包時改成發版 tag
- mcpb/src/server.py：進入點，呼叫 finmind_mcp.server.main
- mcpb/icon.png：512x512，由 FinMind logo 裁切
- mcpb/.mcpbignore
- scripts/build_mcpb.py：複製 mcpb/ → 寫入版本 → npx @anthropic-ai/mcpb@2
validate + pack → dist/finmind.mcpb；--dev 讓相依指向本機原始碼
- scripts/check_mcpb.py：模擬 host（解壓、代入 ${__dirname}/${user_config.*}、
以 uv 啟動、MCP 握手、tools/list 對照 manifest、呼叫 list_datasets）
- tests/test_mcpb.py：manifest tools 與 server 一致、uv 類型與 token 對應、
不宣告 runtimes.python、版本寫入與 tag 解析
修改檔案：
- .github/workflows/ci.yml：新增 mcpb job（--dev 打包＋模擬安裝）
- .github/workflows/publish.yml：PyPI 發佈後新增 mcpb job，釘同版本打包、
從 PyPI 模擬安裝（index 延遲重試 5 次），附加到該 tag 的 GitHub Release
- install/claude-desktop.md：擴充套件列為方式一（推薦），手動設定改方式二，
新增「擴充套件無法連線」常見問題
- install/windows.md：開頭導向 Claude Desktop 擴充套件；找不到指令的 FAQ
先建議完全結束重開，仍不行才查完整路徑
- README.md：Claude Desktop 一鍵安裝連結、倉庫結構、發佈流程說明
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This was referenced Oct 1, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
背景
用戶反映 PowerShell 找得到
uvx，但 Claude Desktop 找不到。#25 補的「查完整路徑、JSON 反斜線寫兩次」對一般用戶太複雜。用戶流程
下載
finmind.mcpb→ 點兩下 → 貼 token。不用裝 Python、不用編輯設定檔、不碰 PATH。修改
mcpb/：manifest v0.4，server.type = "uv"，由 Claude Desktop 自己用 uv 準備 Python 和相依套件；token 走user_config（必填、遮罩），以FINMIND_TOKEN傳給 server。compatibility.runtimes.python：有人回報（Claude Desktop disables installation if no system python detected, even with uv installed modelcontextprotocol/mcpb#84），宣告了之後 Claude Desktop 會去找系統 Python，找不到就拒絕安裝。scripts/build_mcpb.py：用官方 CLI（@anthropic-ai/mcpb）驗證並打包，finmind-mcp釘在發版 tag 的版本；--dev改用本機原始碼。scripts/check_mcpb.py：模擬 host 安裝：解壓、代入變數、用 uv 啟動、MCP 握手、確認 tools 與 manifest 一致、實際呼叫list_datasets。ci.yml）：PR 時用--dev打包＋模擬安裝。publish.yml）：PyPI 發佈後打包、從 PyPI 模擬安裝（PyPI index 還沒更新時會重試），再附加到該 tag 的 GitHub Release。下載連結固定指向最新版。tests/test_mcpb.py：新增 tool 卻忘了更新 manifest 時會擋下。install/claude-desktop.md把擴充套件列為方式一（推薦），新增「擴充套件無法連線」的常見問題；install/windows.md開頭導向擴充套件，找不到指令時先建議完全結束重開；README 補上連結和發版說明。驗證
mcpb validate/pack通過，套件 4 個檔、約 56 KB。list_datasets都通過；--dev用本機原始碼連跑 3 次都通過。python3 scripts/build_mcpb.py 0.0.10產出dist/finmind.mcpb，點兩下安裝，確認畫面會要求輸入 Token，且對話中可以呼叫 tool。finmind.mcpb會自動附到 Release。FinMind-Doc#224 的下載連結要等這一步完成才不會 404。