@wukongcrm/mcp-server 0.1.3 → 0.2.0

package/README.md

@@ -1,149 +1,207 @@
-# @wukongcrm/mcp-server
+# wukong-mcp
 
-WukongCRM MCP Server，用于给支持 Model Context Protocol 的本地 AI 客户端提供 CRM 查询和受控写入能力。
-
-默认代理 `https://www.72crm.com/api-11/` 下的固定白名单接口，不提供任意 URL 透传。
+本项目是供本地 AI 和 ChatGPT 网页端使用的 72CRM MCP Server，固定代理 `https://www.72crm.com/api-11/` 的白名单接口。
 
 ## 特点
 
-- 通过 `CRM_API_KEY` 登录，MCP 进程内部调用 `/login` 换取 `adminToken`。
-- 业务请求按 72CRM 要求发送 `Admin-Token` 请求头，token 只缓存在本地进程内存中。
+- 本地 stdio 模式由用户配置 `CRM_API_KEY`；远程 HTTP 模式通过当前 72CRM 登录用户静默生成专用 API Key。
+- 业务请求仍按 72CRM 要求发送 `Admin-Token` 请求头，该 token 只缓存在本地进程内存中。
+- 远程模式不会把 API Key 暴露给 ChatGPT 模型，也不会把 API Key 明文写入服务端数据文件。
 - API Key 登录使用独立端类型 `type=4`，避免占用 PC 端 `type=1` 登录态。
 - 不读取 OpenAPI，不调用 `/v3/api-docs`。
 - 不支持附件上传、删除、下载流代理。
 - 查询能力覆盖线索、客户、联系人、商机、产品、合同、回款、发票、跟进记录等模块。
-- 写入只开放线索、客户、联系人、商机、跟进记录，并且必须传 `confirm=true`。
-
-## 通用 MCP 配置
+- 人力资源 HRM 保留员工、部门、岗位、考勤、请假等查询，并开放 HRM 域内固定路径写入。
+- 独立财务 FM 保留凭证、账簿、报表、科目、币别、凭证字、仪表盘查询，并开放 FM 域内固定路径写入。
+- 进销存 JXC 保留产品、供应商、仓库、库存和出入库明细查询，并开放 JXC 域内固定路径写入。
+- 无代码能力覆盖应用、模块、字段、数据、角色、流程、阶段、跟进、打印、消息、开放配置和应用市场的 JSON 业务接口。
+- 所有写入仍必须传 `confirm=true`；未确认时只返回预览，不调用 72CRM 写接口。
 
-推荐直接通过 `npx` 启动，无需提前全局安装：
-
-```json
-{
-  "mcpServers": {
-    "wukongcrm": {
-      "type": "stdio",
-      "command": "npx",
-      "args": ["-y", "@wukongcrm/mcp-server"],
-      "env": {
-        "CRM_BASE_URL": "https://www.72crm.com/api-11/",
-        "CRM_API_KEY": "你的 72CRM API Key"
-      }
-    }
-  }
-}
-```
+## ChatGPT 网页端（远程 MCP）
 
-如果你的 MCP 客户端不支持 `type` 字段，可以去掉它：
+ChatGPT 网页端不能启动本地 `stdio` 进程，也不支持在 MCP 配置中直接填写自定义 API Key。远程模式提供 Streamable HTTP MCP 和 OAuth 2.0：用户第一次连接时跳转到 72CRM；绑定页通过当前浏览器 `localStorage` 中的 `Admin-Token` 静默生成一把独立 MCP API Key，再通过一次性绑定码由服务端交换。wukong-mcp 验证该 Key 后，签发包含加密 API Key 的短期访问令牌和可轮换刷新令牌。
 
-```json
-{
-  "mcpServers": {
-    "wukongcrm": {
-      "command": "npx",
-      "args": ["-y", "@wukongcrm/mcp-server"],
-      "env": {
-        "CRM_BASE_URL": "https://www.72crm.com/api-11/",
-        "CRM_API_KEY": "你的 72CRM API Key"
-      }
-    }
-  }
-}
-```
+绑定请求明确不携带 Cookie，`Admin-Token` 也不会传给 wukong-mcp。远程模式不要配置公共的 `CRM_API_KEY`，否则所有 ChatGPT 用户会共用同一个 CRM 账号。
 
-## pnpm 使用
+### 启动配置
 
-不要求必须使用 npm。支持通过 `pnpm dlx` 启动：
+复制示例配置并填写两个不同用途的随机密钥：
 
-```json
-{
-  "mcpServers": {
-    "wukongcrm": {
-      "type": "stdio",
-      "command": "pnpm",
-      "args": ["dlx", "@wukongcrm/mcp-server"],
-      "env": {
-        "CRM_BASE_URL": "https://www.72crm.com/api-11/",
-        "CRM_API_KEY": "你的 72CRM API Key"
-      }
-    }
-  }
-}
+```bash
+cp .env.example .env
+chmod +x start-http.sh
+./start-http.sh
 ```
 
-## 全局安装
+也可以传入其他配置文件：
 
 ```bash
-npm install -g @wukongcrm/mcp-server
+./start-http.sh /path/to/wukong-mcp.env
 ```
 
-安装后可以直接启动：
+脚本默认在每次启动前执行 `npm run build`，并通过 `exec node dist/http-entry.js` 保持前台运行。已经构建完成时，可以在配置文件中设置 `WUKONG_MCP_BUILD_ON_START=0`。
+
+生产环境关键变量如下：
 
 ```bash
-CRM_API_KEY="你的 72CRM API Key" \
-CRM_BASE_URL="https://www.72crm.com/api-11/" \
-wukongcrm-mcp
-```
+MCP_PUBLIC_URL=https://www.72crm.com/mcp
+MCP_OAUTH_SECRET=<单独生成的至少32字符随机密钥>
+MCP_DATA_DIR=/var/lib/wukong-mcp
 
-对应 MCP 配置：
+# 可选；配置后启用 Redis，不配置时继续使用 JSON 文件
+MCP_REDIS_URL=rediss://default:<password>@<redis-host>:6380/0
+MCP_REDIS_PREFIX=wukong-mcp:oauth
 
-```json
-{
-  "mcpServers": {
-    "wukongcrm": {
-      "type": "stdio",
-      "command": "wukongcrm-mcp",
-      "env": {
-        "CRM_BASE_URL": "https://www.72crm.com/api-11/",
-        "CRM_API_KEY": "你的 72CRM API Key"
-      }
-    }
-  }
-}
+CRM_BASE_URL=https://www.72crm.com/api-11/
+CRM_BINDING_AUTHORIZE_URL=https://www.72crm.com/mcp-binding.html
+CRM_BINDING_EXCHANGE_URL=https://www.72crm.com/api-11/adminMcpBinding/exchange
+CRM_BINDING_EXCHANGE_ALLOW_HTTP=false
+CRM_BINDING_CALLBACK_URL=https://www.72crm.com/mcp/oauth/72crm/callback
+CRM_BINDING_CLIENT_ID=wukong-mcp
+CRM_BINDING_CLIENT_SECRET=<与72CRM后端完全一致的至少32字符共享密钥>
+
+MCP_HOST=127.0.0.1
+MCP_PORT=3000
+MCP_ALLOWED_HOSTS=www.72crm.com
+MCP_TRUST_PROXY=1
 ```
 
-## API Key 配置
+- `MCP_OAUTH_SECRET` 用于 AES-256-GCM 加密 OAuth 令牌；更换后，已连接用户需要重新授权。
+- 未配置 `MCP_REDIS_URL` 时，`MCP_DATA_DIR/oauth-state.json` 保存动态客户端、授权临时状态和撤销记录。
+- 配置 `MCP_REDIS_URL` 后，上述 OAuth 状态改为保存到 Redis；支持 `redis://` 和启用 TLS 的 `rediss://`。
+- `MCP_REDIS_PREFIX` 默认为 `wukong-mcp:oauth`。同一套 MCP 实例必须使用相同的前缀和 `MCP_OAUTH_SECRET`。
+- 授权请求和授权码在写入 Redis 或 JSON 前均使用 AES-256-GCM 加密，不会保存明文 API Key；授权码通过 Redis `GETDEL` 原子消费，因此 Redis/Tair 需要兼容 Redis 6.2 或更高版本。
+- 如果已经配置 Redis 但启动时连接失败，服务会启动失败，不会自动退回 JSON，以避免多个实例产生不一致状态。
+- `CRM_BINDING_AUTHORIZE_URL` 必须指向 72CRM 前端中转页，不能直接填写后端授权接口。
+- `CRM_BINDING_EXCHANGE_URL` 由 MCP 服务端请求，优先使用 HTTPS；仅当它是可信 VPC 内网 HTTP 地址时，才同时设置 `CRM_BINDING_EXCHANGE_ALLOW_HTTP=true`。此开关不会放开授权页或回调地址的 HTTPS 校验。
+- `CRM_BINDING_CLIENT_SECRET` 必须与 72CRM `admin-web` 配置完全一致，只保存在服务端。
+- `CRM_BINDING_CALLBACK_URL` 默认根据 `MCP_PUBLIC_URL` 的路径生成，显式配置时必须与其同域。
+- `MCP_ALLOWED_HOSTS` 是逗号分隔的额外 Host 白名单；公开域名会由 `MCP_PUBLIC_URL` 自动加入。
+- `MCP_TRUST_PROXY=1` 表示 MCP 服务前面有一层可信 Nginx 反向代理，使 Express 能正确读取客户端 IP 并避免限流器把所有请求识别为 Nginx；直接暴露 MCP 端口时应设置为 `false`，也可以填写可信代理 IP/CIDR。
+- MCP 的初始 Bearer challenge 同时要求 `crm.read offline_access`，ChatGPT 完成授权后会获得刷新令牌；已经按旧范围授权的连接需要删除后重新连接。
+- 动态 OAuth 客户端只支持 `none + PKCE` 公共客户端模式，不签发客户端密钥，以兼容 ChatGPT 和 Claude 的远程 MCP 授权流程。
 
-`CRM_API_KEY` 是运行时环境变量，不应在 `npm install` 阶段传入。
+远程端点布局：
 
-README 中示例里的 `CRM_API_KEY` 对应 72CRM 个人中心生成的 MCP Token。获取地址：
+- MCP：`https://www.72crm.com/mcp`
+- 健康检查：`https://www.72crm.com/mcp/healthz`
+- OAuth：`/mcp/oauth/authorize`、`/mcp/oauth/token`、`/mcp/oauth/register`、`/mcp/oauth/revoke`
+- 72CRM 回调：`/mcp/oauth/72crm/callback`
+- 标准发现：`/.well-known/oauth-protected-resource/mcp`、`/.well-known/oauth-authorization-server`、`/.well-known/openid-configuration`
 
-```text
-https://www.72crm.com/cloud/#/person/index?selectedIndex=1
+### 72CRM 配置
+
+`admin-web` 需要配置：
+
+```bash
+WUKONG_MCP_BINDING_CLIENT_ID=wukong-mcp
+WUKONG_MCP_BINDING_CLIENT_SECRET=<与MCP服务一致的共享密钥>
+WUKONG_MCP_BINDING_CALLBACK_URL=https://www.72crm.com/mcp/oauth/72crm/callback
+WUKONG_MCP_BINDING_CODE_TTL_SECONDS=120
 ```
 
-MCP 客户端启动 server 时必须能把 `CRM_API_KEY` 注入到 `@wukongcrm/mcp-server` 进程环境中。常见方式是写在 MCP 客户端配置的 `env` 字段里，或由启动脚本/系统环境变量注入。
+`mcp-binding.html` 从 72CRM 前端的 `localStorage["Admin-Token"]` 读取当前登录 Token，以 `Admin-Token` 请求头调用后端，并明确禁止携带 Cookie。Token 只用于本次绑定，不会发给 wukong-mcp。交换接口使用时间戳和 HMAC-SHA256 签名，一次性绑定码只能消费一次。
+
+### 在 ChatGPT 中加载
+
+1. 在 ChatGPT 设置中启用开发者模式，并创建自定义 App/Connector。
+2. MCP Server URL 填写 `https://www.72crm.com/mcp`，认证方式选择 OAuth。
+3. 保存并连接后，浏览器会跳转到 `https://www.72crm.com/mcp-binding.html`；当前已登录时将静默完成绑定。
+4. 授权完成后扫描工具，检查各工具的只读、写入和破坏性标记。
 
 ## 开发运行
 
-```bash
-npm install
-CRM_API_KEY="你的 72CRM API Key" \
-CRM_BASE_URL="https://www.72crm.com/api-11/" \
+```powershell
+cd D:\Desktop\wukong-mcp
+npm ci
+$env:CRM_API_KEY="你的 72CRM API Key"
+$env:CRM_BASE_URL="https://www.72crm.com/api-11/"
 npm run build
 node dist/index.js
 ```
 
-## 发布
+## 打包分发
 
-发布前验证：
+发布到 npm 前，先完成依赖安装和测试：
 
-```bash
+```powershell
+cd D:\Desktop\wukong-mcp
+npm ci
 npm test
 npm run build
-npm pack --dry-run
+npm publish
 ```
 
-首次公开发布 scoped 包：
+包使用 `@wukongcrm/mcp-server` 作用域公开发布。使用者可以直接安装：
 
-```bash
-npm publish
+```powershell
+npm install -g @wukongcrm/mcp-server
+```
+
+如需离线分发，可以在本机生成 npm tarball：
+
+```powershell
+npm pack
+```
+
+生成文件示例：
+
+```text
+wukongcrm-mcp-server-0.2.0.tgz
+```
+
+这个包只包含运行所需的 `dist`、`README.md` 和 `package.json`，不会携带源码、测试文件或用户 API Key。
+
+使用者拿到 `.tgz` 后安装：
+
+```powershell
+npm install -g .\wukongcrm-mcp-server-0.2.0.tgz
+```
+
+安装后可以直接用命令启动：
+
+```powershell
+$env:CRM_API_KEY="使用者自己的 72CRM API Key"
+$env:CRM_BASE_URL="https://www.72crm.com/api-11/"
+wukong-mcp
 ```
 
-`package.json` 已配置 `publishConfig.access=public`，因此不需要额外追加 `--access public`。
+## 本地 AI 配置示例
+
+```json
+{
+  "mcpServers": {
+    "wukong-crm": {
+      "command": "wukong-mcp",
+      "env": {
+        "CRM_BASE_URL": "https://www.72crm.com/api-11/",
+        "CRM_API_KEY": "请在这里填写 72CRM API Key"
+      }
+    }
+  }
+}
+```
 
 ## 支持工具
 
+### 无代码工具
+
+无代码工具只调用源码中声明的固定接口，不提供任意 URL 透传。写工具保持既有 MCP 语义：未传 `confirm=true` 时返回将要调用的接口、请求体和查询参数；明确确认后才执行。
+
+- 应用与模块：`nocode_list_applications`、`nocode_get_application`、`nocode_list_modules`、`nocode_get_module`、`nocode_write_application`、`nocode_write_module`
+- 字段与数据：`nocode_get_module_schema`、`nocode_query_fields`、`nocode_search_records`、`nocode_get_record`、`nocode_query_records`、`nocode_calculate_formula`、`nocode_check_duplicate`、`nocode_write_field`、`nocode_write_record`
+- 权限与团队：`nocode_list_team_members`、`nocode_get_permissions`、`nocode_write_team`、`nocode_write_role`
+- 场景与页面：`nocode_list_scenes`、`nocode_list_tabs`、`nocode_get_module_file`、`nocode_write_scene`、`nocode_write_tab`
+- 流程与阶段：`nocode_list_flows`、`nocode_list_stages`、`nocode_list_custom_buttons`、`nocode_query_workflow`、`nocode_write_flow`、`nocode_write_stage`、`nocode_write_custom_button`、`nocode_write_workflow`
+- 跟进：`nocode_query_followups`、`nocode_write_followup`
+- 业务配置：`nocode_query_configuration`、`nocode_write_configuration`
+- 打印与消息：`nocode_query_printing`、`nocode_write_printing`、`nocode_query_messages`、`nocode_write_message`
+- 开放能力与应用市场：`nocode_query_integrations`、`nocode_write_integration`、`nocode_query_marketplace`、`nocode_write_marketplace`
+
+文件流仍有意不经 MCP 代理，因此应用导入/导出、Excel 导入/导出、跟进导出、打印 PDF/Word 下载不在工具中；打印内容生成和预览 JSON 接口仍可使用。内部测试接口 `/moduleMQ/send` 也不会暴露。
+
+### CRM、OA、HRM、财务、进销存与工单工具
+
 - `crm_auth_status`
 - `crm_list_modules`
 - `crm_list_customer_pools`
@@ -156,16 +214,137 @@ npm publish
 - `crm_get_record_timeline`
 - `crm_get_action_records`
 - `crm_list_files`
+- `crm_search_products`
+- `crm_search_sale_products`
+- `crm_get_product`
+- `crm_get_product_information`
+- `crm_get_product_schema`
+- `crm_list_product_files`
+- `crm_get_product_num`
+- `crm_get_simple_products`
 - `crm_list_users`
 - `crm_find_user_id`
 - `crm_list_departments`
 - `crm_find_dept_id`
+- `crm_list_address_book_contacts`
+- `crm_get_address_book_contact`
+- `crm_list_address_book_departments`
+- `crm_list_address_book_auth_departments`
+- `crm_list_address_book_dept_user_ids`
+- `crm_list_address_book_dept_users`
+- `crm_list_address_book_auth_users`
+- `crm_get_address_book_user_dept_role_info`
+- `crm_get_address_book_organization`
+- `crm_get_address_book_user_count`
+- `crm_toggle_address_book_attention`
+- `crm_list_hrm_employees`
+- `crm_get_hrm_employee`
+- `crm_list_hrm_employee_fields`
+- `crm_list_hrm_departments`
+- `crm_get_hrm_department`
+- `crm_list_hrm_department_employees`
+- `crm_get_hrm_employee_post`
+- `crm_list_hrm_attendance_month_records`
+- `crm_get_hrm_attendance_daily_detail`
+- `crm_list_hrm_leave_records`
+- `crm_list_hrm_leave_types`
+- `crm_write_hrm`
+- `crm_create_hrm_record`
+- `crm_update_hrm_record`
+- `crm_list_finance_modules`
+- `crm_search_finance_vouchers`
+- `crm_get_finance_voucher`
+- `crm_summarize_finance_vouchers`
+- `crm_query_finance_ledger`
+- `crm_query_finance_report`
+- `crm_list_finance_subjects`
+- `crm_list_finance_currencies`
+- `crm_list_finance_voucher_words`
+- `crm_query_finance_dashboard`
+- `crm_write_finance`
+- `crm_create_finance_voucher`
+- `crm_update_finance_voucher`
+- `crm_list_jxc_modules`
+- `crm_search_jxc_records`
+- `crm_get_jxc_record`
+- `crm_get_jxc_record_information`
+- `crm_get_jxc_module_schema`
+- `crm_list_jxc_files`
+- `crm_list_jxc_stock_products`
+- `crm_get_jxc_product_inventory`
+- `crm_list_jxc_stock_movements`
+- `crm_get_jxc_warehouse_product_stock`
+- `crm_get_jxc_warehouse_names`
+- `crm_write_jxc`
+- `crm_create_jxc_record`
+- `crm_update_jxc_record`
+- `crm_list_calendar_events`
+- `crm_get_calendar_event`
+- `crm_list_oa_examine_categories`
+- `crm_list_oa_examine_groups`
+- `crm_list_oa_examines`
+- `crm_get_oa_examine`
+- `crm_get_oa_examine_fields`
+- `crm_list_oa_examine_record_logs`
+- `crm_list_oa_examine_flow_records`
+- `crm_list_oa_announcements`
+- `crm_get_oa_announcement`
+- `crm_create_oa_announcement`
+- `crm_update_oa_announcement`
+- `crm_delete_oa_announcement`
+- `crm_mark_oa_announcement_read`
+- `crm_list_oa_logs`
+- `crm_get_oa_log`
+- `crm_get_oa_log_information`
+- `crm_list_oa_log_templates`
+- `crm_get_oa_log_fields`
+- `crm_get_oa_log_welcome`
+- `crm_get_oa_log_bulletin`
+- `crm_get_oa_log_complete_stats`
+- `crm_list_oa_log_complete_records`
+- `crm_list_oa_log_incomplete_records`
+- `crm_list_oa_tasks`
+- `crm_list_related_oa_tasks`
 - `crm_preview_write`
 - `crm_create_record`
 - `crm_update_customer`
 - `crm_update_record_fields`
+- `crm_create_product`
+- `crm_update_product`
+- `crm_update_product_fields`
+- `crm_update_product_status`
+- `crm_transfer_products_owner`
+- `crm_delete_products`
+- `crm_create_contract`
+- `crm_update_contract`
+- `crm_create_receivables`
+- `crm_update_receivables`
+- `crm_create_receivables_plan`
+- `crm_update_receivables_plan`
+- `crm_create_invoice`
+- `crm_update_invoice`
+- `crm_create_quotation`
+- `crm_update_quotation`
+- `crm_create_calendar_event`
+- `crm_update_calendar_event`
+- `crm_create_oa_examine`
+- `crm_save_oa_examine_draft`
+- `crm_audit_oa_examine`
+- `crm_batch_audit_oa_examine`
+- `crm_create_oa_log`
+- `crm_update_oa_log`
+- `crm_delete_oa_log`
+- `crm_toggle_oa_log_favour`
+- `crm_create_oa_task`
+- `crm_update_oa_task_fields`
 - `crm_add_followup`
 - `crm_update_followup`
+- `workorder_search_records`
+- `workorder_get_record`
+- `workorder_get_schema`
+- `workorder_preview_write`
+- `workorder_create_record`
+- `workorder_update_record`
 
 ### `crm_search_records` 语义搜索
 
@@ -182,6 +361,50 @@ npm publish
 
 客户模块会转换为“客户名称 / 手机 / 电话”三个高级筛选条件，使用 `type=3`（包含）和不同 `groupId` 做 OR 查询。也支持 `query`、`q`、`phone`、`mobile`、`name` 等字段。
 
+负责人和创建人可以直接传用户 ID。单个和多个 ID 分别使用 `ownerUserId` / `ownerUserIds`、`createUserId` / `createUserIds`：
+
+```json
+{
+  "module": "customer",
+  "ownerUserIds": [9, 10],
+  "createUserId": 11
+}
+```
+
+只有昵称时，可以使用 `ownerUserName` / `ownerUserNames`、`createUserName` / `createUserNames`。MCP 会先调用员工列表接口做模糊召回，再按昵称精确比对；唯一命中后才把用户 ID 写入 `formType=user` 的筛选值。查无此人会报错，重名时会列出候选用户 ID，必须改传明确 ID，避免筛错人：
+
+```json
+{
+  "module": "customer",
+  "ownerUserName": "张三"
+}
+```
+
+通用高级筛选也支持相同的昵称解析。以下调用最终发送给 72CRM 的 `values` 会是用户 ID，而不是昵称：
+
+```json
+{
+  "module": "customer",
+  "filters": [
+    {
+      "fieldName": "ownerUserId",
+      "formType": "user",
+      "type": 1,
+      "values": ["张三"]
+    }
+  ]
+}
+```
+
+如需单独核对用户 ID，可调用 `crm_find_user_id`：
+
+```json
+{
+  "name": "张三",
+  "mode": "realname"
+}
+```
+
 ### 客户更新
 
 推荐优先使用 `crm_update_customer` 修改客户字段。它支持直接传客户 ID，也支持通过手机号、客户名或关键字唯一匹配客户；正式写入前会读取客户字段结构，自动补齐 `fieldId`、`fieldType`、`type`、`formType`，避免下拉字段或自定义字段写错结构。
@@ -214,6 +437,655 @@ npm publish
 
 写入成功后默认会再次读取 `/crmCustomer/information/{id}` 做字段级校验；如只想写入不校验，可传 `verify=false`。
 
+### CRM 产品
+
+产品模块同时支持通用 CRM 读接口和专用产品工具。产品列表固定调用 `/crmProduct/queryPageList`，销售产品列表固定调用 `/crmProduct/querySaleProductPageList`：
+
+```json
+{
+  "page": 1,
+  "limit": 20,
+  "keyword": "云服务",
+  "categoryId": 5,
+  "status": 1
+}
+```
+
+详情、详情页字段、字段结构、附件元数据、数量和简要实体分别调用：
+
+- `/crmProduct/queryById/{productId}`
+- `/crmProduct/information/{productId}`
+- `/crmProduct/field` 或 `/crmProduct/field/{productId}`
+- `/crmProduct/queryFileList`
+- `/crmProduct/num`
+- `/crmProduct/querySimpleEntity`
+
+产品新增和编辑可以直接传 72CRM 保存 payload，也可以使用 `entity + field`：
+
+```json
+{
+  "entity": {
+    "name": "云服务"
+  },
+  "field": [],
+  "confirm": true
+}
+```
+
+`crm_create_product` 固定调用 `/crmProduct/add`，`crm_update_product` 固定调用 `/crmProduct/update`，编辑时必须提供 `productId` 或 `id`。字段更新使用 `crm_update_product_fields`，固定调用 `/crmProduct/updateInformation`，会先读取 `/crmProduct/field/{productId}` 自动补齐字段结构，并默认读取 `/crmProduct/information/{productId}` 做写后校验。
+
+上下架、负责人转移和删除分别调用 `/crmProduct/updateStatus`、`/crmProduct/changeOwnerUser`、`/crmProduct/deleteByIds`，这些写入都必须传 `confirm=true`。导入导出、multipart 上传和文件流下载仍不代理。
+
+### CRM 审批单据写入
+
+合同、回款、回款计划、发票、报价单不再走通用 `crm_create_record`，而是使用专用工具绑定真实固定接口：
+
+- 合同：`crm_create_contract` -> `/crmContract/add`，`crm_update_contract` -> `/crmContract/update`
+- 回款：`crm_create_receivables` -> `/crmReceivables/add`，`crm_update_receivables` -> `/crmReceivables/update`
+- 回款计划：`crm_create_receivables_plan` -> `/crmReceivablesPlan/add`，`crm_update_receivables_plan` -> `/crmReceivablesPlan/update`
+- 发票：`crm_create_invoice` -> `/crmInvoice/add`，`crm_update_invoice` -> `/crmInvoice/update`
+- 报价单：`crm_create_quotation` -> `/crmQuotation/add`，`crm_update_quotation` -> `/crmQuotation/update`
+
+这些工具支持两种传法。第一种是直接传 72CRM 原始保存 payload，适合前端或线上接口已经抓到完整结构的场景：
+
+```json
+{
+  "body": {
+    "entity": {
+      "contractNum": "HT-001"
+    },
+    "field": [],
+    "product": [],
+    "examineFlowData": {
+      "label": 6,
+      "dataMap": {},
+      "flowDataList": []
+    }
+  },
+  "confirm": true
+}
+```
+
+第二种是传 `fields/updates/fieldValues`，MCP 会先调用对应 `/field` 接口读取字段结构，再自动组装 `entity + field + product/contract + examineFlowData`：
+
+```json
+{
+  "fields": {
+    "合同编号": "HT-001",
+    "合同金额": 1000,
+    "产品": {
+      "product": [
+        {
+          "productId": 10,
+          "name": [{ "name": "云服务" }],
+          "salesPrice": "288.5",
+          "num": 2,
+          "discount": "90"
+        }
+      ],
+      "totalPrice": "577",
+      "discountRate": "90"
+    }
+  },
+  "examineFlowData": {
+    "label": 6,
+    "dataMap": {},
+    "flowDataList": []
+  },
+  "confirm": true
+}
+```
+
+合同、回款、发票、报价单通常受审批流配置影响。MCP 不会伪造审批流；如果没有传 `examineFlowData`，预览和写入结果会带 `approvalNotice` 提醒。若只想保存草稿，可传 `draft=true`，MCP 会补 `entity.checkStatus=5`。所有写入仍必须传 `confirm=true`。
+
+### 通讯录
+
+通讯录列表固定调用 `/adminUser/queryListName`，支持分页、搜索、部门、关注状态、首字母和首字母排序：
+
+```json
+{
+  "page": 1,
+  "limit": 20,
+  "keyword": "张三",
+  "deptId": 8,
+  "status": 1,
+  "acronym": "Z",
+  "initial": 1
+}
+```
+
+联系人详情固定调用 `/adminUser/queryUserInfo`：
+
+```json
+{
+  "userId": 1001
+}
+```
+
+组织和部门相关只读工具：
+
+- `crm_list_address_book_departments` -> `/adminDept/queryDeptTree`
+- `crm_list_address_book_auth_departments` -> `/adminDept/queryDeptByAuth`
+- `crm_list_address_book_dept_user_ids` -> `/adminUser/queryUserByDeptIds`
+- `crm_list_address_book_dept_users` -> `/adminUser/queryListByDeptIds`
+- `crm_list_address_book_auth_users` -> `/adminUser/queryAuthUserList`
+- `crm_get_address_book_user_dept_role_info` -> `/adminUser/queryUserDeptOrRoleInfo`
+- `crm_get_address_book_organization` -> `/adminUser/queryOrganizationInfo`
+- `crm_get_address_book_user_count` -> `/adminUser/queryUserNumInfo`
+
+按部门查询简要用户：
+
+```json
+{
+  "deptIds": [8, 9]
+}
+```
+
+按用户、部门、角色批量查询聚合信息：
+
+```json
+{
+  "userIds": [1001],
+  "deptIds": [8],
+  "roleIds": [2]
+}
+```
+
+关注状态切换固定调用 `/adminUser/attention`，`userId` 按 72CRM 后端要求走查询参数，必须传 `confirm=true` 才会写入：
+
+```json
+{
+  "userId": 1001,
+  "confirm": true
+}
+```
+
+### 办公审批
+
+审批类型固定调用 `/examines/queryPartList`，默认按 OA 审批传 `label=0`、`pageType=0`；审批分组固定调用 `/examineSuperExamines/queryExamineGroup`，默认 `groupType=0`。
+
+审批列表统一使用 `crm_list_oa_examines`，MCP 会按 `listType` 和 `tab` 映射到新版前端接口：
+
+```json
+{
+  "listType": "upcoming",
+  "tab": "todo",
+  "page": 1,
+  "limit": 15,
+  "search": "报销"
+}
+```
+
+常用映射包括：`upcoming/todo` -> `/examineSuperExamine/todo/me`，`upcoming/copy` -> `/examineSuperExamine/copy/me`，`track/me|do|copy`，`archive/me|audit|follow|tovoid|copy`，`draft`，`all`。也保留旧版 `legacyWaiting` -> `/examineWaiting/queryOaExamineList` 和 `legacyRecord` -> `/examineRecord/queryExamineRecordList`。
+
+审批详情固定调用 `/oaExamine/queryOaExamineInfo/{examineId}`。字段查询支持三种模式：传 `categoryId` 时默认调用 `/oaExamineField/queryField/{categoryId}` 获取新建审批自定义字段；传 `categoryId` 且 `mode=list` 时调用 `/oaExamineField/queryFieldList/{categoryId}`；传 `examineId` 或 `id` 时调用 `/oaExamine/getField` 获取详情字段。审批流转日志固定调用 `/examineRecord/queryExamineRecordLog`。
+
+新增审批、保存草稿、审批处理分别调用 `/oaExamine/setOaExamine`、`/oaExamine/setOaExamineDraft`、`/examineRecord/auditExamine`，批量审批调用 `/examineRecord/batchAuditExamine`。这些写操作都必须传 `confirm=true` 才会请求 72CRM；未传时只返回预览。
+
+新建审批支持两种传法。第一种是直接传 72CRM 原始 payload；第二种是传 `categoryId + fields/updates/fieldValues`，MCP 会先读取自定义字段结构，再自动组装为 `oaExamine + oaExamineRelation + field + oaExamineTravelList`：
+
+```json
+{
+  "categoryId": 7,
+  "batchId": "可选附件批次ID",
+  "fields": {
+    "审批内容": "客户拜访报销",
+    "金额": 128.5,
+    "申请人": [{ "userId": 9 }]
+  },
+  "customerIds": [1001],
+  "confirm": true
+}
+```
+
+系统字段会进入 `oaExamine`，自定义字段会进入 `field`；人员、部门、复选、分类、附件 batchId、明细表、出差/报销事项会按前端提交规则做转换。传 `strictRequired=true` 时会按字段元数据检查必填字段。
+
+### 日历日程
+
+日程列表固定调用 `/oaEvent/queryList`，详情固定调用 `/oaEvent/queryById`。列表查询的 `startTime`、`endTime` 按 72CRM 接口使用毫秒时间戳：
+
+```json
+{
+  "startTime": 1782470400000,
+  "endTime": 1782556799999,
+  "typeIds": [1, 2],
+  "userId": 9
+}
+```
+
+新增和修改日程分别调用 `/oaEvent/save`、`/oaEvent/update`，同样必须传 `confirm=true` 才会写入。可以直接传 72CRM 的 `SetEventBO` 结构：
+
+```json
+{
+  "event": {
+    "eventId": 12,
+    "title": "客户回访",
+    "typeId": 3,
+    "startTime": "2026-06-26 10:00:00",
+    "endTime": "2026-06-26 11:00:00",
+    "ownerUserIds": "9",
+    "repetitionType": 1,
+    "endType": 1
+  },
+  "relation": {
+    "customerIds": "1001"
+  },
+  "notice": [
+    {
+      "type": 1,
+      "value": 15
+    }
+  ],
+  "confirm": true
+}
+```
+
+也可以把 `title`、`typeId`、`startTime`、`endTime`、`ownerUserIds`、`customerIds`、`notices` 等字段放在顶层，MCP 会组装成 `SetEventBO`。删除日程、状态更新、单独增删关联仍不开放。
+
+### OA 公告
+
+公告列表和详情分别固定调用 `/oaAnnouncement/queryList`、`/oaAnnouncement/queryById/{announcementId}`：
+
+```json
+{
+  "page": 1,
+  "limit": 20,
+  "type": 1
+}
+```
+
+新增、编辑、删除和标记已读分别调用 `/oaAnnouncement/addAnnouncement`、`/oaAnnouncement/setAnnouncement`、`/oaAnnouncement/delete/{announcementId}`、`/oaAnnouncement/readAnnouncement`。写入类操作必须传 `confirm=true`；未确认时只返回目标地址和请求体预览。`deptIds`、`ownerUserIds`、`readUserIds` 支持传数组，MCP 会转成 72CRM 接口常用的逗号字符串。
+
+```json
+{
+  "title": "公告标题",
+  "content": "公告内容",
+  "ownerUserIds": [9, 10],
+  "confirm": true
+}
+```
+
+### OA 日志
+
+日志列表、详情、详情页字段、模板、模板字段、欢迎语、公告栏、完成统计、已完成/未完成记录分别固定调用：
+
+- `/oaLog/queryList`
+- `/oaLog/queryById`
+- `/oaLog/information/{logId}`
+- `/oaLogTemplate/queryPartList`
+- `/oaLogTemplateField/field` 或 `/oaLogTemplateField/field/{logId}`
+- `/oaLog/getLogWelcomeSpeech`
+- `/oaLog/queryLogBulletin`
+- `/oaLog/queryCompleteStats`
+- `/oaLog/queryCompleteOaLogList`
+- `/oaLog/queryIncompleteOaLogList`
+
+新增和编辑日志固定调用 `/oaLog/addOrUpdate`。可以直接传 `body` 原始 payload，也可以传 `categoryId + fields/updates/fieldValues`，MCP 会先读取日志模板字段并组装系统字段和自定义字段：
+
+```json
+{
+  "categoryId": 7,
+  "title": "日报",
+  "sendUserIds": [9],
+  "fields": {
+    "日志内容": "今天完成客户回访",
+    "明日工作": "继续跟进报价",
+    "工时": 8
+  },
+  "confirm": true
+}
+```
+
+删除日志和关注/取消关注分别调用 `/oaLog/deleteById`、`/oaLog/favourOrCancel`，都必须传 `confirm=true`。导出、打印和附件流下载仍不代理。
+
+### OA 任务
+
+OA 任务列表固定调用 `/oaTask/queryTaskList`，支持 72CRM 的 `OaTaskListBO` 常用筛选字段：
+
+```json
+{
+  "page": 1,
+  "limit": 20,
+  "type": 1,
+  "status": 1,
+  "priority": 3,
+  "keyword": "客户回访",
+  "mainUserIds": [9, 10]
+}
+```
+
+关联业务任务固定调用 `/oaTask/queryTypeTaskList`：
+
+```json
+{
+  "type": 2,
+  "typeId": 1001
+}
+```
+
+新增主任务固定调用 `/workTask/saveWorkTask`，必须传 `confirm=true` 才会写入。可以直接传 `task`，也可以使用顶层字段：
+
+```json
+{
+  "name": "客户回访",
+  "description": "确认续费计划",
+  "mainUserId": 9,
+  "ownerUserId": [9, 10],
+  "startTime": "2026-06-27",
+  "stopTime": "2026-06-28",
+  "priority": 3,
+  "labelId": [1, 2],
+  "customerIds": [1001],
+  "confirm": true
+}
+```
+
+更新主任务字段固定映射到 72CRM 的独立接口，必须传 `confirm=true` 才会写入：
+
+```json
+{
+  "taskId": 12,
+  "updates": {
+    "name": "客户回访-已更新",
+    "description": "带上报价单",
+    "mainUserId": 9,
+    "ownerUserId": [9, 10],
+    "startTime": "2026-06-27",
+    "stopTime": "2026-06-28",
+    "labelId": [1, 2],
+    "priority": 3,
+    "status": 5
+  },
+  "confirm": true
+}
+```
+
+其中标题、描述、负责人、参与人、时间、标签、优先级、状态会分别调用 `/workTask/setWorkTaskTitle`、`/workTask/setWorkTaskDescription`、`/workTask/setWorkTaskMainUser`、`/workTask/setWorkTaskOwnerUser`、`/workTask/setWorkTaskTime`、`/workTask/setWorkTaskLabel`、`/workTask/setWorkTaskPriority`、`/workTask/setWorkTaskStatus`。删除任务、导出、子任务删除、删除参与人、删除标签暂不开放。
+
+### 人力资源 HRM
+
+HRM 查询工具仍走固定只读接口；写入按“全部放开”开放到 HRM 域内固定路径。`crm_write_hrm` 只允许调用 `/hrm...` 开头的接口，支持直接传 `targetPath`，也支持传 `module + operation` 组合。未传 `confirm=true` 时只返回预览。
+
+员工列表固定调用 `/hrmEmployee/queryPageList`，`keyword`、`name`、`search` 会映射为 HRM 的 `employeeName`：
+
+```json
+{
+  "page": 1,
+  "limit": 15,
+  "keyword": "张三",
+  "deptId": 8,
+  "status": 11
+}
+```
+
+员工详情、字段表头、部门树、部门员工、岗位信息分别调用：
+
+- `/hrmEmployee/queryById/{employeeId}`
+- `/hrmEmployeeField/queryListHeads`
+- `/hrmDept/queryTreeList`
+- `/hrmDept/queryEmployeeByDeptId`
+- `/hrmEmployeePost/postInformation/{employeeId}`
+
+考勤月汇总固定调用 `/hrmAttendanceEmpMonthRecord/queryAttendanceEmpMonthRecordPageList`：
+
+```json
+{
+  "page": 1,
+  "limit": 20,
+  "search": "张三",
+  "deptIds": [8],
+  "times": ["2026-06-01", "2026-06-30"],
+  "isFullAttendance": 1
+}
+```
+
+每日打卡明细固定调用 `/hrmAttendanceClock/queryAttendanceDailyDetail`：
+
+```json
+{
+  "employeeId": 100,
+  "date": "2026-06-29"
+}
+```
+
+请假记录和请假类型分别调用 `/hrmEmployeeLeaveRecord/queryLeaveRecordPageList`、`/hrmEmployeeLeaveRecord/queryLeaveTypeList`：
+
+```json
+{
+  "employeeId": 100,
+  "times": ["2026-06-01", "2026-06-30"],
+  "leaveTypes": ["年假"]
+}
+```
+
+HRM 写入示例：
+
+```json
+{
+  "targetPath": "/hrmEmployee/addEmployee",
+  "body": {
+    "field": [
+      { "fieldName": "employeeName", "value": "张三" }
+    ]
+  },
+  "confirm": true
+}
+```
+
+也可以用组合形式调用任意 HRM 域内接口：
+
+```json
+{
+  "module": "hrmEmployeePost",
+  "operation": "updatePostInformation",
+  "body": {
+    "employeeId": 100,
+    "post": "研发工程师"
+  },
+  "confirm": true
+}
+```
+
+### 独立财务 FM
+
+FM 当前接入独立财务模块，不包含 JXC 财务单据。查询工具仍固定调用只读接口；写入可使用 `crm_write_finance` 调用 `/finance...` 开头的独立财务接口，凭证新增/编辑提供了便捷工具。
+
+凭证列表、详情和汇总分别固定调用 `/financeCertificate/queryPageList`、`/financeCertificate/queryById`、`/financeCertificate/summary`：
+
+```json
+{
+  "page": 1,
+  "limit": 20,
+  "accountId": 3,
+  "keyword": "付货款",
+  "certificateTime": ["2026-06-01", "2026-06-30"]
+}
+```
+
+账簿查询使用 `crm_query_finance_ledger`，`ledger` 支持：
+
+- `detail`: `/financeCertificate/queryDetailAccount`
+- `general`: `/financeCertificate/queryGeneralLedger`
+- `balance`: `/financeCertificate/queryDetailBalanceAccount`
+- `multiColumn`: `/financeCertificate/queryDiversification`
+- `itemsDetail`: `/financeCertificate/queryItemsDetailAccount`
+- `itemsBalance`: `/financeCertificate/queryItemsDetailBalanceAccount`
+- `amountDetail`: `/financeCertificate/queryAmountDetailAccount`
+- `amountGeneral`: `/financeCertificate/queryAmountDetailUpAccount`
+
+财务报表使用 `crm_query_finance_report`，`report` 支持：
+
+- `balanceSheet`: `/financeReport/balanceSheetReport`
+- `incomeStatement`: `/financeReport/incomeStatementReport`
+- `cashFlow`: `/financeReport/cashFlowStatementReport`
+
+传 `checkBalance=true` 时会调用对应报表的 `/balanceCheck` 接口。科目、币别、凭证字和仪表盘分别使用 `/financeSubject/list`、`/financeCurrency/queryAllList` 或 `/financeCurrency/queryListByAccountId`、`/financeVoucher/queryList`、`/financeDashboard/*` 的固定白名单查询。
+
+凭证新增和编辑：
+
+```json
+{
+  "body": {
+    "accountId": 3,
+    "certificateTime": "2026-06-30",
+    "certificateItems": []
+  },
+  "confirm": true
+}
+```
+
+`crm_create_finance_voucher` 固定调用 `/financeCertificate/add`，`crm_update_finance_voucher` 固定调用 `/financeCertificate/update`，编辑时必须提供 `certificateId` 或 `id`：
+
+```json
+{
+  "certificateId": 77,
+  "body": {
+    "accountId": 3,
+    "remark": "updated"
+  },
+  "confirm": true
+}
+```
+
+其他 FM 写接口使用域级写入工具：
+
+```json
+{
+  "targetPath": "/financeDigest/add",
+  "body": {
+    "accountId": 3,
+    "digestContent": "付货款"
+  },
+  "confirm": true
+}
+```
+
+### 进销存 JXC
+
+JXC 查询保留产品、供应商、仓库、库存和出入库明细的固定接口。写入按“全部放开”开放到 JXC 域内固定路径：产品、供应商、仓库提供便捷新增/编辑工具，其他 JXC 单据、资金、库存、设置类写接口可使用 `crm_write_jxc`。
+
+主数据模块可以先用 `crm_list_jxc_modules` 查看固定白名单，再用统一查询工具访问：
+
+```json
+{
+  "module": "product",
+  "page": 1,
+  "limit": 20,
+  "keyword": "电机",
+  "warehouseId": 8
+}
+```
+
+`crm_search_jxc_records` 会按模块固定调用 `/jxcProduct/queryPageList`、`/jxcSupplier/queryPageList` 或 `/jxcWarehouse/queryPageList`。详情、详情页字段、字段结构、附件元数据分别调用：
+
+- `/jxcProduct|jxcSupplier|jxcWarehouse/queryById/{id}`
+- `/jxcProduct|jxcSupplier|jxcWarehouse/information/{id}`
+- `/jxcProduct|jxcSupplier|jxcWarehouse/field`
+- `/jxcProduct|jxcSupplier|jxcWarehouse/queryFileList`
+
+库存列表固定调用 `/jxcWarehouseProduct/queryPageList`：
+
+```json
+{
+  "page": 1,
+  "limit": 20,
+  "keyword": "电机",
+  "productCode": "P-100",
+  "warehouseId": 8,
+  "stock": "1"
+}
+```
+
+产品库存、出入库明细、仓库产品库存数量和仓库名称分别调用：
+
+- `/jxcProduct/queryProductInventory/{productId}`
+- `/jxcDetailed/queryPageList`
+- `/jxcWarehouse/queryProductWarehouseNumBatch`
+- `/jxcWarehouse/queryWarehouseNameByIds`
+
+产品、供应商、仓库主数据新增/编辑：
+
+```json
+{
+  "module": "product",
+  "entity": {
+    "name": "电机"
+  },
+  "field": [],
+  "confirm": true
+}
+```
+
+```json
+{
+  "module": "supplier",
+  "id": 88,
+  "entity": {
+    "name": "新供应商"
+  },
+  "field": [],
+  "confirm": true
+}
+```
+
+其他 JXC 写接口示例：
+
+```json
+{
+  "module": "jxcPurchase",
+  "operation": "add",
+  "body": {
+    "entity": {
+      "orderNo": "PO-001"
+    },
+    "field": []
+  },
+  "confirm": true
+}
+```
+
+## 工单
+
+工单工具用于兼容 PHP 工单能力，同时保持标准 MCP 的固定接口和确认写入边界。
+
+- `workorder_search_records`：普通工单、工单池和线下工单分页查询。`scope=pool` 时固定调用 `/wkoWorkorder/queryPageList` 并传 `isPool=1`，`scope=offline` 时调用 `/wkoOfflineWorkorder/queryPageList`。
+- `workorder_get_record`：查询普通工单或线下工单详情，并同时读取详情字段 `/information/{id}`。
+- `workorder_get_schema`：查询普通工单或线下工单字段结构，可传 `id` 获取编辑字段。
+- `workorder_preview_write`：只生成新建或更新请求体，不调用写接口。
+- `workorder_create_record`：显式 `confirm=true` 后调用 `/wkoWorkorder/add` 或 `/wkoOfflineWorkorder/add`，写入后自动回读。
+- `workorder_update_record`：显式 `confirm=true` 后调用 `/wkoWorkorder/update` 或 `/wkoOfflineWorkorder/update`，写入后自动回读。
+
+普通工单新建示例：
+
+```json
+{
+  "entity": {
+    "name": "测试工单"
+  },
+  "field": [],
+  "confirm": true
+}
+```
+
+线下工单新建示例：
+
+```json
+{
+  "scope": "offline",
+  "body": {
+    "name": "线下维修工单"
+  },
+  "confirm": true
+}
+```
+
 ## 安全边界
 
-以下操作前期全部拒绝：删除、转移负责人、公海流转、导入导出、审批/状态流转、字段配置修改、附件上传。
+HRM、JXC、FM 和工单写入已按要求开放到域内固定路径，但仍保留这些硬边界：
+
+- 必须传 `confirm=true` 才会请求 72CRM；否则只返回预览。
+- `crm_write_hrm` 只能调用 `/hrm...`，`crm_write_jxc` 只能调用 `/jxc...`，`crm_write_finance` 只能调用 `/finance...`。
+- 工单工具只调用 `/wkoWorkorder...` 与 `/wkoOfflineWorkorder...` 固定路径，不开放任意工单路径透传。
+- 不允许 `targetPath` 使用完整 URL、跨域路径、`..`、查询串或片段。
+- 不代理文件流下载，不处理 multipart 文件上传；附件上传仍不支持。
+- 这些写入会真实修改 HRM/JXC/FM/工单业务数据，调用前请先用 `confirm=false` 看预览体。