@miaocedata/mbi-bi-mcp 0.2.4 → 0.2.6

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 CHANGED
@@ -1,124 +1,103 @@
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
- 如果本机验收环境暂时没有 HTTPS,可以显式设置 `MBI_ALLOW_INSECURE_LOCALHOST=true`,并只把 `MBI_PLATFORM_URL` 指向 `localhost`、`127.0.0.1` 或 `::1`。服务端 `mbi-auth` 的 `dev` profile 对应启用 `mbi.auth.bi.allow-insecure-localhost=true`;该开关不会允许局域网 IP 或其他主机,仅用于同一台电脑上的开发联调。客户正式环境仍必须使用 HTTPS。
59
-
60
- ```json
61
- {
62
- "env": {
63
- "MBI_PLATFORM_URL": "http://127.0.0.1:8080",
64
- "MBI_ALLOW_INSECURE_LOCALHOST": "true",
65
- "MBI_API_BASE_PATH": "/prod-api"
66
- }
67
- }
68
- ```
69
-
70
- **客户内网只能走 HTTP 时**(例如只有 `http://192.168.3.28:8080`,没有可用的 HTTPS 反代),可以额外设置 `MBI_ALLOW_INSECURE_PRIVATE_NETWORK=true`,此时只放行 RFC1918 私网地址(`10.0.0.0/8`、`172.16.0.0/12`、`192.168.0.0/16`、`127.0.0.0/8`)与 IPv6 唯一本地地址(`fc00::/7`);公网域名和公网 IP 即使打开该开关也一律拒绝。
71
-
72
- ```json
73
- {
74
- "env": {
75
- "MBI_PLATFORM_URL": "http://192.168.3.28:8080",
76
- "MBI_ALLOW_INSECURE_PRIVATE_NETWORK": "true",
77
- "MBI_API_BASE_PATH": "/prod-api"
78
- }
79
- }
80
- ```
81
-
82
- ⚠️ 打开私网 HTTP 后,`Authorization: Bearer bimcp_...` 会以明文经过内网,同网段的任何人都能抓包并复用这枚 7 天有效的只读令牌,读走整个租户的 App、指标与业务本体。仅在物理/逻辑隔离的内网启用,并优先给内网服务补一层 HTTPS 反代。市场表单不提供这个开关,需要用户在宿主 `mcp.json` 里自行添加。
83
-
84
- **门户只有 http 域名时**(内网穿透把内网服务映射成一个 http 域名,例如花生壳的 `http://97zj0061no79.vicp.fun:57101`),上面两个开关都不覆盖,因为整个主机名既不是本机也不是私网 IP。此时设置 `MBI_ALLOW_INSECURE_HTTP=true`,它对任意主机名/IP 的 http 地址放行。
85
-
86
- ```json
87
- {
88
- "env": {
89
- "MBI_PLATFORM_URL": "http://97zj0061no79.vicp.fun:57101",
90
- "MBI_ALLOW_INSECURE_HTTP": "true",
91
- "MBI_API_BASE_PATH": "/prod-api"
92
- }
93
- }
94
- ```
95
-
96
- ⚠️ 这是范围最大的开关:任何 http 地址(含公网)都会被放行,令牌与业务数据全程明文。只应在临时联调或客户明确接受风险的内网穿透场景使用,长期部署请换成 HTTPS 域名。
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
+ **工具清单按服务端实际能力下发。** 连接器会用一次 `tools/list` 探测服务端真正提供的工具(结果缓存 60 秒),只把服务端认识的清单工具列给宿主,本地的 `configure_platform`、`reauthorize` 始终保留。这样中台未升级时,模型不会去调用注定返回 `Unknown tool` 的工具;探测失败(网络异常等)时退回完整清单,不影响正常使用。
84
+
85
+ **错误信息一定有可读原因。** 服务端的工具错误只带错误码,连接器会按码补一句中文说明(例如 `DATE_DIMENSION_UNAVAILABLE` → 「指定的日期维度不可用,请从 get_analysis_config 返回的日期维度中选择。」),并且只翻译白名单里的错误码,绝不把服务端原始文本透传给模型。协议级错误(例如旧版服务端不认识某个工具)会显示为 `TOOL_NOT_SUPPORTED`,并提示改用 `get_analysis_config`、`get_business_ontology`、`query_metrics`。HTTP 层失败也会带上状态码与排查方向(门户地址、网关路由),不再是一句空的 `BI_SERVICE_UNAVAILABLE`。
86
+
87
+ ## Profile 控制的能力
88
+
89
+ 1. 调用 `get_agent_profiles`。只返回当前平台账号通过 USE/MANAGE ACL、且未停用、未被显式 DENY 的业务 Profile;同时给出当前角色下真正可用的能力。内部 `supervisor` 与 `demo_delivery` 不对外暴露。
90
+ 2. 调用 `get_agent_tools` 并传 `agentId`。平台会按 Profile 能力和角色过滤真实连接器工具:读取要求 `data_query`,连接器写操作要求 `data_change`,大屏要求 `mashup_board`,原生 Sheet 交付要求 `sheet_delivery`。所有写操作还必须具备 `agent:write`。
91
+ 3. 调用 `call_agent_tool`,传同一个 `agentId`、工具名和工具参数。服务端会重新读取当前用户、角色、Profile ACL、租户开关、License、App ACL 和工具放行状态。多步骤任务复用第一次返回的 `executionId`;写操作先调用 `update_plan`。不能在参数里传 `tenantId`、`userId` 或内部会话身份。
92
+
93
+ 如果 `agent:write` 被收回、Profile ACL 被撤销、Profile 被停用、能力被移出白名单或工具管理关闭,下一次调用会拒绝。`get_agent_tools` 不返回未授权的写工具;`publish_mashup_extension` 不直接开放,大屏发布必须经过 `mashup_board` 的版本化验收闸门。
94
+
95
+ `mashup_board` 必须按 `contract → validate → prepare → preflight → verify → publish` 执行,并复用同一个 `executionId`。`publish` 只接受 `prepare` 返回的 `artifact_id`,不能重新传 spec。交互式 Sense X 可以继续启用 `design-only`;已通过 `agent:write`、Profile USE ACL 和 `mashup_board` 能力校验的外部 MCP 执行上下文可以使用同一套版本化自动发布链。
96
+
97
+ ## 打包与上架
98
+
99
+ 运行 `npm pack --dry-run` 检查文件,再运行 `npm publish --access public` 发布到 `@miaocedata/mbi-bi-mcp@0.2.6`(发布前需在 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、客户地址或任何凭证打进市场包。
100
+
101
+ > **提审前须知(本地定制)**:当前 `src/client.js` 将滑动 7 天令牌持久化到本机用户目录(`~/.mbi-bi/grant.json`),目的是避免宿主关闭或每轮对话重启进程后反复授权。令牌文件不在本包目录内,不会随 `npm pack` 进入市场包;但长期凭据落盘属于安全敏感行为,正式提审前须重新评估是否接受。若需恢复短时令牌设计,用同目录的 `src/client.js.bak` 覆盖 `src/client.js`,并把上面的有效期说明同步改回。
102
+
103
+ 说明文档见 `../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",
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.6",
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
@@ -33,6 +33,8 @@ export const reauthorizeTool = {
33
33
  };
34
34
  const jvmTools = JSON.parse(readFileSync(new URL('./tool-manifest.json', import.meta.url), 'utf8'));
35
35
  export const tools = [configurationTool, reauthorizeTool, ...jvmTools];
36
+ // 本地桥接器自带的两个工具,与服务端清单无关,始终对模型可见
37
+ const bridgeTools = new Set([configurationTool.name, reauthorizeTool.name]);
36
38
  const ajv = new Ajv({ strict: true });
37
39
  const validators = new Map(tools.map(({ name, inputSchema }) => [name, ajv.compile(inputSchema)]));
38
40
  const allowedErrors = new Set(['AUTH_REQUIRED', 'AUTH_UNAVAILABLE', 'SCOPE_DENIED', 'LICENSE_REQUIRED', 'BI_MCP_NOT_ENABLED',
@@ -43,7 +45,48 @@ const allowedErrors = new Set(['AUTH_REQUIRED', 'AUTH_UNAVAILABLE', 'SCOPE_DENIE
43
45
  'AGENT_PROFILE_DISABLED', 'AGENT_PROFILE_FORBIDDEN', 'AGENT_PROFILE_NOT_FOUND', 'AGENT_CAPABILITY_FORBIDDEN',
44
46
  'AGENT_CAPABILITY_UNAVAILABLE', 'AGENT_WRITE_FORBIDDEN', 'AGENT_EXECUTION_BUSY', 'AGENT_EXECUTION_NOT_FOUND',
45
47
  'AGENT_EXECUTION_UNAVAILABLE', 'PLATFORM_IDENTITY_UNAVAILABLE', 'PLAN_REQUIRED', 'DELIVERY_GATE_REQUIRED',
46
- 'TOOL_EXECUTION_FAILED']);
48
+ 'DELIVERY_ARTIFACT_REQUIRED', 'TOOL_EXECUTION_FAILED']);
49
+ // 服务端的工具错误只带错误码、不带说明文案(见 ExternalBiMcpController.toolError),
50
+ // 这里按错误码给出我们自己的一句中文提示,既让模型知道下一步怎么做,也不会把服务端原始文本透传出去。
51
+ const toolHints = new Map([
52
+ ['AUTH_REQUIRED', '授权已失效,请重新授权后再试。'],
53
+ ['AUTH_UNAVAILABLE', '授权服务暂不可用,请稍后重试。'],
54
+ ['SCOPE_DENIED', '当前授权不包含该操作所需的权限范围。'],
55
+ ['LICENSE_REQUIRED', '当前租户的 BI 授权不可用,请联系管理员。'],
56
+ ['BI_MCP_NOT_ENABLED', '当前租户尚未开通 MCP 取数能力。'],
57
+ ['RESOURCE_FORBIDDEN', '当前账号无权访问该资源。'],
58
+ ['RATE_LIMITED', '调用过于频繁,请稍后重试。'],
59
+ ['INVALID_ARGUMENT', '参数不符合该工具声明的输入结构。'],
60
+ ['SEMANTIC_VERSION_MISMATCH', '语义版本与平台不一致,请重新调用 get_analysis_config 获取最新配置。'],
61
+ ['UNSUPPORTED_QUERY_CONSTRAINT', '该查询条件不被支持,请改用已注册的指标与维度。'],
62
+ ['DATE_DIMENSION_REQUIRED', '该 App 有多个日期维度,请在 dateRange 中显式指定 dimensionId。'],
63
+ ['DATE_DIMENSION_UNAVAILABLE', '指定的日期维度不可用,请从 get_analysis_config 返回的日期维度中选择。'],
64
+ ['DATE_RANGE_NO_SELECTION', '该日期范围内没有命中数据,请调整起止日期。'],
65
+ ['DATE_MEASURE_UNSUPPORTED', '该指标不支持按日期聚合。'],
66
+ ['DATE_RANGE_UNVERIFIED', '日期范围的可用性未确认,请重新读取分析配置后再查。'],
67
+ ['ONTOLOGY_VERSION_UNAVAILABLE', '指定的业务本体版本不可用,请重新调用 get_business_ontology。'],
68
+ ['ONTOLOGY_QUERY_NOT_ALLOWED', '当前业务本体不允许该查询。'],
69
+ ['ONTOLOGY_CONSTRAINT_UNSUPPORTED', '该约束不被当前业务本体支持。'],
70
+ ['ONTOLOGY_UNAVAILABLE', '业务本体暂不可用,请稍后重试。'],
71
+ ['CONFIG_TOO_LARGE', '分析配置超出大小限制,请联系管理员。'],
72
+ ['BI_SERVICE_UNAVAILABLE', '数据中台暂不可用,请稍后重试。'],
73
+ ['QLIK_IDENTITY_NOT_CONFIGURED', '数据源访问身份未配置,请联系管理员。'],
74
+ ['QLIK_QUERY_FAILED', '数据源查询失败,请稍后重试。'],
75
+ ['AGENT_PROFILE_DISABLED', '该 Agent Profile 已停用。'],
76
+ ['AGENT_PROFILE_FORBIDDEN', '当前账号无权使用该 Agent Profile。'],
77
+ ['AGENT_PROFILE_NOT_FOUND', '未找到该 Agent Profile。'],
78
+ ['AGENT_CAPABILITY_FORBIDDEN', '该能力未在这个 Agent Profile 中开启。'],
79
+ ['AGENT_CAPABILITY_UNAVAILABLE', '该能力当前不可用。'],
80
+ ['AGENT_WRITE_FORBIDDEN', '该 Agent Profile 不允许写操作。'],
81
+ ['AGENT_EXECUTION_BUSY', '上一次执行尚未结束,请稍后再试。'],
82
+ ['AGENT_EXECUTION_NOT_FOUND', '未找到对应的执行上下文。'],
83
+ ['AGENT_EXECUTION_UNAVAILABLE', '执行上下文当前不可用。'],
84
+ ['PLATFORM_IDENTITY_UNAVAILABLE', '平台身份信息不可用,请重新授权。'],
85
+ ['PLAN_REQUIRED', '该操作需要先提交计划。'],
86
+ ['DELIVERY_GATE_REQUIRED', '该操作需要先通过交付检查。'],
87
+ ['DELIVERY_ARTIFACT_REQUIRED', '该操作需要先准备交付产物。'],
88
+ ['TOOL_EXECUTION_FAILED', '工具执行失败,请稍后重试。']
89
+ ]);
47
90
  const message = (structuredContent, isError) => ({ structuredContent, isError,
48
91
  content: [{ type: 'text', text: JSON.stringify(structuredContent) }] });
49
92
  const error = (code, description, requestId) => message({ error: { code, ...(description && { message: description }) },
@@ -147,6 +190,7 @@ export class PlatformClient {
147
190
  #sequence = 0;
148
191
  #stop = new AbortController();
149
192
  #closed = false;
193
+ #serverTools;
150
194
 
151
195
  constructor(urls, { fetcher = fetch, login = authorize, log = (text) => console.error(text),
152
196
  grantStore = persistentGrantStore, scope = urls.mcp.href, envToken } = {}) {
@@ -215,6 +259,35 @@ export class PlatformClient {
215
259
  }, false);
216
260
  }
217
261
 
262
+ // 读取服务端真正提供的工具清单。控制器只对 tools/call 校验令牌,tools/list 是公开的,
263
+ // 因此这里不带 Authorization,避免为了探测清单反而触发一次浏览器授权。
264
+ // 返回 undefined 表示探测失败,调用方按"不过滤"处理,避免网络抖动把工具全藏起来。
265
+ async serverToolNames() {
266
+ if (this.#closed) return undefined;
267
+ const cached = this.#serverTools;
268
+ if (cached && cached.expiresAt > Date.now()) return cached.names;
269
+ const id = `probe-${++this.#sequence}`;
270
+ try {
271
+ const response = await this.fetcher(this.urls.mcp, {
272
+ method: 'POST', redirect: 'error', signal: AbortSignal.any([AbortSignal.timeout(15_000), this.#stop.signal]),
273
+ headers: { 'Content-Type': 'application/json', Accept: 'application/json', 'MCP-Protocol-Version': '2025-06-18' },
274
+ body: JSON.stringify({ jsonrpc: '2.0', id, method: 'tools/list', params: {} })
275
+ });
276
+ if (!response.ok) {
277
+ void response.body?.cancel().catch(() => {});
278
+ return undefined;
279
+ }
280
+ const envelope = await readJson(response, 1_000_000);
281
+ const list = envelope?.result?.tools;
282
+ if (!Array.isArray(list)) return undefined;
283
+ const names = new Set(list.map((tool) => tool?.name).filter((name) => typeof name === 'string'));
284
+ this.#serverTools = { names, expiresAt: Date.now() + 60_000 };
285
+ return names;
286
+ } catch {
287
+ return undefined;
288
+ }
289
+ }
290
+
218
291
  #needLogin() {
219
292
  if (this.#closed) return error('BI_SERVICE_UNAVAILABLE');
220
293
  // 配置令牌模式下永不打开浏览器:空值/非法值都直接给出可操作的错误
@@ -257,13 +330,29 @@ export class PlatformClient {
257
330
  if (this.#grant === grant) { this.#grant = undefined; this.#grantStore.clear(); }
258
331
  return error('AUTH_REQUIRED', '中台授权已失效;下次调用将重新打开登录。');
259
332
  }
260
- return error(response.status === 429 ? 'RATE_LIMITED' : 'BI_SERVICE_UNAVAILABLE');
333
+ if (response.status === 429) return error('RATE_LIMITED', toolHints.get('RATE_LIMITED'));
334
+ return error('BI_SERVICE_UNAVAILABLE', `数据中台返回 HTTP ${response.status},请确认门户地址与网关路由可用。`);
261
335
  }
262
336
  const envelope = await readJson(response, 4_000_000);
263
- const result = envelope?.result;
337
+ if (envelope?.jsonrpc !== '2.0' || envelope.id !== id) {
338
+ return error('BI_SERVICE_UNAVAILABLE', '数据中台返回了无法识别的响应,请确认 MBI_PLATFORM_URL 指向平台门户而不是其它服务。');
339
+ }
340
+ // 协议级错误在 JSON-RPC 的 error 成员里(例如 Unknown tool / AUTH_REQUIRED),
341
+ // 这里只按已知错误码翻译成本地文案,绝不透传远端原文,避免把敏感信息带进模型上下文。
342
+ const rpcError = envelope.error;
343
+ if (rpcError) {
344
+ const remote = typeof rpcError.message === 'string' ? rpcError.message.trim() : '';
345
+ if (remote === 'Unknown tool') {
346
+ return error('TOOL_NOT_SUPPORTED',
347
+ '当前数据中台版本未启用该工具;请升级服务端,或改用 get_analysis_config、get_business_ontology、query_metrics。');
348
+ }
349
+ if (allowedErrors.has(remote)) return error(remote, toolHints.get(remote), rpcError.data?.requestId);
350
+ return error('BI_SERVICE_UNAVAILABLE', `数据中台返回协议错误(code=${rpcError.code ?? 'unknown'}),请稍后重试。`);
351
+ }
352
+ const result = envelope.result;
264
353
  const data = result?.structuredContent;
265
- if (envelope?.jsonrpc !== '2.0' || envelope.id !== id || !data || typeof data !== 'object' || Array.isArray(data)) {
266
- return error('BI_SERVICE_UNAVAILABLE');
354
+ if (!data || typeof data !== 'object' || Array.isArray(data)) {
355
+ return error('BI_SERVICE_UNAVAILABLE', '数据中台返回了空结果,请稍后重试。');
267
356
  }
268
357
  if (result.isError === true) {
269
358
  const code = data.error?.code;
@@ -273,12 +362,15 @@ export class PlatformClient {
273
362
  } else if (code !== 'AUTH_UNAVAILABLE') {
274
363
  this.#extend(grant);
275
364
  }
276
- return error(allowedErrors.has(code) ? code : 'BI_SERVICE_UNAVAILABLE', null, data.requestId);
365
+ // 服务端工具错误只有错误码(ExternalBiMcpController.toolError 不带 message),
366
+ // 因此这里必须补一句可读原因,否则用户只看到 isError 而不知道该怎么办。
367
+ return error(allowedErrors.has(code) ? code : 'BI_SERVICE_UNAVAILABLE',
368
+ allowedErrors.has(code) ? toolHints.get(code) : '数据中台返回了未识别的错误,请稍后重试。', data.requestId);
277
369
  }
278
- if (result.isError !== false) return error('BI_SERVICE_UNAVAILABLE');
370
+ if (result.isError !== false) return error('BI_SERVICE_UNAVAILABLE', '数据中台返回了不完整的结果,请稍后重试。');
279
371
  this.#extend(grant);
280
372
  return message(data, false);
281
- } catch { return error('BI_SERVICE_UNAVAILABLE'); }
373
+ } catch { return error('BI_SERVICE_UNAVAILABLE', '调用数据中台失败(网络或超时),请稍后重试。'); }
282
374
  }
283
375
 
284
376
  #extend(grant) {
@@ -309,12 +401,10 @@ export class PlatformSession {
309
401
  this.#reload();
310
402
  }
311
403
 
312
- // 把地址不可用的真实原因带给用户,避免只看到"尚未配置"而无从下手(典型场景是 http 地址被安全策略拒绝)
404
+ // 把地址不可用的真实原因带给用户,避免只看到"尚未配置"而无从下手
313
405
  #unavailableMessage() {
314
- if (typeof this.#configError === 'string' && this.#configError.includes('Insecure HTTP')) {
315
- return '数据中台地址是 HTTP,明文传输默认被拒绝:本机地址需设置 MBI_ALLOW_INSECURE_LOCALHOST=true,'
316
- + '内网 IP 需设置 MBI_ALLOW_INSECURE_PRIVATE_NETWORK=true,'
317
- + '内网穿透等只有 http 域名的场景需设置 MBI_ALLOW_INSECURE_HTTP=true,或改用 HTTPS 门户地址。';
406
+ if (typeof this.#configError === 'string' && this.#configError.includes('MBI_PLATFORM_URL')) {
407
+ return '数据中台地址不可用:MBI_PLATFORM_URL 必须是 http(s) 门户地址,且不能包含空格、问号、井号或反斜杠。';
318
408
  }
319
409
  return '尚未配置数据中台地址。请让用户明确提供门户地址,再调用 configure_platform。';
320
410
  }
@@ -350,6 +440,15 @@ export class PlatformSession {
350
440
  return this.#client.call(name, args);
351
441
  }
352
442
 
443
+ // 对外只宣称服务端真正支持的清单工具:线上服务端可能还是旧版本(例如只有 3 个工具),
444
+ // 若把清单里的工具全列出来,模型会去调用注定返回 Unknown tool 的工具。
445
+ async advertisedTools() {
446
+ if (!this.#client) return tools;
447
+ const names = await this.#client.serverToolNames();
448
+ if (!names) return tools;
449
+ return tools.filter((tool) => bridgeTools.has(tool.name) || names.has(tool.name));
450
+ }
451
+
353
452
  async #configure(args) {
354
453
  if (!args || typeof args.url !== 'string' || args.url.trim().length < 8 || args.url.length > 2048
355
454
  || args.apiBasePath !== undefined
@@ -374,12 +473,13 @@ export class PlatformSession {
374
473
  next = undefined;
375
474
  }
376
475
  if (!next) {
377
- if (typeof reason === 'string' && reason.includes('Insecure HTTP')) {
378
- return error('INVALID_ARGUMENT', '数据中台地址是 HTTP,明文传输默认被拒绝:本机地址需设置 '
379
- + 'MBI_ALLOW_INSECURE_LOCALHOST=true,内网 IP 需设置 MBI_ALLOW_INSECURE_PRIVATE_NETWORK=true,'
380
- + '内网穿透等只有 http 域名的场景需设置 MBI_ALLOW_INSECURE_HTTP=true,或改用 HTTPS 门户地址。');
476
+ if (typeof reason === 'string' && reason.includes('MBI_PLATFORM_URL')) {
477
+ return error('INVALID_ARGUMENT', '数据中台地址无效:请提供 http(s) 门户地址,不能包含空格、问号、井号或反斜杠。');
478
+ }
479
+ if (typeof reason === 'string' && reason.includes('MBI_API_BASE_PATH')) {
480
+ return error('INVALID_ARGUMENT', '接口前缀无效:应形如 /prod-api,只能包含字母、数字、下划线和短横线。');
381
481
  }
382
- return error('INVALID_ARGUMENT', '数据中台地址无效;正式环境必须是 HTTPS 门户地址。');
482
+ return error('INVALID_ARGUMENT', '数据中台地址无效;正式环境建议使用 HTTPS 门户地址。');
383
483
  }
384
484
 
385
485
  if (this.#config && this.#client
package/src/index.js CHANGED
@@ -1,25 +1,26 @@
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.4' }, { 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(HTTPS);本机开发可启用 MBI_ALLOW_INSECURE_LOCALHOST;同时检查 MBI_API_BASE_PATH。');
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 } 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.6' }, { capabilities: { tools: {} } });
10
+ // 工具清单按服务端实际能力过滤,避免旧版服务端下模型调用注定失败的工具
11
+ server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: await session.advertisedTools() }));
12
+ server.setRequestHandler(CallToolRequestSchema, ({ params }) => session.call(params.name, params.arguments));
13
+ server.onerror = () => console.error('[mbi-senseX-mcp] MCP protocol error.');
14
+ server.onclose = () => session.close();
15
+ for (const signal of ['SIGINT', 'SIGTERM']) process.once(signal, () => {
16
+ session.close();
17
+ void server.close().finally(() => process.exit(0));
18
+ });
19
+ process.stdin.once('end', () => session.close());
20
+ await server.connect(new StdioServerTransport());
21
+ }
22
+
23
+ main().catch(() => {
24
+ console.error('[mbi-senseX-mcp] 启动失败。请检查 MBI_PLATFORM_URL(http 或 https 门户地址)、MBI_API_BASE_PATH,并确认地址里没有空格、问号或井号。');
25
+ process.exitCode = 1;
26
+ });
@@ -271,7 +271,7 @@
271
271
  },
272
272
  {
273
273
  "name": "call_agent_tool",
274
- "description": "Execute an Agent Profile capability or an actual connector tool returned by get_agent_tools. Every call rechecks the current platform roles, Profile ACL and Profile capability allowlist. Reuse executionId for multi-step dashboard, delivery and plan state.",
274
+ "description": "Execute an Agent Profile capability or an actual connector tool returned by get_agent_tools. Every call rechecks the current platform roles, Profile ACL and Profile capability allowlist. Reuse executionId for multi-step dashboard, delivery and plan state. For mashup_board, follow contract -> validate -> prepare -> preflight -> verify -> publish; publish consumes the artifact_id returned by prepare and never accepts a fresh spec.",
275
275
  "inputSchema": {
276
276
  "type": "object",
277
277
  "additionalProperties": false,