sx-platform-mcp 0.0.4 → 0.0.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.
Files changed (2) hide show
  1. package/dist/index.js +63 -10
  2. package/package.json +1 -1
package/dist/index.js CHANGED
@@ -20738,6 +20738,23 @@ function registerTools(server, ctx, tools, options = {}) {
20738
20738
  const SERVER_INSTRUCTIONS = [
20739
20739
  "━━━━ sx-platform 低代码平台 · 通用操作规则 ━━━━",
20740
20740
  "",
20741
+ "【做看板/数据分析先找全数据源】不要只查模型设计。",
20742
+ "",
20743
+ " 1. 先用 sx_model 找模型;",
20744
+ " 2. 再用 sx_sql { action:\"list\" } 查 SQL 设计,看有没有现成的 SQL 数据源;",
20745
+ " 3. 选 SQL 时用 sx_sql { action:\"get\" } 读 SQL_EXPR 和 SQL_OTHER;",
20746
+ " 4. SQL_OTHER 含 sqlFileList / orderList / fieldList 三个键;",
20747
+ " fieldList 是字段说明表,做报表/看板前先读,确认字段中文名和类型。",
20748
+ "",
20749
+ "【查询接口选择】默认分页,不要用 list 拉全量。",
20750
+ "",
20751
+ " · 模型数据:优先 sx_dynamic { action:\"page\", current:1, size:20 };",
20752
+ " 需要总数、翻页、大表查询,一律用 page。",
20753
+ " · SQL 数据:优先平台的 sqlPage(分页)接口;不要用 sqlList 拉全量。",
20754
+ " · sx_dynamic { action:\"list\" } 只适合确定很小的数据(字典/配置/少量候选);",
20755
+ " 它不分页、没有 total,maxRows 也不生效;没有过滤条件时平台会返回全部行。",
20756
+ " · 用户说“全部/所有”时,先确认数据量;大表要用 page 分页循环,不要一次 list。",
20757
+ "",
20741
20758
  "【工具选择顺序】先用已有工具,不够再查路由。",
20742
20759
  "",
20743
20760
  " 1. 先根据对话内容和当前上下文判断:常驻工具能不能直接满足?",
@@ -21362,7 +21379,7 @@ const queryConditionShape = {
21362
21379
  const dynamicQueryTools = [defineTool({
21363
21380
  name: "sx_dynamic",
21364
21381
  title: "数据查询(分页/列表/单条/搜索/取数/变更记录/公式)",
21365
- description: "低代码数据层的**唯一查询入口**。用 `action` 选择查什么:\n\n· **`page`**(最常用)—— 分页查询模型数据,带 total。`current` / `size` **必填且为正整数**。\n 适合「列出/统计满足条件的 X 记录」。「最近 N 条」用 `orderList` + 小 size,不要拉全量再截断。\n· **`list`** —— 同上但**不分页**,返回数组。数据量大时改用 page 或先收窄条件。\n· **`get`** —— 查单条(按 `sxKey` 或 `queryValue`)。**编辑前先调它**拿全部字段、当前值与 SX_KEY。\n `actionType:\"ADD\"` 返回**带新增默认值**的记录(当前登录人/时间/STATUS 都已填好),不需要定位;\n `EDIT` / `VIEW` / `COPY_ADD` / `CHANGE` 需要定位。\n· **`search`** —— 下拉/自动补全。给定模型与值列/标签列,把编码翻译成文本。\n `fieldDictTable` 传 SX_DICT / SX_DICT_BIZ 表示查平台字典。\n· **`datasource`** —— 统一取数接口,支持**分组汇总**与 **SQL 数据源**:\n `dataSourceType:\"model\"`(按模型名,单表)/ `\"sql\"`(按 SQL 编码,**多表关联用这个**);\n `queryMode:\"2\"`(列表)/ `\"1\"`(分组汇总,需 `groupSumFieldList`)。\n ⚠️ groupSum:`\"1\"`=分组字段、`\"3\"`=COUNT、其它=SUM。**不支持 AVG**(自己 SUM÷COUNT)。\n **不要自己写 `sqlField:\"COUNT(1)\"` 配 `groupSum:\"2\"`** —— 会生成 SUM(COUNT(1)) 报 ORA-00937。\n· **`change_log`** —— 单条记录的字段级审计轨迹(旧值/新值/操作人)。需 `sxKey`。\n· **`formula`** —— 服务端公式解析,用于落库前先验证公式写法。\n\n**字段范围**:传 `formCode` 只返回表单字段;传 `modelName` 返回模型全部字段;两者都传时**表单优先**。`allField:\"1\"` 优先于表单。\n不确定列名时:先 `allField:\"1\"` 查一条看真实物理列名。\n`subData:\"2\"` 连带返回子模型数据 —— **这是发现模型关系的正确方式**(子记录 PID = 主记录 ID)。\n\n⚠️ 写操作(保存/批量/删除/锁定等)全部在 `sx_dynamic_save`,本工具只读。",
21382
+ description: "低代码数据层的**唯一查询入口**。用 `action` 选择查什么:\n\n· **`page`**(最常用)—— 分页查询模型数据,带 total。`current` / `size` **必填且为正整数**。\n 适合「列出/统计满足条件的 X 记录」。「最近 N 条」用 `orderList` + 小 size,不要拉全量再截断。\n· **`list`** —— **仅限确定数据量很小的表**(字典/配置/少量候选);不分页、无 total、`maxRows` 不生效。\n 大表、行数不确定、没有过滤条件时**禁止用 list**,否则平台会全量扫描并可能超时;一律改用 page。\n· **`get`** —— 查单条(按 `sxKey` 或 `queryValue`)。**编辑前先调它**拿全部字段、当前值与 SX_KEY。\n `actionType:\"ADD\"` 返回**带新增默认值**的记录(当前登录人/时间/STATUS 都已填好),不需要定位;\n `EDIT` / `VIEW` / `COPY_ADD` / `CHANGE` 需要定位。\n· **`search`** —— 下拉/自动补全。给定模型与值列/标签列,把编码翻译成文本。\n `fieldDictTable` 传 SX_DICT / SX_DICT_BIZ 表示查平台字典。\n· **`datasource`** —— **通用查数入口**,支持列表、分组汇总、SQL 数据源:\n `dataSourceType:\"model\"`(按模型名)/ `\"sql\"`(按 SQL 编码,多表关联用这个);\n `queryMode:\"2\"`(列表)/ `\"1\"`(分组汇总,需 `groupSumFieldList`);\n `maxRows` **必填**,返回全部传 `-1`,限制行数传正整数。\n `dataAuth`:model 默认 `\"1\"`、sql 默认 `\"2\"`;管理员做看板可显式传 `\"99\"`(不控制权限)。\n `queryColumns` 只对 model 列表生效;`extQueryColumnList` 可加 CASE WHEN 等扩展列。\n `formData` 只对 SQL 模式生效;`sqlAllField:\"1\"` 只对 SQL 列表模式生效。\n ⚠️ groupSum:`\"1\"`=分组字段、`\"3\"`=COUNT、其它=SUM。**不支持 AVG**(自己 SUM÷COUNT)。\n **不要自己写 `sqlField:\"COUNT(1)\"` 配 `groupSum:\"2\"`** —— 会生成 SUM(COUNT(1)) 报 ORA-00937。\n· **`change_log`** —— 单条记录的字段级审计轨迹(旧值/新值/操作人)。需 `sxKey`。\n· **`formula`** —— 服务端公式解析,用于落库前先验证公式写法。\n\n**字段范围**:传 `formCode` 只返回表单字段;传 `modelName` 返回模型全部字段;两者都传时**表单优先**。`allField:\"1\"` 优先于表单。\n不确定列名时:先 `allField:\"1\"` 查一条看真实物理列名。\n`subData:\"2\"` 连带返回子模型数据 —— **这是发现模型关系的正确方式**(子记录 PID = 主记录 ID)。\n\n⚠️ 写操作(保存/批量/删除/锁定等)全部在 `sx_dynamic_save`,本工具只读。",
21366
21383
  group: "dynamic",
21367
21384
  inputSchema: {
21368
21385
  action: enumType(ACTIONS$10).describe("查什么:page / list / get / search / datasource / change_log / formula"),
@@ -21398,6 +21415,16 @@ const dynamicQueryTools = [defineTool({
21398
21415
  dicData: stringType().optional().describe("action=search:内联字典的 JSON 字符串,如 [{\"dictKey\":\"1\",\"dictValue\":\"启用\"}]"),
21399
21416
  dataSourceType: enumType(["model", "sql"]).optional().describe("action=datasource 必填:model=按模型名取数;sql=按 SQL 编码(多表关联用这个)"),
21400
21417
  queryMode: enumType(["1", "2"]).optional().describe("action=datasource 必填:1=分组汇总(需 groupSumFieldList);2=列表明细"),
21418
+ dataAuth: enumType([
21419
+ "1",
21420
+ "2",
21421
+ "99"
21422
+ ]).optional().describe("权限控制:model 默认 1、sql 默认 2;管理员做看板可传 99(不控权限)"),
21423
+ extQueryColumnList: arrayType(objectType({
21424
+ fieldName: stringType().describe("结果列名"),
21425
+ fieldRemark: stringType().optional().describe("中文名"),
21426
+ sqlField: stringType().optional().describe("CASE WHEN / 表达式;原样拼 SQL")
21427
+ })).optional().describe("action=datasource + queryMode=2:额外扩展列(如 CASE WHEN)"),
21401
21428
  sqlCode: stringType().optional().describe("action=datasource + dataSourceType=sql 必填:SQL 编码"),
21402
21429
  groupSumFieldList: arrayType(objectType({
21403
21430
  fieldName: stringType().describe("结果列名(分组字段用真实列名,统计列可自定义如 CNT)"),
@@ -21413,7 +21440,7 @@ const dynamicQueryTools = [defineTool({
21413
21440
  rowData: recordType(unknownType()).optional().describe("action=formula:行数据,公式中通过 $rowData 访问"),
21414
21441
  mainData: recordType(unknownType()).optional().describe("action=formula:主表数据,作为公式变量顶层作用域")
21415
21442
  },
21416
- handler: async (args, { client }) => {
21443
+ handler: async (args, { client, role }) => {
21417
21444
  const action = args.action;
21418
21445
  let target;
21419
21446
  if (NEEDS_TARGET$1.has(action)) {
@@ -21465,10 +21492,12 @@ const dynamicQueryTools = [defineTool({
21465
21492
  const rows = Array.isArray(res.data) ? res.data : [];
21466
21493
  const hint = emptyResultHint(rows.length === 0 ? 0 : void 0, args.modelName);
21467
21494
  const scope = fieldScopeNote(args);
21495
+ const hasFilter = args.queryValue !== void 0 || args.queryParam !== void 0 || args.queryList !== void 0 || args.compoundQuery !== void 0 || args.search !== void 0;
21468
21496
  return ok({
21469
21497
  returned: rows.length,
21470
21498
  ...scope ? { fieldScope: scope } : {},
21471
21499
  ...hint ? { hint } : {},
21500
+ ...hasFilter ? {} : { warning: "list 未带过滤条件,平台会返回全部匹配行;大表请改用 action:\"page\" 并带 current/size。" },
21472
21501
  data: res.data
21473
21502
  });
21474
21503
  }
@@ -21547,6 +21576,10 @@ const dynamicQueryTools = [defineTool({
21547
21576
  if (args.dataSourceType === "model" && !args.modelName) return fail("dataSourceType=model 时必须传 modelName。可用 sx_model {action:\"list\", scope:\"all\"} 查模型名。");
21548
21577
  if (args.dataSourceType === "sql" && !args.sqlCode) return fail("dataSourceType=sql 时必须传 sqlCode(来自 SX_SQL.SQL_CODE,可用 sx_dynamic 查 SX_SQL 获取)。");
21549
21578
  if (!args.queryMode) return fail("action=\"datasource\" 必须传 queryMode:1=分组汇总;2=列表明细。示例:queryMode:\"2\"。");
21579
+ if (args.maxRows === void 0) return fail("action=\"datasource\" 必须传 maxRows:返回全部传 -1,限制行数传正整数。");
21580
+ if (args.maxRows < -1) return fail("maxRows 只能是 -1(全部)或 >=0 的整数。");
21581
+ const actualRole = typeof role === "function" ? role() : role;
21582
+ if (args.dataAuth === "99" && actualRole !== "administrator") return fail("dataAuth=99(不控制权限)仅管理员可用。");
21550
21583
  if (args.queryMode === "1" && (!args.groupSumFieldList || args.groupSumFieldList.length === 0)) return fail("queryMode=1(分组汇总)必须传 groupSumFieldList。例如:[{fieldName:\"STATUS\",groupSum:\"1\"},{fieldName:\"CNT\",groupSum:\"3\",sqlField:\"ID\"}]");
21551
21584
  /**
21552
21585
  * ⚠️ **dataAuth 必须按数据源类型传,否则数据权限完全不生效。**
@@ -21567,7 +21600,7 @@ const dynamicQueryTools = [defineTool({
21567
21600
  *
21568
21601
  * 所以这里一律按类型带上,不做角色判断 —— 少一个分支,也少一处出错机会。
21569
21602
  */
21570
- const dataAuth = args.dataSourceType === "sql" ? "2" : "1";
21603
+ const dataAuth = args.dataAuth ?? (args.dataSourceType === "sql" ? "2" : "1");
21571
21604
  const body = {
21572
21605
  dataSourceType: args.dataSourceType,
21573
21606
  queryMode: args.queryMode,
@@ -21577,6 +21610,7 @@ const dynamicQueryTools = [defineTool({
21577
21610
  maxRows: args.maxRows,
21578
21611
  groupSumFieldList: args.groupSumFieldList,
21579
21612
  queryColumns: args.queryColumns,
21613
+ extQueryColumnList: args.extQueryColumnList,
21580
21614
  orderList: args.orderList,
21581
21615
  compoundQuery: args.compoundQuery,
21582
21616
  compoundExpr: args.compoundExpr,
@@ -24401,6 +24435,17 @@ const STANDALONE_PAGE_NOTICE = ["【权限说明】当前身份为普通用户
24401
24435
  */
24402
24436
  const SECTIONS$4 = {
24403
24437
  overview: [
24438
+ "━━ 数据源选择:模型设计 + SQL 设计都要看 ━━",
24439
+ "",
24440
+ "做看板/数据分析时,不要只从模型设计里找数据:",
24441
+ " 1. 先用 sx_model { action:\"list\", scope:\"all\" } 找模型;",
24442
+ " 2. 再用 sx_sql { action:\"list\" } 找现成 SQL 数据源;",
24443
+ " 3. 选 SQL 时用 sx_sql { action:\"get\" } 看 SQL_EXPR 与 SQL_OTHER;",
24444
+ " 4. SQL_OTHER.fieldList 是字段说明表,先读它确认字段中文名/类型;",
24445
+ " 5. 找不到现成 SQL 时,才考虑新建 SQL 或直接查模型。",
24446
+ "",
24447
+ "SQL 设计也是报表/看板/集成流/API 的正式数据源,不要漏掉。",
24448
+ "",
24404
24449
  "━━━━ 零、先读 iframe 平台规范(写 HTML 前的硬门槛)━━━━",
24405
24450
  "",
24406
24451
  "平台自带一份 iframe 动态 HTML 规范,位于:",
@@ -27856,7 +27901,7 @@ async function findSql(client, sqlCode) {
27856
27901
  const sqlTools = [{
27857
27902
  name: "sx_sql",
27858
27903
  title: "SQL 设计(查询 / 详情 / 保存 / 预览 / 删除)",
27859
- description: "SQL 设计的独立入口。SQL 存在 `SX_SQL`,作为**报表 / 集成流 / API 的数据源**。\n\n· **`list`** —— 列出本租户的 SQL 设计(编码 / 名称 / 归属应用 / 同步状态)。\n· **`get`** —— 取一条的完整配置(含 `SQL_EXPR` 语句与 `SQL_OTHER`)。\n· **`save`** —— 新建或更新(按 `sqlCode` 判断是否存在)。**更新时先读全量再合并**,不会把 `SQL_OTHER` 里的排序/附件配置抹掉。\n· **`preview`** —— 执行一次取数,用来验证语句是否可跑、字段名对不对。\n· **`delete`**(需 `confirm`)—— 逻辑删除。\n\n━━ 关键约束 ━━\n① **`sqlCode` 是唯一业务键**,租户内唯一。建议大写+下划线,如 `RPT_ORDER_LIST`。\n② 预览与查询**必须带 `formCode`**(平台要据此查表单配置)。按平台约定它等于 `sqlCode`,所以省略时工具自动用 `sqlCode` 兜底。\n③ 报表用 `sx_report_create` 生成时,**表单编码就是 sqlCode**,两者天然一致。\n④ 表名请写 `T${SYS.TENANT_ID}_模型名` 而不是写死租户,否则跨租户复制会失效。\n\n━━ SQL 里的可用变量 ━━\n`${SYS.TENANT_ID}` / `${SYS.USER_ID}` / `${SYS.USER_NAME}` / `${SYS.DEPT_ID}` 等,由平台在执行时注入。传 `params` 可额外注入自定义参数。",
27904
+ description: "SQL 设计的独立入口。SQL 存在 `SX_SQL`,作为**报表 / 看板 / 数据分析 / 集成流 / API 的数据源**。\n做数据分析或看板时,除了模型设计,也要先用 `list/get` 查 SQL 设计,确认有没有现成的 SQL 数据源。\n\n· **`list`** —— 列出本租户的 SQL 设计(编码 / 名称 / 归属应用 / 同步状态)。\n· **`get`** —— 取一条的完整配置(`SQL_EXPR` + `SQL_OTHER.sqlFileList/orderList/fieldList`)。\n· **`save`** —— 新建或更新(按 `sqlCode` 判断是否存在)。**更新时先读全量再合并**,不会把 `SQL_OTHER` 里的排序/附件/字段说明配置抹掉。\n· **`preview`** —— 执行一次取数,用来验证语句是否可跑、字段名对不对。\n· **`delete`**(需 `confirm`)—— 逻辑删除。\n\n━━ 关键约束 ━━\n① **`sqlCode` 是唯一业务键**,租户内唯一。建议大写+下划线,如 `RPT_ORDER_LIST`。\n② 预览与查询**必须带 `formCode`**(平台要据此查表单配置)。按平台约定它等于 `sqlCode`,所以省略时工具自动用 `sqlCode` 兜底。\n③ 报表用 `sx_report_create` 生成时,**表单编码就是 sqlCode**,两者天然一致。\n④ 表名请写 `T${SYS.TENANT_ID}_模型名` 而不是写死租户,否则跨租户复制会失效。\n\n━━ SQL 里的可用变量 ━━\n`${SYS.TENANT_ID}` / `${SYS.USER_ID}` / `${SYS.USER_NAME}` / `${SYS.DEPT_ID}` 等,由平台在执行时注入。传 `params` 可额外注入自定义参数。",
27860
27905
  group: "form",
27861
27906
  mutating: true,
27862
27907
  /** 只有 save / delete 改数据;list / get / preview 是纯读。 */
@@ -27876,6 +27921,7 @@ const sqlTools = [{
27876
27921
  order: stringType().describe("\"1\"=倒序,其它=正序")
27877
27922
  })).optional().describe("save:默认排序,写入 SQL_OTHER.orderList"),
27878
27923
  sqlFileList: arrayType(recordType(unknownType())).optional().describe("save:关联附件,写入 SQL_OTHER.sqlFileList。形如 [{fieldName:\"FILE1\", dataIdSource:\"ID\", modelField:\"MES_AFRU.AFRU_IMAGE\"}]"),
27924
+ fieldList: arrayType(recordType(unknownType())).optional().describe("save:字段说明表格,写入 SQL_OTHER.fieldList;常见 {fieldName, fieldRemark, fieldType, fieldLength},结构按平台字段说明表。"),
27879
27925
  extra: recordType(unknownType()).optional().describe("save:其它要一并写入 SX_SQL 的字段(UPPER 列名),原样带上"),
27880
27926
  keyword: stringType().optional().describe("list:按 SQL_CODE / SQL_NAME 模糊过滤"),
27881
27927
  current: numberType().int().positive().optional().describe("list:页码,默认 1"),
@@ -27951,15 +27997,16 @@ const sqlTools = [{
27951
27997
  const base = existing ? { ...existing } : {};
27952
27998
  delete base.SX_KEY;
27953
27999
  let other = base.SQL_OTHER;
27954
- if (args.orderList || args.sqlFileList) {
28000
+ {
27955
28001
  let parsed = {};
27956
28002
  if (typeof other === "string" && other.trim().startsWith("{")) try {
27957
28003
  parsed = JSON.parse(other);
27958
28004
  } catch {
27959
28005
  parsed = {};
27960
28006
  }
27961
- if (args.orderList) parsed.orderList = args.orderList;
27962
- if (args.sqlFileList) parsed.sqlFileList = args.sqlFileList;
28007
+ parsed.sqlFileList = args.sqlFileList ?? (Array.isArray(parsed.sqlFileList) ? parsed.sqlFileList : []);
28008
+ parsed.orderList = args.orderList ?? (Array.isArray(parsed.orderList) ? parsed.orderList : []);
28009
+ parsed.fieldList = args.fieldList ?? (Array.isArray(parsed.fieldList) ? parsed.fieldList : []);
27963
28010
  other = JSON.stringify(parsed);
27964
28011
  }
27965
28012
  const formValue = {
@@ -30048,16 +30095,22 @@ const SECTIONS$2 = {
30048
30095
  " SQL_DATABASE 数据源 ID,一般 null(用默认数据源)",
30049
30096
  " APP_ID 所属应用(可空)",
30050
30097
  "",
30051
- "SQL_OTHER 的结构(源码 SqlOtherConfig,只有两个键):",
30098
+ "SQL_OTHER 的结构(当前平台维护三个键):",
30052
30099
  "```json",
30053
30100
  "{",
30054
30101
  " \"sqlFileList\": [],",
30055
30102
  " \"orderList\": [",
30056
30103
  " { \"prop\": \"BARCODE\", \"order\": \"0\" }",
30057
- " ]",
30104
+ " ],",
30105
+ " \"fieldList\": []",
30058
30106
  "}",
30059
30107
  "```",
30060
- " 两个键即使为空也要保留 —— 平台的列配置界面依赖它们存在。",
30108
+ " 三个键即使为空也要保留 —— 平台的列配置/字段说明界面依赖它们存在。",
30109
+ "",
30110
+ "── 字段说明 fieldList ──",
30111
+ " `[{ fieldName, fieldRemark, fieldType, ... }]`",
30112
+ " 保存 SQL 时写入 SQL_OTHER.fieldList;做报表/看板/数据分析时先读它,",
30113
+ " 确认字段中文名和类型,不要只靠 SQL 结果列猜。",
30061
30114
  "",
30062
30115
  "── 默认排序 orderList(⚠️ 易错)──",
30063
30116
  " `[{ prop: \"字段名\", order: \"0\" | \"1\" }]`",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "sx-platform-mcp",
3
- "version": "0.0.4",
3
+ "version": "0.0.5",
4
4
  "description": "思绪云平台(Sixu Cloud)的 MCP 服务:stdio 形态,供 WorkBuddy 等 AI 客户端通过 npx 拉起",
5
5
  "type": "module",
6
6
  "bin": {