妙策BI V2 — 本地服务连接器
一个 Python 版 Stdio MCP Server,让 WorkBuddy 读取本地服务数据、调用本地接口。核心能力:首次使用判断并配置 URL → 拉起页面做登录认证 → 凭证加密存本机 → 后续调用自动带凭证。
市场展示名:妙策BI V2(Miaoce BI V2)|当前版本:2.0.0(Python 重写) 协议标识
local-mcp-proxy保持不变;data/下的config.json、credentials.json、.salt与旧版 Node 实现完全兼容,升级不需要重新登录。
工作原理
WorkBuddy ──stdio/JSON-RPC 2.0──▶ mbi_mcp ──HTTP──▶ 你的本地服务
│
├─ config.json 本地服务地址 / 认证参数
└─ credentials.json 加密凭证(AES-256-GCM)
- 凭证只用本机派生的密钥加密,不会上传到云端;密钥文件
.salt同样只存在本机。 proxy_call只允许相对路径或与baseUrl同源的完整 URL,避免凭证被跨源请求带走。- 涉及写入的
POST/PUT/PATCH/DELETE必须显式传confirm: true,连接器会在技术上拒绝未确认的写操作。
运行环境
- Python 3.9+
- 唯一第三方依赖:
cryptography(AES-256-GCM;其余全部标准库)
pip install . # 或 pipx install . / uvx --from . mbi-data-platform-mcp
mbi-data-platform-mcp # stdio 启动
python -m mbi_mcp # 等价的模块入口
一键安装脚本(Windows)
# 默认:检测 Python → 从包源安装 → 自检(导入 + stdio 握手)→ 打印可粘贴的配置
powershell -ExecutionPolicy Bypass -File scripts\install.ps1
# 离线 / 从本地仓库安装
powershell -ExecutionPolicy Bypass -File scripts\install.ps1 -FromPath D:\AgentMCP\workbuddyMCP
# 缺 Python 时用 winget 自动装
powershell -ExecutionPolicy Bypass -File scripts\install.ps1 -InstallPython
# 顺手写入 %USERPROFILE%\.workbuddy\mcp.json(自动备份 .bak,保留其他 MCP 条目)
powershell -ExecutionPolicy Bypass -File scripts\install.ps1 -ConfigureMcp
也可以直接双击 scripts\install.cmd(内部转交 PowerShell,参数原样透传)。
脚本退出码:0 成功,1 失败(缺 Python / 安装失败 / 校验失败)。
市场安装:WorkBuddy 目前只托管 Node 运行时(
runtime.type仅支持node),Python 版不会被客户端自动安装。 从市场安装前,用户机器需要满足两个条件:
- 已安装 Python 3.9+(Windows 上建议勾选 "Add python.exe to PATH");
- 已安装本连接器的包:
pip install mbi-data-platform-mcp。市场配置用
python -m mbi_mcp启动,不再经过uvx。若机器上没有python命令,可把mcp.json的command换成py(Windows 启动器,args改为["-3","-m","mbi_mcp"])或python3(macOS / Linux)。
首次使用流程
只需一个入口:proxy_bootstrap(推荐首选)。 它把下面所有步骤自动串起来,地址与 client_id 都由用户确认而非写死:
proxy_bootstrap()
├─ 未配置地址? → 弹框请用户确认访问地址(默认预填 http://127.0.0.1:8080,可改自定义)
│ 客户端不支持弹框 → 返回 status=need_base_url,由 Agent 询问后再以 {baseUrl} 调用
├─ client_id 未确认/仍为 local-mcp-proxy? → 弹框请用户确认服务端注册的公开 client_id
│ 客户端不支持弹框 → 返回 status=need_client_id,由 Agent 询问后再以 {clientId} 调用
├─ 已认证? → 直接返回 status=ready,连接器就绪
└─ 未认证? → 自动打开浏览器发起登录(authorizeUrl + PKCE),返回 status=auth_started
用户浏览器登录完成 → 回调落盘凭证
proxy_bootstrap() 再调一次(或 proxy_auth_wait)→ status=ready
proxy_call() → 自动带凭证访问本地服务
- 首次确认地址 —— 调用
proxy_bootstrap(无需参数)。若本机没有配置,不会擅自写死默认地址,而是通过 MCP elicitation 弹框让用户确认(默认预填http://127.0.0.1:8080,可改为任意自定义地址);确认后把地址与派生端点/auth/oauth2/authorize、/auth/oauth2/token写入data/config.json。若客户端未声明 elicitation 能力,则返回status: need_base_url+suggestedBaseUrls,由 Agent 向用户询问地址后,再以{baseUrl: "<地址>"}调用一次即可落盘。地址会做规范化(缺协议补http://、去尾斜杠)。 - 确认 client_id —— 地址确认后,OAuth2 模式会检查
client_id:空值或旧占位符local-mcp-proxy会弹框让用户确认服务端注册的公开客户端(默认预填2551e6d15c0e02460982354bcc50388c)。不支持弹框时返回status: need_client_id+suggestedClientId,由 Agent 询问后再以{clientId: "<值>"}调用一次写盘。 - 自动认证 —— 同一次调用会检查凭证;没有凭证就自动打开系统浏览器进入登录页。若浏览器未自动打开或过慢,直接把返回的完整
authorizeUrl复制到浏览器,不要只复制 baseUrl。 - 确认结果 —— 你在浏览器完成登录后,再次调用
proxy_bootstrap(或proxy_auth_wait)确认凭证已加密落盘,返回status: ready。 - 正常使用 —— 用
proxy_call,凭证自动注入;令牌过期且有 refreshToken 时自动刷新。
幂等安全:proxy_bootstrap 可重复调用——已配置的地址和 client_id 不会再次询问,已认证不会重复弹浏览器。只有需要换服务/重新登录时才用 force: true / reauth: true。
proxy_bootstrap 参数 |
说明 | 默认 |
|---|---|---|
baseUrl |
本地服务根地址。首次省略时会弹框询问用户(或返回 need_base_url 降级);已配置时仅在 force 下生效 |
弹框默认预填 http://127.0.0.1:8080 |
authorizeUrl / tokenUrl |
授权/令牌端点 | 由 baseUrl 自动派生 |
clientId |
客户端 ID;首次或检测到旧占位符时弹框确认,也可显式传入 | 弹框默认预填 2551e6d15c0e02460982354bcc50388c |
authMode |
oauth2 / api_key / none |
oauth2 |
openBrowser |
是否自动打开浏览器 | true |
force / reauth |
强制覆盖配置 / 强制重新认证 | false |
如果本地服务用的是简单 API Key / 已手动拿到 token,跳过浏览器流程,直接用
proxy_auth_submit提交即可。
工具清单
| 工具 | 用途 |
|---|---|
proxy_bootstrap |
首选:一键初始化(自动配置+自动认证+幂等) |
proxy_status |
查看配置/认证状态(令牌脱敏) |
proxy_configure |
配置 baseUrl、认证模式及参数(自定义场景才用) |
proxy_auth_start |
发起 OAuth2 认证(PKCE + 本地回调 + 打开浏览器) |
proxy_auth_wait |
等待认证结果;默认 30 秒没完成就先返回 status=pending + 完整 authorizeUrl,可直接发给用户手动打开;传 pendingAfterMs: 0 恢复长阻塞,timeoutMs 默认 180000 |
proxy_auth_submit |
手动提交 access_token / API Key |
proxy_call |
调用本地接口,自动带凭证、令牌过期自动刷新 |
proxy_auth_clear |
清除本地凭证,重新认证 |
认证模式
none—— 无需认证,直连本地服务。api_key—— 提交 token 后按模板注入请求头(如Authorization: Bearer <token>)。oauth2—— 授权码 + PKCE 流程,本地回调用http://127.0.0.1:<redirectPort><redirectPath>(默认http://127.0.0.1:18765/callback)。
对接 MBI 数据中台(/auth/oauth2/** 端点)
连接器的 OAuth2 实现严格对齐设计文档第 8.7 节契约。已适配 MBI 的 mbi-auth 专用端点:
authorizeUrl = http://<网关>/auth/oauth2/authorize
tokenUrl = http://<网关>/auth/oauth2/token
clientId = 2551e6d15c0e02460982354bcc50388c (公开客户端,usePkce=true,无需 clientSecret)
scope = read write
redirectPort = 18765
网关 clientid 一致性校验(坑 C)已自动处理:MBI 网关要求请求头 clientid 与 token 内的 clientid 一致,否则 401。连接器在 oauth2 模式下会自动注入 clientid 头(值 = 配置的 clientId),无需在每次 proxy_call 手传。如需关闭,配置 autoClientIdHeader: false;如需带其他自定义头,用 defaultHeaders 配置一次即可:
proxy_configure({
baseUrl: "http://<网关>",
authMode: "oauth2",
authorizeUrl: "http://<网关>/auth/oauth2/authorize",
tokenUrl: "http://<网关>/auth/oauth2/token",
clientId: "2551e6d15c0e02460982354bcc50388c",
scope: "read write",
usePkce: true
// defaultHeaders / autoClientIdHeader 一般无需配置
})
token 响应遵循标准 OAuth2(access_token/token_type/expires_in/refresh_token/scope,裸 JSON),过期自动用 refresh_token 续期;凭证 AES-256-GCM 加密存于本机。
本地文件
data/config.json—— 服务地址与认证配置(明文,仅本机可读)data/credentials.json—— 加密后的凭证data/.salt—— 本机派生密钥的盐值(删除后凭证将无法解密)
请勿单独删除 data/ 下的隐藏文件;需要重置时用 proxy_auth_clear。
测试
python test/run_all.py # 运行全部自动化测试
python test/test_server.py # 协议与工具基础(状态/配置/同源/写操作/脱敏)
python test/test_elicitation.py # 首次地址确认:弹框收集 / 不支持时降级 need_base_url
python test/test_e2e.py # 完整 OAuth2 + PKCE + 回调 + 自动续期端到端
python test/test_market.py # 市场三种运行形态端到端
这些测试都在系统临时目录里跑,不会读写真实的 data/。
注意:连接器运行期间会常驻占用
127.0.0.1:18765,直接跑端到端测试若撞端口,改一下测试里的redirectPort即可。
环境变量模式(官方市场分发)
上架 WorkBuddy 官方市场时走 auth_mode: "token",凭证由客户端注入到 mcp.json 的 env:
| 变量 | 必填 | 说明 |
|---|---|---|
MBI_BASE_URL |
是 | 数据中台网关地址,如 https://mbi.example.com |
MBI_ACCESS_TOKEN |
是 | 个人访问令牌;保留默认值 auto 表示走浏览器授权 |
MBI_CLIENT_ID |
否 | 留空则自动从令牌的 clientid 声明解析 |
MBI_AUTHORIZE_URL / MBI_TOKEN_URL |
否 | 覆盖由 MBI_BASE_URL 自动派生的端点 |
MBI_TIMEOUT_MS |
否 | 请求超时毫秒 |
该模式的特点:
- 优先级最高:环境变量覆盖
data/config.json,且不写盘,不影响用户本地已有配置; - 开箱即用:
proxy_bootstrap直接返回ready,不询问地址、不打开浏览器; - 状态可查:
proxy_status返回credentialSource: "env"与env诊断块。
本地手动设置示例(macOS / Linux):
MBI_BASE_URL=http://127.0.0.1:8080 MBI_ACCESS_TOKEN=eyJhbGci... python -m mbi_mcp
Windows PowerShell:
$env:MBI_BASE_URL="http://127.0.0.1:8080"; $env:MBI_ACCESS_TOKEN="eyJhbGci..."; python -m mbi_mcp
市场提交物料见 connector/(元信息 / mcp.json / token-schema / 图标 / Skill),完整上架流程见 docs/上架方案.md,目录规范见 docs/STRUCTURE.md。
打提交包:
python scripts/pack.py
# 输出 dist/mbi-data-platform-<version>.zip(正斜杠路径、无空目录条目),并打印包大小与 SHA256
数据目录位置
| 运行方式 | 数据目录 |
|---|---|
| 源码目录直接运行 | <项目>/data/ |
| pip / pipx / uvx 安装运行 | ~/.mbi-data-platform-mcp/ |
设置了 LOCAL_MCP_PROXY_DATA_DIR |
该变量指定的路径 |
安装形态下不写入 site-packages(安装目录可能被清理,会导致配置丢失)。
从 1.x(Node 版)迁移
- 工具名、参数、返回结构、数据目录、凭证格式均保持一致,客户端侧无需改配置;
- 只需把启动方式从
npx mbi-data-platform-mcp换成mbi-data-platform-mcp(或python -m mbi_mcp); - 已有的
data/config.json、credentials.json、.salt可直接复用,不需要重新登录; - 版本号升至
2.0.0,因为运行时依赖从 Node 变成了 Python 3.9+ 与cryptography。
Metadata
Release files for mbi-data-platform-mcp 2.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| mbi_data_platform_mcp-2.0.0.tar.gz | 33.2 kB | Without provenance | Details for mbi_data_platform_mcp-2.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| mbi_data_platform_mcp-2.0.0-py3-none-any.whl | Python 3 | none | any | Details for mbi_data_platform_mcp-2.0.0-py3-none-any.whl |
Total release size: 71.4 kB
Release files / mbi_data_platform_mcp-2.0.0.tar.gz
| Download URL | mbi_data_platform_mcp-2.0.0.tar.gz |
|---|---|
| Size | 33.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
131bd16c2a0d6d78baba50ef0cbf6ddb5439a8ba1dd239ea4b30cbe4b9fb033a
|
|
BLAKE2b-256 checksum How to use checksums |
17d456a97d80f9ec32e587529d4c7479cb623d2c00fe67b84c5ca2aba85ad176
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.17
|
Release files / mbi_data_platform_mcp-2.0.0-py3-none-any.whl
| Download URL | mbi_data_platform_mcp-2.0.0-py3-none-any.whl |
|---|---|
| Size | 38.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c4569c9c7e3a1b540e17cf213d0431e40857c0e8486323cbe865de24289c9b3b
|
|
BLAKE2b-256 checksum How to use checksums |
907637c223aa5db4145646294447d9163fe155719322402b3cd36dfc66360b0d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.17
|
Security for mbi-data-platform-mcp 2.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.