kingdee-mcp-dev

# 金蝶 MCP 开发团 · 知识库 本 Skill 是 `kingdee-mcp-dev` 专家团的共享知识底座，供主理人（龚联达）与四位团员（范探源 / 寇豆码 / 严过关 / 温书成）在协作时查阅。目标是**把金蝶开放平台 ApiDoc 的全部接口集成进 `D:\AI\projects\kingdee-mcp`**。 ## 项目事实（已实证，勿凭记忆） - **源码位置**：`D:\AI\projects\kingdee-mcp`，Python + FastMCP。 - **工具规模**：`src/kingdee_mcp/server.py` 当前 **97 个 `@mcp.tool`**（2026-08-07 实测 97；本日新增 6 个标准动作通用工具 `kingdee_cancel_bills` / `kingdee_void_bills` / `kingdee_close_bill` / `kingdee_unclose_bill` / `kingdee_forbid_bills` / `kingdee_enable_bills`，覆盖 14/15 标准动作；报表由 `kingdee_query_report` 覆盖；覆盖 13 大业务域 + 4 个 SQL Server 探查）。 - **构建后端**：`hatchling`（`python -m build`），`dist/` 产物 `kingdee_mcp-0.2.0-py3-none-any.whl` / `.tar.gz`。 - **运行环境**：金蝶 K3Cloud `http://<K3Cloud-Server>/k3cloud/`，账套 `<ACCT_ID>`（<公司名>）。 - **登录方式**：仅账号密码（`ValidateUser`），无第三方应用授权；配置 `KINGDEE_SERVER_URL` / `KINGDEE_ACCT_ID` / `KINGDEE_USERNAME` / `KINGDEE_PASSWORD`。 - **WebAPI 权限拒绝**返回 `[[{'Result':{报错}}]]`（r[0][0] 是 dict），正常数据返回 `[[值,...]]`（r[0][0] 是标量）—— 写查询脚本务必用此区分，否则会把错误当数据。 ## ApiDoc 结构（浏览器实测） `https://openapi.open.kingdee.com/ApiDoc` 是 Element UI(el-tree) SPA，需真实浏览器爬取。结构为 **16 业务领域 → 77 模块 → 操作（标准金蝶 WebAPI 动作集）**： - 16 业务领域：员工服务、财务会计、税务管理、成本管理、资产管理、管理会计、供应链、电商与分销、零售管理、生产制造、质量管理、星空云服务、基础管理、BOS、移动应用、PLM。 - 标准操作动作（每个单据模块通用）：保存 / 提交 / 审核 / 反审核 / 撤销 / 下推 / 作废 / 整单关闭 / 反关闭 / 批量保存 / 单据查询 / 查看 / 暂存 / 删除，外加部分领域专属动作（如费用类「申请单退款」）。 - 原始抓取树见 `references/api-inventory-raw.json`（领域→模块已全量；操作级仅在「员工服务」域完整抓取，其余域操作需逐模块切换抓取）。 ## 集成工作流（团队 SOP 映射） | 阶段 | 负责团员 | 关键动作 | 输入 → 输出 | |------|----------|----------|-------------| | 探字段 / WebAPI 映射 | 范探源 | `kingdee_get_fields` 探 FormId 与字段 Key；映射 ApiDoc 操作到 `Save/Submit/Audit/Push/ExecuteBillQuery` | 任务 → 字段/操作映射表 | | 实现 `@mcp.tool` | 寇豆码 | 复用提速工具，落地工具代码 | 映射表 → 工具签名 | | 测试回归 | 严过关 | `bin/kmcp test` + 用例；区分权限拒绝 vs 正常数据 | 工具签名 → 回归报告 | | 文档 / 发布 | 温书成 | 更新 `docs/`、`mcp_optimization_notes.md`、CHANGELOG；`bin/kmcp build` → `twine upload` → Pages | 变更 → 发布清单 | ## 提速工具（已落地 server.py，优先复用） - `kingdee_validate_bill`：保存前校验，返回 `auto_fixes / missing_required / entry_issues / suggestions`，**不真正保存**。 - `kingdee_get_bill_template`：取已验证 model 骨架，支持 `SAL_Quotation` / `SAL_SaleOrder` / `PUR_PurchaseOrder`。 - `kingdee_refresh_metadata`：强制刷新元数据。 - 元数据已落盘缓存到 `~/.workbuddy/kingdee_metadata_cache/`。 **推荐工作流**：`get_bill_template → 填数 → validate_bill → save_bill`。 ## 必读参考 - `references/webapi-login-cache.md` — 金蝶 WebAPI 登录机制、元数据缓存读取与刷新。 - `references/field-discovery-sop.md` — `kingdee_get_fields` 探字段的标准操作流程与返回解析。 - `references/ercustom-pitfalls.md` — 本环境二开单据坑（SAL_SaleOrder 二开、TRNV_Receipt/PaymentSlip、FCUSTID 全大写、FBaseUnitId 等）。 - `references/apidoc-coverage-template.md` — ApiDoc 覆盖进度跟踪表模板，配合 `bin/kmcp coverage` 使用。 - `references/avoid-duplication.md` — **防止重复开发红线**：通用/专用工具清单 + 决策树 + `bin/kmcp tools` 查重用法。开工前必读。 ## 助手命令（bin/kmcp） 团队配套 CLI `bin/kmcp`： - `bin/kmcp test` — 跑 `evals/` + `tests/` 回归（连真实金蝶环境）。 - `bin/kmcp build` — `python -m build` 构建 wheel / sdist。 - `bin/kmcp list-tools` — 统计 `@mcp.tool` 数量。 - `bin/kmcp coverage` — 对照 `references/api-inventory-raw.json` 输出 ApiDoc 覆盖进度。