gxcs-lowcode-mcp 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,10 @@
-# Temporary Holding Version
+# gxcs-lowcode-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Read-only MCP stdio server that exposes the GXCS low-code platform REST API as 8 whitelisted `GET` tools for WorkBuddy.
+
+- No third-party runtime dependencies (Node.js >= 18 built-ins only).
+- Every tool is read-only: no create, update, delete, or arbitrary URL calls.
+- Configuration is supplied through `API_BASE_URL` and `AUTH_TOKEN` environment variables. No credentials are bundled.
+- `AUTH_TOKEN` is sent as `Authorization: Bearer <token>` (the prefix is added automatically).
+
+This package is the distributable form of `server/index.mjs` used by the `gxcs-lowcode-query` WorkBuddy connector. It is not intended for direct CLI use.

package/package.json

@@ -1,6 +1,17 @@
 {
   "name": "gxcs-lowcode-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Read-only MCP stdio server for the GXCS low-code platform, used by the WorkBuddy connector gxcs-lowcode-query.",
+  "type": "module",
+  "bin": {
+    "gxcs-lowcode-mcp": "./server/index.mjs"
+  },
+  "files": [
+    "server/index.mjs",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "license": "UNLICENSED"
+}

package/server/index.mjs

@@ -0,0 +1,308 @@
+#!/usr/bin/env node
+// Local stdio MCP server for the GXCS low-code platform (read-only).
+// No third-party dependencies: Node >= 18 built-ins only.
+// Protocol: MCP JSON-RPC 2.0 over newline-delimited stdio.
+// IMPORTANT: stdout is reserved for protocol messages. All diagnostics go to stderr.
+
+import readline from 'node:readline';
+
+const SERVER_NAME = 'gxcs-lowcode-query';
+const SERVER_VERSION = '0.2.0';
+const MAX_RESPONSE_CHARS = 120000;
+
+const API_BASE_URL = String(process.env.API_BASE_URL || '').replace(/\/+$/, '');
+const AUTH_TOKEN = String(process.env.AUTH_TOKEN || '');
+
+function diag(message) {
+  // Never print AUTH_TOKEN or Authorization values.
+  process.stderr.write(`[${SERVER_NAME}] ${message}\n`);
+}
+
+// Whitelist: tool name -> HTTP method + path builder. Nothing else can be called.
+const TOOLS = [
+  {
+    name: 'list_applications',
+    description: '分页查询低代码平台的应用列表。可按名称、分组、主键过滤。只读。',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        pageNum: { type: 'integer', description: '页码，从 1 开始', minimum: 1 },
+        pageSize: { type: 'integer', description: '每页条数，建议 1-100', minimum: 1, maximum: 100 },
+        name: { type: 'string', description: '应用名称（模糊）' },
+        groupId: { type: 'integer', description: '应用分组 ID' },
+        id: { type: 'integer', description: '应用主键' },
+        delFlag: { type: 'integer', description: '删除标识：0 正常，1 已删除', enum: [0, 1] }
+      },
+      required: ['pageNum', 'pageSize']
+    },
+    build: (a) => ({ method: 'GET', path: '/ent/application/page', query: pick(a, ['pageNum', 'pageSize', 'name', 'groupId', 'id', 'delFlag']) })
+  },
+  {
+    name: 'get_application',
+    description: '按应用 ID 查询应用详情（名称、分组、可见范围、描述等）。只读。',
+    inputSchema: {
+      type: 'object',
+      properties: { id: { type: 'integer', description: '应用主键 ID' } },
+      required: ['id']
+    },
+    build: (a) => ({ method: 'GET', path: '/ent/application/detail', query: { id: requireInt(a.id, 'id') } })
+  },
+  {
+    name: 'list_application_groups',
+    description: '分页查询应用分组列表。只读。',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        pageNum: { type: 'integer', description: '页码，从 1 开始', minimum: 1 },
+        pageSize: { type: 'integer', description: '每页条数', minimum: 1, maximum: 100 }
+      },
+      required: ['pageNum', 'pageSize']
+    },
+    build: (a) => ({ method: 'GET', path: '/ent/application/group/page', query: pick(a, ['pageNum', 'pageSize']) })
+  },
+  {
+    name: 'query_form_data',
+    description: '按表单 ID 分页查询业务数据（表单记录）。type 决定视图类型。只读。',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        type: { type: 'integer', description: '类型：1 PC表格，2 移动端表格，3 消息通知，4 流程中心', enum: [1, 2, 3, 4] },
+        djid: { type: 'integer', description: '表单 ID' },
+        pageNum: { type: 'integer', description: '页码，从 1 开始', minimum: 1 },
+        pageSize: { type: 'integer', description: '每页条数', minimum: 1, maximum: 100 },
+        keyword: { type: 'string', description: '模糊检索词' },
+        paramStr: { type: 'string', description: '查询条件字符串（平台原生格式）' },
+        orderByField: { type: 'string', description: '排序字段，默认 id' },
+        isDesc: { type: 'integer', description: '1 正序，2 倒序', enum: [1, 2] }
+      },
+      required: ['type', 'pageNum', 'pageSize']
+    },
+    build: (a) => {
+      const type = requireInt(a.type, 'type');
+      if (![1, 2, 3, 4].includes(type)) throw new ToolError('type 必须是 1/2/3/4');
+      return {
+        method: 'GET',
+        path: `/ent/application/auth/form/data/page/${type}`,
+        query: pick(a, ['djid', 'pageNum', 'pageSize', 'keyword', 'paramStr', 'orderByField', 'isDesc'])
+      };
+    }
+  },
+  {
+    name: 'get_form_data_detail',
+    description: '按表单 ID 与记录主键查询单条业务数据的字段明细。只读。',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        djid: { type: 'integer', description: '表单 ID' },
+        id: { type: 'integer', description: '记录主键 ID' },
+        fields: { type: 'string', description: '需要返回的展示字段，逗号分隔' },
+        authParam: { type: 'string', description: '权限参数（平台原生）' }
+      },
+      required: ['id']
+    },
+    build: (a) => ({ method: 'GET', path: '/ent/application/auth/form/data/detail', query: pick(a, ['djid', 'id', 'fields', 'authParam']) })
+  },
+  {
+    name: 'list_form_display_fields',
+    description: '查询某表单在表格视图中的展示列（字段名、标题、类型）。常用于为 query_form_data 准备字段。只读。',
+    inputSchema: {
+      type: 'object',
+      properties: { djid: { type: 'integer', description: '表单 ID' } },
+      required: ['djid']
+    },
+    build: (a) => ({ method: 'GET', path: `/ent/application/auth/form/table/field/get/${requireInt(a.djid, 'djid')}`, query: {} })
+  },
+  {
+    name: 'list_process_categories',
+    description: '查询流程分类列表，可按分类名称过滤。只读。',
+    inputSchema: {
+      type: 'object',
+      properties: { categoryName: { type: 'string', description: '流程分类名称' } }
+    },
+    build: (a) => ({ method: 'GET', path: '/category/list', query: pick(a, ['categoryName']) })
+  },
+  {
+    name: 'list_business_rules',
+    description: '查询某表单配置的业务规则列表，可按状态、名称、编码过滤。只读。',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        djId: { type: 'integer', description: '表单 ID' },
+        name: { type: 'string', description: '业务规则名称' },
+        code: { type: 'string', description: '业务规则编码' },
+        status: { type: 'integer', description: '状态：0 启用，1 停用', enum: [0, 1] }
+      },
+      required: ['djId']
+    },
+    build: (a) => ({ method: 'GET', path: `/business/rule/list/${requireInt(a.djId, 'djId')}`, query: pick(a, ['name', 'code', 'status']) })
+  }
+];
+
+class ToolError extends Error {}
+
+function pick(obj, keys) {
+  const out = {};
+  for (const key of keys) {
+    const value = obj[key];
+    if (value === undefined || value === null || value === '') continue;
+    out[key] = value;
+  }
+  return out;
+}
+
+function requireInt(value, name) {
+  const n = Number(value);
+  if (!Number.isInteger(n) || n < 0) throw new ToolError(`${name} 必须是非负整数`);
+  return n;
+}
+
+async function callApi(spec) {
+  if (!API_BASE_URL) throw new ToolError('未配置 API_BASE_URL，请在连接器设置中填写 API 服务地址');
+  if (!AUTH_TOKEN) throw new ToolError('未配置 AUTH_TOKEN，请在连接器设置中填写访问凭证');
+
+  let base;
+  try {
+    base = new URL(API_BASE_URL);
+  } catch {
+    throw new ToolError('API_BASE_URL 不是合法 URL');
+  }
+  if (base.protocol !== 'http:' && base.protocol !== 'https:') {
+    throw new ToolError('API_BASE_URL 只支持 http/https');
+  }
+
+  const url = new URL(base.pathname.replace(/\/+$/, '') + spec.path, base.origin);
+  for (const [key, value] of Object.entries(spec.query || {})) {
+    if (Array.isArray(value)) {
+      for (const item of value) url.searchParams.append(key, String(item));
+    } else {
+      url.searchParams.set(key, String(value));
+    }
+  }
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), 25000);
+  let response;
+  try {
+    response = await fetch(url, {
+      method: spec.method,
+      headers: {
+        'Authorization': /^Bearer\s+/i.test(AUTH_TOKEN) ? AUTH_TOKEN : 'Bearer ' + AUTH_TOKEN,
+        'Accept': 'application/json'
+      },
+      signal: controller.signal
+    });
+  } catch (err) {
+    if (err?.name === 'AbortError') throw new ToolError('请求超时（25 秒），请检查 API 地址或网络可达性');
+    throw new ToolError(`请求失败：${err?.message || 'unknown error'}`);
+  } finally {
+    clearTimeout(timer);
+  }
+
+  const text = await response.text();
+  if (response.status === 401 || response.status === 403) {
+    throw new ToolError('凭证无效或已过期（HTTP 401/403），请在连接器设置中更新访问凭证后重试');
+  }
+  if (!response.ok) {
+    throw new ToolError(`服务端返回 HTTP ${response.status}`);
+  }
+
+  let payload;
+  try {
+    payload = JSON.parse(text);
+  } catch {
+    payload = text;
+  }
+  // Platform-level business errors are also surfaced to the model.
+  if (payload && typeof payload === 'object' && payload.success === false) {
+    throw new ToolError(`接口返回失败：code=${payload.code ?? '?'} msg=${payload.msg ?? '(无说明)'}`);
+  }
+  const serialized = typeof payload === 'string' ? payload : JSON.stringify(payload, null, 2);
+  return serialized.length > MAX_RESPONSE_CHARS
+    ? serialized.slice(0, MAX_RESPONSE_CHARS) + '\n...[响应已截断，请缩小 pageSize 或增加过滤条件]'
+    : serialized;
+}
+
+function toolDefinitions() {
+  return TOOLS.map(({ name, description, inputSchema }) => ({ name, description, inputSchema }));
+}
+
+function send(message) {
+  process.stdout.write(JSON.stringify(message) + '\n');
+}
+
+function ok(id, result) {
+  send({ jsonrpc: '2.0', id, result });
+}
+
+function fail(id, code, message) {
+  send({ jsonrpc: '2.0', id, error: { code, message } });
+}
+
+async function handle(message) {
+  if (!message || typeof message !== 'object') return;
+  const { id, method, params } = message;
+
+  switch (method) {
+    case 'initialize':
+      ok(id, {
+        protocolVersion: params?.protocolVersion || '2024-11-05',
+        capabilities: { tools: { listChanged: false } },
+        serverInfo: { name: SERVER_NAME, version: SERVER_VERSION }
+      });
+      return;
+    case 'notifications/initialized':
+    case 'notifications/cancelled':
+      return; // notification: no response
+    case 'ping':
+      ok(id, {});
+      return;
+    case 'tools/list':
+      ok(id, { tools: toolDefinitions() });
+      return;
+    case 'resources/list':
+      ok(id, { resources: [] });
+      return;
+    case 'prompts/list':
+      ok(id, { prompts: [] });
+      return;
+    case 'tools/call': {
+      const name = params?.name;
+      const tool = TOOLS.find((t) => t.name === name);
+      if (!tool) {
+        fail(id, -32602, `未知工具：${name}`);
+        return;
+      }
+      const args = params?.arguments && typeof params.arguments === 'object' ? params.arguments : {};
+      try {
+        const spec = tool.build(args);
+        const text = await callApi(spec);
+        ok(id, { content: [{ type: 'text', text }], isError: false });
+      } catch (err) {
+        const message = err instanceof ToolError ? err.message : `调用失败：${err?.message || 'unknown error'}`;
+        ok(id, { content: [{ type: 'text', text: message }], isError: true });
+      }
+      return;
+    }
+    default:
+      if (id !== undefined) fail(id, -32601, `不支持的方法：${method}`);
+  }
+}
+
+diag(`started (node ${process.version}, api_configured=${Boolean(API_BASE_URL)}, token_configured=${Boolean(AUTH_TOKEN)})`);
+
+const rl = readline.createInterface({ input: process.stdin, crlfDelay: Infinity });
+rl.on('line', (line) => {
+  if (!line.trim()) return;
+  let message;
+  try {
+    message = JSON.parse(line);
+  } catch {
+    diag('dropped a malformed JSON-RPC line');
+    return;
+  }
+  Promise.resolve(handle(message)).catch((err) => {
+    diag(`handler error: ${err?.message || 'unknown'}`);
+    if (message?.id !== undefined) fail(message.id, -32603, '内部错误');
+  });
+});
+rl.on('close', () => diag('stdin closed, exiting'));