Metadata-Version: 2.4
Name: mbi-data-platform-mcp
Version: 2.0.0
Summary: MCP server for Miaoce BI V2: query datasets, data sources, sync jobs and data APIs with one injected access token.
License-Expression: LicenseRef-Proprietary
Keywords: mcp,modelcontextprotocol,mbi,data-platform,workbuddy-connector
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: cryptography>=41.0

# 妙策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；其余全部标准库）

```bash
pip install .                 # 或 pipx install . / uvx --from . mbi-data-platform-mcp
mbi-data-platform-mcp         # stdio 启动
python -m mbi_mcp             # 等价的模块入口
```

### 一键安装脚本（Windows）

```powershell
# 默认：检测 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` 配置一次即可：

```json
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`。

## 测试

```bash
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）：

```bash
MBI_BASE_URL=http://127.0.0.1:8080 MBI_ACCESS_TOKEN=eyJhbGci... python -m mbi_mcp
```

Windows PowerShell：

```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`。

打提交包：

```bash
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`。
