@miaocedata/mbi-bi-mcp 0.2.5 → 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
@@ -80,6 +80,10 @@ MBI_PLATFORM_URL = "https://bi.example.com"
80
80
  2. `query_metrics` 每次只查询一个 App。要限定日期,例如传 `dateRange: { "dimensionId": "205", "from": "2026-10-01", "toExclusive": "2026-11-01" }`。起日包含,止日不包含,最多 366 天。用配置中 `dateRangeSupported` 的真实日历维度;有多个时明确指定,不能用字段名或表达式。
81
81
  3. 中台校验实际日期选择和指定版本的本体规则。不能安全应用筛选、版本无权访问或存在未支持的约束时,工具返回错误;不要移除用户要求的约束重试。旧服务端不支持这些新参数,本地连接器和中台各服务应按 [部署与验收](../mbi-agent-service/docs/50-external-bi-mcp-deployment.md) 配套升级。
82
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
+
83
87
  ## Profile 控制的能力
84
88
 
85
89
  1. 调用 `get_agent_profiles`。只返回当前平台账号通过 USE/MANAGE ACL、且未停用、未被显式 DENY 的业务 Profile;同时给出当前角色下真正可用的能力。内部 `supervisor` 与 `demo_delivery` 不对外暴露。
@@ -88,9 +92,11 @@ MBI_PLATFORM_URL = "https://bi.example.com"
88
92
 
89
93
  如果 `agent:write` 被收回、Profile ACL 被撤销、Profile 被停用、能力被移出白名单或工具管理关闭,下一次调用会拒绝。`get_agent_tools` 不返回未授权的写工具;`publish_mashup_extension` 不直接开放,大屏发布必须经过 `mashup_board` 的版本化验收闸门。
90
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
+
91
97
  ## 打包与上架
92
98
 
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、客户地址或任何凭证打进市场包。
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、客户地址或任何凭证打进市场包。
94
100
 
95
101
  > **提审前须知(本地定制)**:当前 `src/client.js` 将滑动 7 天令牌持久化到本机用户目录(`~/.mbi-bi/grant.json`),目的是避免宿主关闭或每轮对话重启进程后反复授权。令牌文件不在本包目录内,不会随 `npm pack` 进入市场包;但长期凭据落盘属于安全敏感行为,正式提审前须重新评估是否接受。若需恢复短时令牌设计,用同目录的 `src/client.js.bak` 覆盖 `src/client.js`,并把上面的有效期说明同步改回。
96
102
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@miaocedata/mbi-bi-mcp",
3
- "version": "0.2.5",
3
+ "version": "0.2.6",
4
4
  "description": "Read-only stdio MCP adapter for authorized data platform deployments",
5
5
  "type": "module",
6
6
  "license": "UNLICENSED",
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) {
@@ -348,6 +440,15 @@ export class PlatformSession {
348
440
  return this.#client.call(name, args);
349
441
  }
350
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
+
351
452
  async #configure(args) {
352
453
  if (!args || typeof args.url !== 'string' || args.url.trim().length < 8 || args.url.length > 2048
353
454
  || args.apiBasePath !== undefined
package/src/index.js CHANGED
@@ -2,12 +2,13 @@
2
2
  import { Server } from '@modelcontextprotocol/sdk/server/index.js';
3
3
  import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
4
4
  import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
5
- import { PlatformSession, tools } from './client.js';
5
+ import { PlatformSession } from './client.js';
6
6
 
7
7
  async function main() {
8
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 }));
9
+ const server = new Server({ name: 'mbi-senseX', version: '0.2.6' }, { capabilities: { tools: {} } });
10
+ // 工具清单按服务端实际能力过滤,避免旧版服务端下模型调用注定失败的工具
11
+ server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: await session.advertisedTools() }));
11
12
  server.setRequestHandler(CallToolRequestSchema, ({ params }) => session.call(params.name, params.arguments));
12
13
  server.onerror = () => console.error('[mbi-senseX-mcp] MCP protocol error.');
13
14
  server.onclose = () => session.close();
@@ -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,