@miaocedata/mbi-bi-mcp 0.2.4 → 0.2.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +97 -124
- package/package.json +26 -26
- package/src/auth.js +0 -36
- package/src/client.js +9 -10
- package/src/index.js +25 -25
package/README.md
CHANGED
|
@@ -1,124 +1,97 @@
|
|
|
1
|
-
# 数据中台 BI MCP · 本地连接器
|
|
2
|
-
|
|
3
|
-
这是 Node.js 22+ 的 **stdio** MCP。它只通过中台对外接口取数,不直连任何底层数据引擎,也不启动可见的 Sense X 对话。它提供 `configure_platform`(设置/切换地址)、`reauthorize`(换账号后重新认证)、`get_analysis_config`(分析配置)、`get_business_ontology`(已发布本体)、`query_metrics`(已登记指标查询),以及 `get_agent_profiles`、`get_agent_tools`、`call_agent_tool`。写看板、原生 Sheet 交付和 Mashup 大屏完全复用平台 `agent:write`、Agent Profile USE ACL、Profile 能力白名单和原有交付门禁。客户须部署中台、持有有效 License,由中台管理员启用该租户的「外部问数」,再使用有资源权限和相应 Profile 的中台账号授权。无需单独签发 WorkBuddy License。
|
|
4
|
-
|
|
5
|
-
## 本地联调(无需 npm 发布)
|
|
6
|
-
|
|
7
|
-
在本包目录运行 `npm ci`、`npm test`。在宿主 MCP 配置中加入以下服务(路径替换成实际绝对路径;`node` 需在宿主的 PATH 中):
|
|
8
|
-
|
|
9
|
-
```json
|
|
10
|
-
{
|
|
11
|
-
"mcpServers": {
|
|
12
|
-
"mbi-senseX": {
|
|
13
|
-
"command": "node",
|
|
14
|
-
"args": ["D:/path/to/mbi-external-bi-mcp/src/index.js"],
|
|
15
|
-
"env": {
|
|
16
|
-
"MBI_PLATFORM_URL": "https://bi.example.com"
|
|
17
|
-
}
|
|
18
|
-
}
|
|
19
|
-
}
|
|
20
|
-
}
|
|
21
|
-
```
|
|
22
|
-
|
|
23
|
-
- **WorkBuddy**:先用本地 stdio 配置联调。`connector/mcp.json` 是 npm 包发布后的提审配置示例,不是已确认的市场包格式;应在提审前用 WorkBuddy 的实际版本验证配置、首次授权和重试行为。
|
|
24
|
-
- **Claude Code**:同形状 JSON 可配置到项目 `.mcp.json`;不要把客户实际地址提交到公开仓库。也可使用本机用户级 MCP 配置。
|
|
25
|
-
- **Codex**:本地 `config.toml` 使用下列配置。云端运行环境不在本次支持范围内。
|
|
26
|
-
|
|
27
|
-
```toml
|
|
28
|
-
[mcp_servers.mbi-senseX]
|
|
29
|
-
command = "node"
|
|
30
|
-
args = ["D:/path/to/mbi-external-bi-mcp/src/index.js"]
|
|
31
|
-
|
|
32
|
-
[mcp_servers.mbi-senseX.env]
|
|
33
|
-
MBI_PLATFORM_URL = "https://bi.example.com"
|
|
34
|
-
```
|
|
35
|
-
|
|
36
|
-
**标准部署只填 `MBI_PLATFORM_URL`。** 它是门户 HTTPS 地址(可含门户路径),`MBI_API_BASE_PATH` 是同源 API 前缀(默认 `/prod-api`,网关直接挂在同源根路径时设为空字符串)。浏览器须与连接器运行在同一台主机,且两者均可通过客户网络访问门户;不要关闭 TLS 校验。
|
|
37
|
-
|
|
38
|
-
**也可以直接填一个访问令牌:** 在 `env` 里增加 `MBI_ACCESS_TOKEN`(以 `bimcp_` 开头,49 个字符)。有值时连接器直接使用该令牌,**不再读取本机 `~/.mbi-bi/grant.json`,也不会打开浏览器**;令牌只驻留进程内存,绝不写盘。令牌无效或过期时工具返回 `AUTH_REQUIRED` 并提示去连接设置里更新,此时调用 `reauthorize` 不会生效(它只用于浏览器授权模式)。留空则完全走浏览器授权。适合无人值守、审核或自动化环境。
|
|
39
|
-
|
|
40
|
-
```json
|
|
41
|
-
{
|
|
42
|
-
"env": {
|
|
43
|
-
"MBI_PLATFORM_URL": "https://bi.example.com",
|
|
44
|
-
"MBI_API_BASE_PATH": "/prod-api",
|
|
45
|
-
"MBI_ACCESS_TOKEN": "bimcp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
|
|
46
|
-
}
|
|
47
|
-
}
|
|
48
|
-
```
|
|
49
|
-
|
|
50
|
-
**也可以完全通过会话配置地址。** 用户明确说出门户地址后,Agent 调用 `configure_platform`;地址保存在本机 `~/.mbi-senseX/platform.json`,之后无需编辑宿主 `mcp.json`。示例:
|
|
51
|
-
|
|
52
|
-
```text
|
|
53
|
-
把数据中台地址配置为 https://bi.example.com
|
|
54
|
-
```
|
|
55
|
-
|
|
56
|
-
非标准网关前缀可在同一次配置中传 `apiBasePath`。切换地址会关闭旧地址的本地连接、尽力撤销旧 access token,并清除旧授权;新地址仍需重新登录授权。`MBI_PLATFORM_URL` 和 `MBI_API_BASE_PATH` 现在只作为首次启动时的默认值,已通过会话保存的地址优先。
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
```json
|
|
61
|
-
{
|
|
62
|
-
"env": {
|
|
63
|
-
"MBI_PLATFORM_URL": "http://
|
|
64
|
-
"
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
三个开关互不影响,只按"地址是否命中各自的放行条件"判断:`MBI_ALLOW_INSECURE_LOCALHOST` → 仅本机主机名;`MBI_ALLOW_INSECURE_PRIVATE_NETWORK` → 仅 RFC1918 / IPv6 ULA;`MBI_ALLOW_INSECURE_HTTP` → 任意 http 主机。
|
|
99
|
-
|
|
100
|
-
首次调用工具会打开浏览器。用中台账号登录,确认租户并点击批准,看到成功提示后在宿主重试同一工具。连接器把令牌缓存到本机用户目录 `~/.mbi-bi/grant.json`(POSIX 上以 0600 权限创建;Windows 位于当前用户配置文件目录下),令牌初始有效期为 7 天,并在每次成功使用时自动重新计算 7 天;进程重启后自动从该文件恢复未过期令牌。只有连续 7 天未使用或服务端判定失效(401)时才重新授权并要求批准。用户可以在门户 `/external-bi/connections` 撤销当前账号在当前租户下的全部 BI MCP 连接;撤销后本地缓存会在下一次请求被服务端拒绝时清除。连接器不要求提供中台密码或 Web token。
|
|
101
|
-
|
|
102
|
-
用户要换账号、换租户,或怀疑缓存令牌已经失效时,让 Agent 调用 `reauthorize`(无参数):它尽力撤销服务端令牌、删除本机缓存 `~/.mbi-bi/grant.json`,并立刻打开新的授权页;工具本身立即返回,不阻塞对话。用户在浏览器里批准后,重新调用目标工具即可。手工删除 `~/.mbi-bi/grant.json` 效果相同,但下一次工具调用仍会自动打开浏览器。注意授权回调只监听 127.0.0.1 的随机端口、等待 300 秒(5 分钟),宿主配置里的 `timeout` 必须大于这个窗口(建议 360000 或更大),否则进程会被提前结束、浏览器只剩 `ERR_CONNECTION_REFUSED`。
|
|
103
|
-
|
|
104
|
-
## 查询语义和版本
|
|
105
|
-
|
|
106
|
-
1. 用 `get_analysis_config` 查业务 ID 和 `semanticVersion`;如要应用本体,用 `get_business_ontology` 查该 App 的生产 ACTIVE 发布,复制其中的 `ontologyVersion`(即 `releaseId`)。读跨 App 本体需要所有依赖 App 的权限,不能据此做跨 App 聚合或 JOIN。
|
|
107
|
-
2. `query_metrics` 每次只查询一个 App。要限定日期,例如传 `dateRange: { "dimensionId": "205", "from": "2026-10-01", "toExclusive": "2026-11-01" }`。起日包含,止日不包含,最多 366 天。用配置中 `dateRangeSupported` 的真实日历维度;有多个时明确指定,不能用字段名或表达式。
|
|
108
|
-
3. 中台校验实际日期选择和指定版本的本体规则。不能安全应用筛选、版本无权访问或存在未支持的约束时,工具返回错误;不要移除用户要求的约束重试。旧服务端不支持这些新参数,本地连接器和中台各服务应按 [部署与验收](../mbi-agent-service/docs/50-external-bi-mcp-deployment.md) 配套升级。
|
|
109
|
-
|
|
110
|
-
## Profile 控制的能力
|
|
111
|
-
|
|
112
|
-
1. 调用 `get_agent_profiles`。只返回当前平台账号通过 USE/MANAGE ACL、且未停用、未被显式 DENY 的业务 Profile;同时给出当前角色下真正可用的能力。内部 `supervisor` 与 `demo_delivery` 不对外暴露。
|
|
113
|
-
2. 调用 `get_agent_tools` 并传 `agentId`。平台会按 Profile 能力和角色过滤真实连接器工具:读取要求 `data_query`,连接器写操作要求 `data_change`,大屏要求 `mashup_board`,原生 Sheet 交付要求 `sheet_delivery`。所有写操作还必须具备 `agent:write`。
|
|
114
|
-
3. 调用 `call_agent_tool`,传同一个 `agentId`、工具名和工具参数。服务端会重新读取当前用户、角色、Profile ACL、租户开关、License、App ACL 和工具放行状态。多步骤任务复用第一次返回的 `executionId`;写操作先调用 `update_plan`。不能在参数里传 `tenantId`、`userId` 或内部会话身份。
|
|
115
|
-
|
|
116
|
-
如果 `agent:write` 被收回、Profile ACL 被撤销、Profile 被停用、能力被移出白名单或工具管理关闭,下一次调用会拒绝。`get_agent_tools` 不返回未授权的写工具;`publish_mashup_extension` 不直接开放,大屏发布必须经过 `mashup_board` 的版本化验收闸门。
|
|
117
|
-
|
|
118
|
-
## 打包与上架
|
|
119
|
-
|
|
120
|
-
运行 `npm pack --dry-run` 检查文件,再运行 `npm publish --access public` 发布到 `@miaocedata/mbi-bi-mcp@0.2.4`(发布前需在 npmjs.com 拥有 `miaocedata` 组织,否则会报 `404 Scope not found`),市场包用 `connector/mcp.json` 里固定的版本号启动。`connector/mcp.json` 的 `npmRegistries` 按 `registry.npmjs.org` → `registry.npmmirror.com` 顺序回退:npm 官方仓库是权威源,国内镜像只做兜底,避免只配镜像时新版本尚未同步导致 `npx` 404。后续每次升级必须先递增 `package.json` 的版本号再发布,并同步修改 `connector/mcp.json` 与 `connector/connector-meta.json` 里的版本号;只向 WorkBuddy 提交所需连接器材料,不把中台服务、Python connector、客户地址或任何凭证打进市场包。
|
|
121
|
-
|
|
122
|
-
> **提审前须知(本地定制)**:当前 `src/client.js` 将滑动 7 天令牌持久化到本机用户目录(`~/.mbi-bi/grant.json`),目的是避免宿主关闭或每轮对话重启进程后反复授权。令牌文件不在本包目录内,不会随 `npm pack` 进入市场包;但长期凭据落盘属于安全敏感行为,正式提审前须重新评估是否接受。若需恢复短时令牌设计,用同目录的 `src/client.js.bak` 覆盖 `src/client.js`,并把上面的有效期说明同步改回。
|
|
123
|
-
|
|
124
|
-
说明文档见 `../mbi-agent-service/docs/50-external-bi-mcp-deployment.md`。涉及客户数据外发时,要同时检查宿主模型的使用与留存策略:中台数据不经 Sense X Agent,但经授权返回给外部宿主后,由宿主处理。
|
|
1
|
+
# 数据中台 BI MCP · 本地连接器
|
|
2
|
+
|
|
3
|
+
这是 Node.js 22+ 的 **stdio** MCP。它只通过中台对外接口取数,不直连任何底层数据引擎,也不启动可见的 Sense X 对话。它提供 `configure_platform`(设置/切换地址)、`reauthorize`(换账号后重新认证)、`get_analysis_config`(分析配置)、`get_business_ontology`(已发布本体)、`query_metrics`(已登记指标查询),以及 `get_agent_profiles`、`get_agent_tools`、`call_agent_tool`。写看板、原生 Sheet 交付和 Mashup 大屏完全复用平台 `agent:write`、Agent Profile USE ACL、Profile 能力白名单和原有交付门禁。客户须部署中台、持有有效 License,由中台管理员启用该租户的「外部问数」,再使用有资源权限和相应 Profile 的中台账号授权。无需单独签发 WorkBuddy License。
|
|
4
|
+
|
|
5
|
+
## 本地联调(无需 npm 发布)
|
|
6
|
+
|
|
7
|
+
在本包目录运行 `npm ci`、`npm test`。在宿主 MCP 配置中加入以下服务(路径替换成实际绝对路径;`node` 需在宿主的 PATH 中):
|
|
8
|
+
|
|
9
|
+
```json
|
|
10
|
+
{
|
|
11
|
+
"mcpServers": {
|
|
12
|
+
"mbi-senseX": {
|
|
13
|
+
"command": "node",
|
|
14
|
+
"args": ["D:/path/to/mbi-external-bi-mcp/src/index.js"],
|
|
15
|
+
"env": {
|
|
16
|
+
"MBI_PLATFORM_URL": "https://bi.example.com"
|
|
17
|
+
}
|
|
18
|
+
}
|
|
19
|
+
}
|
|
20
|
+
}
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
- **WorkBuddy**:先用本地 stdio 配置联调。`connector/mcp.json` 是 npm 包发布后的提审配置示例,不是已确认的市场包格式;应在提审前用 WorkBuddy 的实际版本验证配置、首次授权和重试行为。
|
|
24
|
+
- **Claude Code**:同形状 JSON 可配置到项目 `.mcp.json`;不要把客户实际地址提交到公开仓库。也可使用本机用户级 MCP 配置。
|
|
25
|
+
- **Codex**:本地 `config.toml` 使用下列配置。云端运行环境不在本次支持范围内。
|
|
26
|
+
|
|
27
|
+
```toml
|
|
28
|
+
[mcp_servers.mbi-senseX]
|
|
29
|
+
command = "node"
|
|
30
|
+
args = ["D:/path/to/mbi-external-bi-mcp/src/index.js"]
|
|
31
|
+
|
|
32
|
+
[mcp_servers.mbi-senseX.env]
|
|
33
|
+
MBI_PLATFORM_URL = "https://bi.example.com"
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
**标准部署只填 `MBI_PLATFORM_URL`。** 它是门户 HTTPS 地址(可含门户路径),`MBI_API_BASE_PATH` 是同源 API 前缀(默认 `/prod-api`,网关直接挂在同源根路径时设为空字符串)。浏览器须与连接器运行在同一台主机,且两者均可通过客户网络访问门户;不要关闭 TLS 校验。
|
|
37
|
+
|
|
38
|
+
**也可以直接填一个访问令牌:** 在 `env` 里增加 `MBI_ACCESS_TOKEN`(以 `bimcp_` 开头,49 个字符)。有值时连接器直接使用该令牌,**不再读取本机 `~/.mbi-bi/grant.json`,也不会打开浏览器**;令牌只驻留进程内存,绝不写盘。令牌无效或过期时工具返回 `AUTH_REQUIRED` 并提示去连接设置里更新,此时调用 `reauthorize` 不会生效(它只用于浏览器授权模式)。留空则完全走浏览器授权。适合无人值守、审核或自动化环境。
|
|
39
|
+
|
|
40
|
+
```json
|
|
41
|
+
{
|
|
42
|
+
"env": {
|
|
43
|
+
"MBI_PLATFORM_URL": "https://bi.example.com",
|
|
44
|
+
"MBI_API_BASE_PATH": "/prod-api",
|
|
45
|
+
"MBI_ACCESS_TOKEN": "bimcp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
|
|
46
|
+
}
|
|
47
|
+
}
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
**也可以完全通过会话配置地址。** 用户明确说出门户地址后,Agent 调用 `configure_platform`;地址保存在本机 `~/.mbi-senseX/platform.json`,之后无需编辑宿主 `mcp.json`。示例:
|
|
51
|
+
|
|
52
|
+
```text
|
|
53
|
+
把数据中台地址配置为 https://bi.example.com
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
非标准网关前缀可在同一次配置中传 `apiBasePath`。切换地址会关闭旧地址的本地连接、尽力撤销旧 access token,并清除旧授权;新地址仍需重新登录授权。`MBI_PLATFORM_URL` 和 `MBI_API_BASE_PATH` 现在只作为首次启动时的默认值,已通过会话保存的地址优先。
|
|
57
|
+
|
|
58
|
+
`MBI_PLATFORM_URL` 同时支持 http 与 https,不需要任何额外开关:本机 `http://localhost:8080`、内网 `http://192.168.3.28:8080`、内网穿透域名 `http://97zj0061no79.vicp.fun:57101` 都可以直接填。
|
|
59
|
+
|
|
60
|
+
```json
|
|
61
|
+
{
|
|
62
|
+
"env": {
|
|
63
|
+
"MBI_PLATFORM_URL": "http://97zj0061no79.vicp.fun:57101",
|
|
64
|
+
"MBI_API_BASE_PATH": "/prod-api"
|
|
65
|
+
}
|
|
66
|
+
}
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
⚠️ http 是明文传输:`Authorization: Bearer bimcp_...` 与所有报表数据都不加密,链路上任何一跳都能抓到并复用这枚 7 天有效的只读令牌。生产环境请优先使用 https 域名,只有客户内网确实没有 TLS 时才用 http。
|
|
70
|
+
|
|
71
|
+
> 历史版本用 `MBI_ALLOW_INSECURE_LOCALHOST`、`MBI_ALLOW_INSECURE_PRIVATE_NETWORK`、`MBI_ALLOW_INSECURE_HTTP` 三个开关控制 http 放行;0.2.5 起已移除,这三个环境变量不再生效,可以从配置里删掉。
|
|
72
|
+
|
|
73
|
+
首次调用工具会打开浏览器。用中台账号登录,确认租户并点击批准,看到成功提示后在宿主重试同一工具。连接器把令牌缓存到本机用户目录 `~/.mbi-bi/grant.json`(POSIX 上以 0600 权限创建;Windows 位于当前用户配置文件目录下),令牌初始有效期为 7 天,并在每次成功使用时自动重新计算 7 天;进程重启后自动从该文件恢复未过期令牌。只有连续 7 天未使用或服务端判定失效(401)时才重新授权并要求批准。用户可以在门户 `/external-bi/connections` 撤销当前账号在当前租户下的全部 BI MCP 连接;撤销后本地缓存会在下一次请求被服务端拒绝时清除。连接器不要求提供中台密码或 Web token。
|
|
74
|
+
|
|
75
|
+
用户要换账号、换租户,或怀疑缓存令牌已经失效时,让 Agent 调用 `reauthorize`(无参数):它尽力撤销服务端令牌、删除本机缓存 `~/.mbi-bi/grant.json`,并立刻打开新的授权页;工具本身立即返回,不阻塞对话。用户在浏览器里批准后,重新调用目标工具即可。手工删除 `~/.mbi-bi/grant.json` 效果相同,但下一次工具调用仍会自动打开浏览器。注意授权回调只监听 127.0.0.1 的随机端口、等待 300 秒(5 分钟),宿主配置里的 `timeout` 必须大于这个窗口(建议 360000 或更大),否则进程会被提前结束、浏览器只剩 `ERR_CONNECTION_REFUSED`。
|
|
76
|
+
|
|
77
|
+
## 查询语义和版本
|
|
78
|
+
|
|
79
|
+
1. 用 `get_analysis_config` 查业务 ID 和 `semanticVersion`;如要应用本体,用 `get_business_ontology` 查该 App 的生产 ACTIVE 发布,复制其中的 `ontologyVersion`(即 `releaseId`)。读跨 App 本体需要所有依赖 App 的权限,不能据此做跨 App 聚合或 JOIN。
|
|
80
|
+
2. `query_metrics` 每次只查询一个 App。要限定日期,例如传 `dateRange: { "dimensionId": "205", "from": "2026-10-01", "toExclusive": "2026-11-01" }`。起日包含,止日不包含,最多 366 天。用配置中 `dateRangeSupported` 的真实日历维度;有多个时明确指定,不能用字段名或表达式。
|
|
81
|
+
3. 中台校验实际日期选择和指定版本的本体规则。不能安全应用筛选、版本无权访问或存在未支持的约束时,工具返回错误;不要移除用户要求的约束重试。旧服务端不支持这些新参数,本地连接器和中台各服务应按 [部署与验收](../mbi-agent-service/docs/50-external-bi-mcp-deployment.md) 配套升级。
|
|
82
|
+
|
|
83
|
+
## Profile 控制的能力
|
|
84
|
+
|
|
85
|
+
1. 调用 `get_agent_profiles`。只返回当前平台账号通过 USE/MANAGE ACL、且未停用、未被显式 DENY 的业务 Profile;同时给出当前角色下真正可用的能力。内部 `supervisor` 与 `demo_delivery` 不对外暴露。
|
|
86
|
+
2. 调用 `get_agent_tools` 并传 `agentId`。平台会按 Profile 能力和角色过滤真实连接器工具:读取要求 `data_query`,连接器写操作要求 `data_change`,大屏要求 `mashup_board`,原生 Sheet 交付要求 `sheet_delivery`。所有写操作还必须具备 `agent:write`。
|
|
87
|
+
3. 调用 `call_agent_tool`,传同一个 `agentId`、工具名和工具参数。服务端会重新读取当前用户、角色、Profile ACL、租户开关、License、App ACL 和工具放行状态。多步骤任务复用第一次返回的 `executionId`;写操作先调用 `update_plan`。不能在参数里传 `tenantId`、`userId` 或内部会话身份。
|
|
88
|
+
|
|
89
|
+
如果 `agent:write` 被收回、Profile ACL 被撤销、Profile 被停用、能力被移出白名单或工具管理关闭,下一次调用会拒绝。`get_agent_tools` 不返回未授权的写工具;`publish_mashup_extension` 不直接开放,大屏发布必须经过 `mashup_board` 的版本化验收闸门。
|
|
90
|
+
|
|
91
|
+
## 打包与上架
|
|
92
|
+
|
|
93
|
+
运行 `npm pack --dry-run` 检查文件,再运行 `npm publish --access public` 发布到 `@miaocedata/mbi-bi-mcp@0.2.5`(发布前需在 npmjs.com 拥有 `miaocedata` 组织,否则会报 `404 Scope not found`),市场包用 `connector/mcp.json` 里固定的版本号启动。`connector/mcp.json` 的 `npmRegistries` 按 `registry.npmjs.org` → `registry.npmmirror.com` 顺序回退:npm 官方仓库是权威源,国内镜像只做兜底,避免只配镜像时新版本尚未同步导致 `npx` 404。后续每次升级必须先递增 `package.json` 的版本号再发布,并同步修改 `connector/mcp.json` 与 `connector/connector-meta.json` 里的版本号;只向 WorkBuddy 提交所需连接器材料,不把中台服务、Python connector、客户地址或任何凭证打进市场包。
|
|
94
|
+
|
|
95
|
+
> **提审前须知(本地定制)**:当前 `src/client.js` 将滑动 7 天令牌持久化到本机用户目录(`~/.mbi-bi/grant.json`),目的是避免宿主关闭或每轮对话重启进程后反复授权。令牌文件不在本包目录内,不会随 `npm pack` 进入市场包;但长期凭据落盘属于安全敏感行为,正式提审前须重新评估是否接受。若需恢复短时令牌设计,用同目录的 `src/client.js.bak` 覆盖 `src/client.js`,并把上面的有效期说明同步改回。
|
|
96
|
+
|
|
97
|
+
说明文档见 `../mbi-agent-service/docs/50-external-bi-mcp-deployment.md`。涉及客户数据外发时,要同时检查宿主模型的使用与留存策略:中台数据不经 Sense X Agent,但经授权返回给外部宿主后,由宿主处理。
|
package/package.json
CHANGED
|
@@ -1,26 +1,26 @@
|
|
|
1
|
-
{
|
|
2
|
-
"name": "@miaocedata/mbi-bi-mcp",
|
|
3
|
-
"version": "0.2.
|
|
4
|
-
"description": "Read-only stdio MCP adapter for authorized data platform deployments",
|
|
5
|
-
"type": "module",
|
|
6
|
-
"license": "UNLICENSED",
|
|
7
|
-
"engines": {
|
|
8
|
-
"node": ">=20.6.0"
|
|
9
|
-
},
|
|
10
|
-
"bin": {
|
|
11
|
-
"mbi-bi-mcp": "src/index.js"
|
|
12
|
-
},
|
|
13
|
-
"scripts": {
|
|
14
|
-
"test": "node --test"
|
|
15
|
-
},
|
|
16
|
-
"files": [
|
|
17
|
-
"src/*.js",
|
|
18
|
-
"src/tool-manifest.json",
|
|
19
|
-
"src/magic-data-mark.png",
|
|
20
|
-
"README.md"
|
|
21
|
-
],
|
|
22
|
-
"dependencies": {
|
|
23
|
-
"@modelcontextprotocol/sdk": "1.32.2",
|
|
24
|
-
"ajv": "8.18.0"
|
|
25
|
-
}
|
|
26
|
-
}
|
|
1
|
+
{
|
|
2
|
+
"name": "@miaocedata/mbi-bi-mcp",
|
|
3
|
+
"version": "0.2.5",
|
|
4
|
+
"description": "Read-only stdio MCP adapter for authorized data platform deployments",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"license": "UNLICENSED",
|
|
7
|
+
"engines": {
|
|
8
|
+
"node": ">=20.6.0"
|
|
9
|
+
},
|
|
10
|
+
"bin": {
|
|
11
|
+
"mbi-bi-mcp": "src/index.js"
|
|
12
|
+
},
|
|
13
|
+
"scripts": {
|
|
14
|
+
"test": "node --test"
|
|
15
|
+
},
|
|
16
|
+
"files": [
|
|
17
|
+
"src/*.js",
|
|
18
|
+
"src/tool-manifest.json",
|
|
19
|
+
"src/magic-data-mark.png",
|
|
20
|
+
"README.md"
|
|
21
|
+
],
|
|
22
|
+
"dependencies": {
|
|
23
|
+
"@modelcontextprotocol/sdk": "1.32.2",
|
|
24
|
+
"ajv": "8.18.0"
|
|
25
|
+
}
|
|
26
|
+
}
|
package/src/auth.js
CHANGED
|
@@ -112,47 +112,11 @@ export function callbackPage(kind = 'success', nonce = '') {
|
|
|
112
112
|
</html>`;
|
|
113
113
|
}
|
|
114
114
|
|
|
115
|
-
// 允许明文 HTTP 的本机主机名,仅用于本地联调
|
|
116
|
-
const LOOPBACK_HOSTS = ['localhost', '127.0.0.1', '[::1]', '::1'];
|
|
117
|
-
|
|
118
|
-
/**
|
|
119
|
-
* 判断主机名是否属于内网私有地址段。
|
|
120
|
-
* 只服务于"客户内网用 HTTP 部署"的场景,必须再配合 MBI_ALLOW_INSECURE_PRIVATE_NETWORK=true 才放行,
|
|
121
|
-
* 避免公网域名/IP 意外走明文传输。
|
|
122
|
-
*/
|
|
123
|
-
function isPrivateNetworkHost(hostname) {
|
|
124
|
-
const ipv4 = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(hostname);
|
|
125
|
-
if (ipv4) {
|
|
126
|
-
const first = Number(ipv4[1]);
|
|
127
|
-
const second = Number(ipv4[2]);
|
|
128
|
-
if (first === 10) return true; // 10.0.0.0/8
|
|
129
|
-
if (first === 172 && second >= 16 && second <= 31) return true; // 172.16.0.0/12
|
|
130
|
-
if (first === 192 && second === 168) return true; // 192.168.0.0/16
|
|
131
|
-
if (first === 127) return true; // 127.0.0.0/8
|
|
132
|
-
return false;
|
|
133
|
-
}
|
|
134
|
-
const host = hostname.replace(/^\[|\]$/g, '').toLowerCase();
|
|
135
|
-
if (host === '::1') return true;
|
|
136
|
-
return /^f[cd][0-9a-f]{2}:/.test(host); // IPv6 唯一本地地址 fc00::/7
|
|
137
|
-
}
|
|
138
|
-
|
|
139
115
|
export function platformUrls(env) {
|
|
140
116
|
const raw = env.MBI_PLATFORM_URL;
|
|
141
117
|
const insecureHttp = /^http:\/\//i.test(raw ?? '');
|
|
142
118
|
if (!raw || (!/^https:\/\//i.test(raw) && !insecureHttp) || /[\\\s?#]/.test(raw)) throw new Error('Invalid MBI_PLATFORM_URL');
|
|
143
119
|
const base = new URL(raw);
|
|
144
|
-
if (insecureHttp) {
|
|
145
|
-
const loopback = LOOPBACK_HOSTS.includes(base.hostname);
|
|
146
|
-
const allowLocalhost = loopback && env.MBI_ALLOW_INSECURE_LOCALHOST === 'true';
|
|
147
|
-
const allowPrivate = env.MBI_ALLOW_INSECURE_PRIVATE_NETWORK === 'true' && isPrivateNetworkHost(base.hostname);
|
|
148
|
-
// 内网穿透/映射场景下门户只有 http 域名(例如花生壳的 *.vicp.fun),用这个开关整体放行
|
|
149
|
-
const allowAnyHost = env.MBI_ALLOW_INSECURE_HTTP === 'true';
|
|
150
|
-
if (!allowLocalhost && !allowPrivate && !allowAnyHost) {
|
|
151
|
-
throw new Error('Insecure HTTP requires MBI_ALLOW_INSECURE_LOCALHOST=true for localhost, '
|
|
152
|
-
+ 'MBI_ALLOW_INSECURE_PRIVATE_NETWORK=true for private network hosts, '
|
|
153
|
-
+ 'or MBI_ALLOW_INSECURE_HTTP=true for any host');
|
|
154
|
-
}
|
|
155
|
-
}
|
|
156
120
|
if (base.username || base.password || !/^\/(?:[A-Za-z0-9_-]+\/)*[A-Za-z0-9_-]*$/.test(base.pathname)) throw new Error('Invalid MBI_PLATFORM_URL');
|
|
157
121
|
const prefix = env.MBI_API_BASE_PATH ?? '/prod-api';
|
|
158
122
|
if (prefix && !/^(?:\/[A-Za-z0-9_-]+)+$/.test(prefix)) throw new Error('Invalid MBI_API_BASE_PATH');
|
package/src/client.js
CHANGED
|
@@ -309,12 +309,10 @@ export class PlatformSession {
|
|
|
309
309
|
this.#reload();
|
|
310
310
|
}
|
|
311
311
|
|
|
312
|
-
// 把地址不可用的真实原因带给用户,避免只看到"尚未配置"
|
|
312
|
+
// 把地址不可用的真实原因带给用户,避免只看到"尚未配置"而无从下手
|
|
313
313
|
#unavailableMessage() {
|
|
314
|
-
if (typeof this.#configError === 'string' && this.#configError.includes('
|
|
315
|
-
return '
|
|
316
|
-
+ '内网 IP 需设置 MBI_ALLOW_INSECURE_PRIVATE_NETWORK=true,'
|
|
317
|
-
+ '内网穿透等只有 http 域名的场景需设置 MBI_ALLOW_INSECURE_HTTP=true,或改用 HTTPS 门户地址。';
|
|
314
|
+
if (typeof this.#configError === 'string' && this.#configError.includes('MBI_PLATFORM_URL')) {
|
|
315
|
+
return '数据中台地址不可用:MBI_PLATFORM_URL 必须是 http(s) 门户地址,且不能包含空格、问号、井号或反斜杠。';
|
|
318
316
|
}
|
|
319
317
|
return '尚未配置数据中台地址。请让用户明确提供门户地址,再调用 configure_platform。';
|
|
320
318
|
}
|
|
@@ -374,12 +372,13 @@ export class PlatformSession {
|
|
|
374
372
|
next = undefined;
|
|
375
373
|
}
|
|
376
374
|
if (!next) {
|
|
377
|
-
if (typeof reason === 'string' && reason.includes('
|
|
378
|
-
return error('INVALID_ARGUMENT', '
|
|
379
|
-
+ 'MBI_ALLOW_INSECURE_LOCALHOST=true,内网 IP 需设置 MBI_ALLOW_INSECURE_PRIVATE_NETWORK=true,'
|
|
380
|
-
+ '内网穿透等只有 http 域名的场景需设置 MBI_ALLOW_INSECURE_HTTP=true,或改用 HTTPS 门户地址。');
|
|
375
|
+
if (typeof reason === 'string' && reason.includes('MBI_PLATFORM_URL')) {
|
|
376
|
+
return error('INVALID_ARGUMENT', '数据中台地址无效:请提供 http(s) 门户地址,不能包含空格、问号、井号或反斜杠。');
|
|
381
377
|
}
|
|
382
|
-
|
|
378
|
+
if (typeof reason === 'string' && reason.includes('MBI_API_BASE_PATH')) {
|
|
379
|
+
return error('INVALID_ARGUMENT', '接口前缀无效:应形如 /prod-api,只能包含字母、数字、下划线和短横线。');
|
|
380
|
+
}
|
|
381
|
+
return error('INVALID_ARGUMENT', '数据中台地址无效;正式环境建议使用 HTTPS 门户地址。');
|
|
383
382
|
}
|
|
384
383
|
|
|
385
384
|
if (this.#config && this.#client
|
package/src/index.js
CHANGED
|
@@ -1,25 +1,25 @@
|
|
|
1
|
-
#!/usr/bin/env node
|
|
2
|
-
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
|
|
3
|
-
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
|
|
4
|
-
import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
|
|
5
|
-
import { PlatformSession, tools } from './client.js';
|
|
6
|
-
|
|
7
|
-
async function main() {
|
|
8
|
-
const session = new PlatformSession(process.env);
|
|
9
|
-
const server = new Server({ name: 'mbi-senseX', version: '0.2.
|
|
10
|
-
server.setRequestHandler(ListToolsRequestSchema, () => ({ tools }));
|
|
11
|
-
server.setRequestHandler(CallToolRequestSchema, ({ params }) => session.call(params.name, params.arguments));
|
|
12
|
-
server.onerror = () => console.error('[mbi-senseX-mcp] MCP protocol error.');
|
|
13
|
-
server.onclose = () => session.close();
|
|
14
|
-
for (const signal of ['SIGINT', 'SIGTERM']) process.once(signal, () => {
|
|
15
|
-
session.close();
|
|
16
|
-
void server.close().finally(() => process.exit(0));
|
|
17
|
-
});
|
|
18
|
-
process.stdin.once('end', () => session.close());
|
|
19
|
-
await server.connect(new StdioServerTransport());
|
|
20
|
-
}
|
|
21
|
-
|
|
22
|
-
main().catch(() => {
|
|
23
|
-
console.error('[mbi-senseX-mcp]
|
|
24
|
-
process.exitCode = 1;
|
|
25
|
-
});
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
|
|
3
|
+
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
|
|
4
|
+
import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
|
|
5
|
+
import { PlatformSession, tools } from './client.js';
|
|
6
|
+
|
|
7
|
+
async function main() {
|
|
8
|
+
const session = new PlatformSession(process.env);
|
|
9
|
+
const server = new Server({ name: 'mbi-senseX', version: '0.2.5' }, { capabilities: { tools: {} } });
|
|
10
|
+
server.setRequestHandler(ListToolsRequestSchema, () => ({ tools }));
|
|
11
|
+
server.setRequestHandler(CallToolRequestSchema, ({ params }) => session.call(params.name, params.arguments));
|
|
12
|
+
server.onerror = () => console.error('[mbi-senseX-mcp] MCP protocol error.');
|
|
13
|
+
server.onclose = () => session.close();
|
|
14
|
+
for (const signal of ['SIGINT', 'SIGTERM']) process.once(signal, () => {
|
|
15
|
+
session.close();
|
|
16
|
+
void server.close().finally(() => process.exit(0));
|
|
17
|
+
});
|
|
18
|
+
process.stdin.once('end', () => session.close());
|
|
19
|
+
await server.connect(new StdioServerTransport());
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
main().catch(() => {
|
|
23
|
+
console.error('[mbi-senseX-mcp] 启动失败。请检查 MBI_PLATFORM_URL(http 或 https 门户地址)、MBI_API_BASE_PATH,并确认地址里没有空格、问号或井号。');
|
|
24
|
+
process.exitCode = 1;
|
|
25
|
+
});
|