Skip to main content

妙策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 版不会被客户端自动安装。 从市场安装前,用户机器需要满足两个条件:

  1. 已安装 Python 3.9+(Windows 上建议勾选 "Add python.exe to PATH");
  2. 已安装本连接器的包: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() → 自动带凭证访问本地服务
  1. 首次确认地址 —— 调用 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://、去尾斜杠)。
  2. 确认 client_id —— 地址确认后,OAuth2 模式会检查 client_id:空值或旧占位符 local-mcp-proxy 会弹框让用户确认服务端注册的公开客户端(默认预填 2551e6d15c0e02460982354bcc50388c)。不支持弹框时返回 status: need_client_id + suggestedClientId,由 Agent 询问后再以 {clientId: "<值>"} 调用一次写盘。
  3. 自动认证 —— 同一次调用会检查凭证;没有凭证就自动打开系统浏览器进入登录页。若浏览器未自动打开或过慢,直接把返回的完整 authorizeUrl 复制到浏览器,不要只复制 baseUrl。
  4. 确认结果 —— 你在浏览器完成登录后,再次调用 proxy_bootstrap(或 proxy_auth_wait)确认凭证已加密落盘,返回 status: ready。
  5. 正常使用 —— 用 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)

Source distribution for mbi-data-platform-mcp 2.0.0
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)

Table of built distributions (wheels) for mbi-data-platform-mcp 2.0.0
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

2.0.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page