ui-service-mcp

ui-service-mcp 是一个面向 E10 Form Service 的 MCP Server，将表单、字段和样例数据能力封装为标准 MCP Tool，供 ui-code-agent 或其他 MCP Client 调用。

核心能力

• 查询并展开 E10 应用列表，保留文件夹路径和应用摘要。
• 查询指定应用下的物理表单列表。
• 查询表单主表字段、明细字段和明细表信息，可补充选择类字段的选项值。
• 查询当前登录用户的姓名、头像、岗位、性别、部门和分部信息。
• get_fields 在保留原始字段元数据的基础上追加字段能力和查询类型能力。
• 创建物理表单，并回读验证物理表名。
• 批量创建表单字段，并回读验证字段是否保存成功。
• 通过 query_form_data 查询有界页面样例/快照数据，并按需补查总数。
• 按需查询流程列表数据，支持按优先级查询紧急/重要流程；流程总数通过独立 Tool 显式查询，不会随列表查询自动调用。
• 按文件夹名称搜索知识文件夹树，为文档列表查询定位文件夹。
• 按员工和时间范围查询日程列表及按天日程数量。
• 查询当前用户相关的最新会议列表，保留分页信息并脱敏会议记录。
• 查询门户通讯录人员列表，默认请求全部标准字段并使用返回的 displayData，支持按人员范围和指定字段分页返回。
• 查询公文门户列表及可用显示字段，默认直接查询列表；仅在返回结果缺少用户要求的字段时按需查询字段清单。
• 查询内部、外部或全部邮件的未读数量和角标文案。
• 查询邮件门户列表，支持邮箱目录、时间范围、邮件类型、已读状态、待办、标星和附件筛选。
• 查询当前用户可见的通知公告列表，保留安全公告字段和分页总数。
• 查询数据源统计数据，支持聚合函数和统计前/统计后过滤。
• 在真实请求前批量校验 list/stat/group/workflow 查询参数，支持离线字段清单校验。
• 写入一条表单样例数据，并返回 E10 生成的数据 ID。
• 支持 stdio 和 HTTP 两种 MCP 接入方式。
• 统一返回认证、校验、网络、资源不存在、冲突和内部错误等分类。

MCP Tools

| Tool | 主要参数 | 能力 | | --- | --- | --- | | list_apps | 可选 type、appType | 查询并展开应用摘要 | | list_forms | appId | 查询应用下的物理表单 | | get_fields | objId、可选 appId | 查询字段并返回能力/选项元数据 | | query_account_info | 无业务参数 | 查询当前登录用户的账号信息 | | query_form_data | objId、appId、queryFields、可选 includeCount | 查询分页样例/快照并按需补查总数 | | query_workflow_data | type、可选 newConditions、分页参数 | 按流程类型及原生条件查询流程列表；不自动查询总数 | | query_workflow_count | type、可选 newConditions、分页参数 | 仅用户明确需要总数时，按流程类型及原生条件查询流程总数 | | query_document_data | 可选分页、folderIds、queryCount | 按流程列表方式查询文档目录分页数据；未传 folderIds 时不筛选目录 | | query_knowledge_folder_tree | searchKey、可选文件夹维度和知识库类型 | 模糊搜索知识文件夹并返回命中节点路径树和 matches；查询指定文件夹文档前先调用 | | query_calendar_data | employeeIds、可选时间范围 | 查询员工日程列表及按天数量 | | query_meeting_data | 可选 current、pageSize | 查询当前用户相关的最新会议列表 | | query_contact_data | 可选分页、tabKey、columnIndex | 默认传全部标准字段，使用 displayData 查询通讯录列表；用户指定字段时只传指定字段 | | query_official_document_fields | 可选 fieldType、listType、dealType | 列表结果缺少用户要求字段时，检查该字段是否可展示 | | query_official_document_data | listType=1 必须传 dealType；可选分页、fieldIds | 直接查询公文流程或公文库列表；公文库自动使用 dealType=15；fieldIds 仅用于确认字段后的补充查询 | | query_mail_data | 可选 params、icon | 查询邮件未读数量和角标文案 | | query_mail_list_data | 可选分页、fileldColumn、邮箱目录和邮件筛选 | 查询邮件门户列表及分页信息；无需传 pageId | | query_placard_data | 可选 params JSON 字符串 | 查询通知公告列表及分页总数 | | query_stat_data | objId、appId、statFields | 查询聚合统计数据 | | query_chart_data | objId、appId、groupFields、statFields | 按分组维度和指标查询聚合数据，适用于图表、排行榜等组件展示 | | validate_query | queryType 及对应查询参数 | 不发起业务数据查询，批量返回全部查询问题 | | create_form | appId、name、可选 tableNameSuffix | 创建物理表单并验证 | | batch_create_fields | appId、objId、formId、fields | 批量创建字段并验证 | | save_sample_data | objId、formData | 写入一条样例数据 |

流程条件数据区域接入（服务层）

本项目只提供服务层 MCP Tool，不包含页面前端或页面区域配置。页面消费方可以分别调用列表和 count Tool，并将返回的流程数据或数量填充到“紧急待办”“重要流程”“重要待办”等数据区域。

调用方直接传递 E10 原生 newConditions，服务只负责将其同时用于列表和 count 请求，不解释或重建条件：

| 页面数据区域 | newConditions 中的条件 | 列表/count | | --- | --- | --- | | 紧急待办 | requestlevelShow eq 2 | 传同一份 newConditions | | 重要待办 | requestlevelShow eq 1 | 传同一份 newConditions | | 紧急且重要待办 | requestlevelShow aggregate 1,2 | 传同一份 newConditions |

列表和 count 应使用相同的 type 与 newConditions。count 请求仍按其 E10 契约使用数组包装。 不传 newConditions 时保持原有全部流程查询。页面前端接入、区域渲染和空态展示不在本服务范围内。

字段创建支持：Text、TextArea、Number、Money、Date、DateTime、Select、RadioBox、CheckBox 和 FileComponent。

认证与安全

默认从环境变量读取 E10 认证信息。每个 Tool 也可以通过 auth 参数传入认证信息，优先级为：

Tool 参数 auth > 服务环境变量

| 变量 | 说明 | | --- | --- | | E10_BASE_URL | E10 服务地址 | | E10_USER_ID | 用户 ID | | E10_TENANT_KEY | 租户 Key | | E10_ETEAMS_ID | E10 会话凭证 |

请求只访问 E10_BASE_URL 同源地址，并同时使用 Cookie 和 ETEAMSID 请求头认证。认证信息不会写入日志、错误响应或业务文件。

HTTP 模式还支持：

• env 模式：使用服务环境变量认证。
• gateway 模式：通过可信用户和租户请求头识别调用方，连接配置仍来自服务端环境变量。
• 请求体大小、并发数、超时、Origin 和优雅关闭控制。
• GET /healthz 健康检查和 GET /readyz 就绪检查。

详细认证、请求和错误契约见 CONTRACTS.md。

本地运行

要求 Node.js >=22.5。

npm install
npm run build

stdio 模式

适合由 MCP Client 启动短进程。stdout 只输出 MCP JSON-RPC 消息，日志输出到 stderr。

npm start

HTTP 模式

默认监听 127.0.0.1:3030，MCP 接口为 /mcp。

npm run start:http

常用配置：

MCP_HTTP_HOST=0.0.0.0 \
MCP_HTTP_PORT=3030 \
MCP_AUTH_MODE=env \
npm run start:http

Docker

stdio 服务：

docker build -t ui-service-mcp .
docker run --rm -i \
  -e E10_BASE_URL=https://your-e10.example.com \
  -e E10_USER_ID=your-user-id \
  -e E10_TENANT_KEY=your-tenant-key \
  -e E10_ETEAMS_ID=your-eteams-id \
  ui-service-mcp

HTTP 服务使用 Dockerfile.http 构建：

docker build -f Dockerfile.http -t ui-service-mcp-http .

开发与发布

npm run build
npm test

仓库新增 release 分支，定位为预上线与正式发版分支。develop 继续用于日常开发和集成； 待发布代码必须先进入 release。以后正式 npm 版本只能从 release 发布，不得直接从 develop、功能分支或本地未提交状态发布。

发版前必须确认当前分支为 release、工作区干净，并且 HEAD 与 origin/release 一致；版本说明、npm 包和 registry 验证记录必须来自同一个 commit。

开发者应先为每次迭代新增一个 docs/changes/unreleased/*.md 变更片段，再执行发布准备。当前发布策略为 patch-only：

npm run release:check
npm run release:prepare -- patch
# 提交 prepare 生成的版本和说明，并 push origin release 后再发布
npm run release:publish -- --confirm
npm run release:verify

正式发布源固定为 https://registry.npmjs.org，安装源为 https://registry.npmmirror.com。 发布后须同步镜像并核对官方/镜像 tarball 的完整性。不要使用跳过提交和远端核对的 prepare/publish 连续快捷命令。

发布工具会生成版本专属说明、同步 package.json 和 package-lock.json、执行构建/测试/打包检查，并在 registry 验证成功后更新 CHANGELOG.md 和归档变更片段。版本说明见 docs/releases。