# KingdeeMCP [Health: Active]

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/WaHaiLong/KingdeeMCP  
**GitHub Stars:** 122  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/kingdeemcp

## Description
金蝶云星空 MCP Server：让 Claude/Cursor 等 AI 助手用自然语言直接查询、操作 ERP（采购/销售/库存/财务等 97 个工具）

## Tools
Capabilities this server exposes over MCP:

- **kingdee_usage_report** — 查看 MCP 使用统计报告，包括工具调用频率、成功率、耗时分布等。

    此工具分析已记录的使用日志，帮助了解：
    - 哪些工具被高频使用
    - 哪些工具失败率较高
    - API 调用耗时分布
    - 使用时段分布

    Returns:
        str: 使用报告（支持 text/markdown/json 格式）
    
- **kingdee_usage_stats** — 获取当前会话的使用统计摘要。

    返回当前进程内聚合的统计数据：
    - 工具使用次数
    - 成功/失败次数
    - 累计耗时
    - 错误类型统计

    Returns:
        str: 统计数据的 JSON 格式
    
- **kingdee_discover_tables** — 搜索 SQL Server 中包含关键字的表名（仅查系统目录，不读业务数据）。

    适用场景：
    - 想知道"采购"相关的表有哪些
    - 快速定位业务表名，不记得确切名称时
    - 配合 kingdee_discover_columns 一起使用，先找表再看字段

    搜索范围：SQL Server 系统目录（information_schema.TABLES / sys.tables）

    Returns:
        str: 表名列表，含表名、类型、创建时间
    
- **kingdee_discover_columns** — 按关键字搜索 SQL Server 中的列名（仅查系统目录，不读业务数据）。

    适用场景：
    - 想找一个"供应商编码"字段在哪些表里
    - 接口映射时，确认某个字段在数据库里的实际名称
    - 快速验证 Kingdee API 字段和数据库字段的对应关系

    Returns:
        str: 列名搜索结果，含表名、列名、数据类型、是否可空
    
- **kingdee_describe_table** — 查看指定表的完整结构（列名、类型、可空、默认值）。

    适用场景：
    - 知道表名，想了解完整字段列表
    - 写 SQL 或做数据建模前，查看表结构
    - 确认 Kingdee API 返回的字段在数据库里的实际类型

    已知金蝶常用表名前缀：
    - t_PUR_：采购相关（t_PUR_PurchaseOrder 采购订单）
    - t_SAL_：销售相关（t_SAL_SaleOrder 销售订单）
    - t_STK_：库存相关（t_STK_InStock 入库单）
    - t_BD_：基础资料（t_BD_Material 物料、t_BD_Supplier 供应商）

    Returns:
        str: 表结构详情
    
- **kingdee_discover_metadata_candidates** — 发现金蝶数据库中与指定 form_id 或 form_id 前缀对应的表。

    这是面向金蝶/K3 场景的辅助工具：根据 form_id 推测对应的数据库表名。

    form_id → 表名对应规律：
    - PUR_PurchaseOrder  → t_PUR_PurchaseOrder（采购订单）
    - SAL_SaleOrder     → t_SAL_SaleOrder（销售订单）
    - STK_InStock       → t_STK_InStock（入库单）
    - BD_Material       → t_BD_Material（物料）
    - BD_Supplier       → t_BD_Supplier（供应商）
    - BD_Customer       → t_BD_Customer（客户）

    适用场景：
    - 想知道某个 form_id 对应数据库里哪张表
    - 想探索某类单据的所有关联表（如采购全流程：订单→收料→入库）
    - 理解金蝶 form_id 和数据库表名的映射关系

    Returns:
        str: form_id 与表名的候选映射列表
    
- **kingdee_upload_attachment** — 按 WebAPI V6.0 上传一块附件并绑定已存在的单据（表头或分录）。

    直接传 Base64，不读取服务器本地文件。单块最多 4 MiB。
    多块上传须按顺序调用，保持单据/分录/文件名一致，后续块传首次返回的 file_id，
    只有最后一块 is_last=true。上传完成不触发单据提交或审核。
    success=true 且 next_action=null 才表示全部上传完成；失败或结果未知时不要自动重传。
    
- **kingdee_download_attachment** — 按 WebAPI V6.0 下载一块附件，返回 Base64 file_part，不写服务器本地文件。

    file_id 使用上传返回的 FileId，不是附件内码 attachment_ids。
    首次 start_index=0；is_last=false 时用返回的 start_index 继续下载，直到 next_action=null。
    每块分别 Base64 解码后按顺序拼接字节，不要直接拼接 Base64 字符串。
    
- **kingdee_query_bills** — 查询金蝶云星空任意单据列表，支持过滤、排序和分页。

    适用 form_id 示例：PUR_PurchaseOrder（采购订单）、SAL_SaleOrder（销售订单）、
    STK_InStock（采购入库）、SAL_OUTSTOCK（销售出库）、STK_MisDelivery（其他出库）。

    也可查基础资料：BD_Currency（币别）、BD_AccountBook（账簿）、
    BD_VOUCHERGROUP（凭证字）、BD_RateType（汇率类型）等。这类表单的查询视图
    没有 FID 列，工具会自动去掉 FID 字段与 FID 排序，无需调用方特殊处理（#28）。

    Returns:
        str: JSON，含 form_id / count / has_more / data 字段；
             发生自动降级时额外带 notice 字段说明
    
- **kingdee_view_bill** — 根据单据内码 FID 获取单据完整详情（含所有分录字段）。

    mode=summary（默认）：关联字段只保留 Id / Number / Name，大幅缩减体积，
        适合参照旧单建新单。完整数据动辄 10 万字符，summary 通常在 1 万以内。
    mode=full：返回原始 JSON。

    Returns:
        str: JSON 格式的单据数据
    
- **kingdee_query_purchase_orders** — 查询采购订单（PUR_PurchaseOrder）列表。

    常用 filter_string：
    - 已审核: "FDocumentStatus='C'"
    - 指定供应商: "FSupplierId.FNumber='S001'"
    - 指定日期: "FDate>='2024-01-01' and FDate<='2024-12-31'"
    - 未关闭: "FCloseStatus='A'"
    - 业务正常: "FBusinessClose='A'"

    推荐 field_keys（默认已包含关键执行字段）：
    FID,FBillNo,FDate,FDocumentStatus,FSupplierId.FName,FPurchaseDeptId.FName,
    FTaxAmount,FAllAmount,FReceiveQty,FStockInQty

    注：FTotalAmount/FLinkQty/FBusinessClose 等字段在 demo 环境可能不存在，
    如需关联数量，请用 FReceiveQty + FStockInQty 代替，或用 kingdee_get_fields 确认可用字段

    关联数量业务规则：
    - 关联数量 = 累计收料数量 + 累计入库数量
    - 关联数量 >= 订单数量时，采购订单无法下推收料单/入库单
    - 勾选控制交货数量时，关联数量 >= 交货下限时无法下推

    Returns:
        str: JSON 格式的采购订单列表
    
- **kingdee_query_purchase_order_progress** — 查询采购订单行明细及执行进度（含累计收料/入库数量）。

    与 kingdee_query_purchase_orders 的区别：
    - 本工具查询【表体分录级】字段，返回每行物料的详细执行情况
    - 默认返回已审核单据，可通过 filter_string 过滤

    返回的关键字段（demo 账套实测）：
    - FBillNo: 单据编号
    - FMaterialId.FNumber / FMaterialId.FName: 物料编码/名称
    - FQty: 订单数量
    - FReceiveQty: 累计收料数量
    - FStockInQty: 累计入库数量
    - FPrice: 单价（不含税）
    - FTaxPrice: 含税单价
    - FAllAmount: 价税合计

    以下字段需启用供应链模块后才存在（demo 环境可能不存在）：
    - FLinkQty: 关联数量（=累计收料数量+累计入库数量）
    - FBusinessClose: 业务关闭状态（A=正常，B=业务关闭）
    - FFreezeStatus: 冻结状态（A=正常，B=冻结）
    - FTerminateStatus: 终止状态（A=正常，B=终止）
    - FDlyCntl_Low / FDlyCntl_High: 交货下限/上限

    业务关闭规则（需启用供应链）：
    - 累计入库数量 >= 交货下限时，该行自动【业务关闭】
    - 累计入库数量 < 交货下限时，自动【业务反关闭】

    Returns:
        str: JSON 格式的采购订单执行进度列表
    
- **kingdee_query_sale_orders** — 查询销售订单（SAL_SaleOrder）列表。

    常用 filter_string：
    - 已审核: "FDocumentStatus='C'"
    - 指定客户: "FCustId.FNumber='C001'"

    推荐 field_keys：
    FID,FBillNo,FDate,FDocumentStatus,FCustId.FName,FSalesOrgId.FName,FTotalAmount

    Returns:
        str: JSON 格式的销售订单列表
    
- **kingdee_query_sale_quotations** — 查询销售报价单（SAL_Quotation）列表。

    常用 filter_string：
    - 已审核: "FDocumentStatus='C'"
    - 指定客户: "FCUSTID.FNumber='C001'"
    - 未失效: "FExpiryDate>='2026-01-01'"

    推荐 field_keys（默认已包含关键字段）：
    FID,FBillNo,FDate,FDocumentStatus,FCUSTID.FName,FSalerId.FName,FExpiryDate

    注（本环境为二开定制，与标准字段不同）：
    - 销售员字段为 FSalerId（非标准 FSalesmanId），写 FSalesmanId 会 500
    - 主表无 FTotalAmount（金额在分录 FQUOTATIONFIN 内），如需金额请用
      kingdee_query_bills 指定分录字段，或用 kingdee_get_fields 确认可用字段

    Returns:
        str: JSON 格式的销售报价单列表
    
- **kingdee_query_stock_bills** — 查询出入库相关单据。

    form_id 常用取值：
    - STK_InStock:        采购入库单
    - SAL_OUTSTOCK:       销售出库单
    - STK_MisDelivery:    其他出库单
    - STK_Miscellaneous:  其他入库单
    - STK_TransferDirect: 直接调拨单

    Returns:
        str: JSON 格式的出入库单列表
    
- **kingdee_query_inventory** — 查询即时库存数量（STK_Inventory）。

    常用 filter_string：
    - 指定物料: "FMaterialId.FNumber='MAT001'"
    - 指定仓库: "FStockId.FNumber='WH01'"
    - 有库存:   "FBaseQty>0"（默认已设置）

    Returns:
        str: JSON 格式的库存列表，含物料编码、名称、仓库、数量、单位
    
- **kingdee_query_outsource_orders** — 查询委外加工订单（SUB_SubReqOrder）列表。

    委外加工订单记录外协生产任务，包含 CP 测试、封装、FT 成品测试等工序
    的委托加工情况，是 WIP 在制量、逾期分析、回货预测的核心数据来源。

    常用 filter_string：
    - 在制（未结案）：  "FDocumentStatus='C' and FStatus not in ('6','7')"（默认）
    - 指定供应商：     "FSupplierId.FName like '%华力%'"
    - 逾期未完工：     "FPlanFinishDate<GETDATE() and FStatus not in ('3','6','7')"
    - 30 天内到期：    "FPlanFinishDate>=GETDATE() and FPlanFinishDate<=DATEADD(day,30,GETDATE())"
    - 指定批次：       "FLot.FNumber='AP5E047'"
    - 指定产品型号：   "FMaterialId.FSpecification='APT32F004B'"
    - 已完工待入库：   "FStatus='3'"

    关键字段说明：
    - FQty：           委外订单总数量（颗）
    - FStockInQty：    已入库数量（已完工回厂的数量）
    - FNoStockInQty：  未入库在制量（FQty - FStockInQty，可为负表示超收）
    - FStatus：        执行状态（1=开工，3=完工，6=结案，7=结算）
    - FPlanFinishDate：计划完工日（逾期判断基准）
    - FPurOrderNo：    关联采购订单号（CP 委外专用，可反查晶圆来源采购单）
    - FLot.FNumber：   批次号（WIP 追溯用）
    - F_XTR_Qty：      晶圆辅单位片数（自定义扩展字段，如需可追加到 field_keys）

    💡 REMEMBER: 若报"字段不存在"，用 kingdee_get_fields('SUB_SubReqOrder') 确认该账套可用字段

    Returns:
        str: JSON，含 count / has_more / data 字段
    
- **kingdee_query_receipts** — 查询应收单（AR_Receivable）列表，支持按客户、日期、核销状态、打开状态过滤。

    应收单记录客户应收账款，包含应收金额、已核销金额、核销状态等信息，
    是营收、回款、应收余额、票据占比等财务指标的核心数据来源。

    常用 filter_string：
    - 已审核：        "FDocumentStatus='C'"（默认）
    - 指定客户：      "FCUSTOMERID.FNumber='C001'"
    - 指定月份：      "FDATE>='2026-01-01' and FDATE<='2026-01-31'"
    - 未核销：        "FWRITTENOFFSTATUS='A'"
    - 未关闭：        "FOPENSTATUS='A'"
    - 期初数据：      "FISINIT=true"（初始化单）或 "FISINIT=false"（业务单）

    关键字段说明：
    - FALLAMOUNTFOR：     应收总金额（原币含税），财务核心指标
    - FNOTAXAMOUNTFOR：   应收不含税金额（原币），用于综合毛利率计算
    - FRELATEHADPAYAMOUNT：已核销金额
    - FWRITTENOFFSTATUS： 核销状态（A=未核销，B=部分核销，C=完全核销）
    - FOPENSTATUS：       打开状态（A=未关闭，B=已关闭，C=部分关闭）
    - FENDDATE_H：        到期日
    - FISINIT：           是否为初始化单据（期初数据）

    ⚠️ 不同金蝶账套字段名可能不同（如 FCUSTOMERID 可能为 FCustId、FDate 可能为 FDATE），
    先调用 kingdee_get_fields('AR_Receivable') 确认该账套可用字段。

    Returns:
        str: JSON，含 count / has_more / data 字段
    
- **kingdee_query_materials** — 查询物料基础资料（BD_Material）。

    常用 filter_string：
    - 按编码前缀: "FNumber like 'HG%'"
    - 按名称模糊: "FName like '%钢板%'"
    - 已审核启用: "FDocumentStatus='C'"

    Returns:
        str: JSON 格式的物料列表，含编码、名称、规格、单位、物料分组
    
- **kingdee_query_partners** — 查询客户（BD_Customer）或供应商（BD_Supplier）基础资料。

    partner_type 取值：BD_Customer 或 BD_Supplier

    Returns:
        str: JSON 格式的客户/供应商列表，含编码、名称、简称、联系人、电话
    
- **kingdee_save_bill** — 新建或修改金蝶单据（采购订单、销售订单等）。

    - 新建：model 中不传 FID
    - 修改：model 中必须传 FID，并设置 is_delete_entry=false 防止分录被删
    - 自动纠错：如字段名拼写错误（如 FSalesOrgId→FSaleOrgId），会自动修正

    新建采购订单 model 示例：
    {
      "FDate": "2024-01-15",
      "FSupplierId": {"FNumber": "S001"},
      "FPurchaseDeptId": {"FNumber": "D001"},
      "FPOOrderEntry": [
        {"FMaterialId": {"FNumber": "MAT001"}, "FQty": 100, "FPrice": 10.5, "FUnitID": {"FNumber": "PCS"}}
      ]
    }

    Returns:
        str: JSON，含新建单据的 FID 和单据编号 FBillNo
    
- **kingdee_validate_bill** — 保存前校验单据模型（不真正保存），秒级反馈结构是否正确，避免反复试错。

    返回：
    - ok: 是否通过（无缺失必填、无结构问题）
    - is_new: 是否新建（model 无 FID）
    - auto_fixes: 将被自动更名的字段 [{"from","to","location"}]（如 FCustId→FCUSTID）
    - missing_required: 缺失的顶层必填字段
    - entry_issues: 分录中缺失的必填子字段 / 结构异常
    - suggestions: 修正建议清单

    典型用法：先用本工具校验 -> 按 suggestions 修正 -> 再调用 kingdee_save_bill，一次成功。
    
- **kingdee_get_bill_template** — 获取常用单据的「已验证 model 骨架」模板（销售报价单/销售订单/采购订单等）。

    返回该表单的正确字段名、必填项、分录必填字段组成的 model 示例，AI 只需替换占位符填业务数据，
    跳过字段摸索。占位符形如 <客户编码>。保存前建议再用 kingdee_validate_bill 校验。

    支持的 form_id：SAL_Quotation / SAL_SaleOrder / PUR_PurchaseOrder（其它表单返回提示）。
    
- **kingdee_refresh_metadata** — 强制重新从金蝶拉取指定表单的元数据（忽略内存/磁盘缓存），用于表单结构变更后刷新。

    返回是否成功及字段数量。刷新后 kingdee_validate_bill / kingdee_save_bill 将使用最新字段定义。
    
- **kingdee_submit_bills** — 提交单据（草稿 → 待审核）。

    返回结构化结果：success=true 时包含 next_action 字段，建议调用 kingdee_audit_bills 完成审核。

    Returns:
        str: JSON，含 success / next_action / bill_ids 字段
    
- **kingdee_audit_bills** — 审核单据（待审核 → 已审核）。

    返回结构化结果：success=true 时表示单据已生效，next_action=null。

    Returns:
        str: JSON，含 success / bill_ids 字段
    
- **kingdee_unaudit_bills** — 反审核单据（已审核 → 待审核）。反审核后可重新修改和提交。

    返回结构化结果：success=true 时表示单据已回到待审核状态。

    Returns:
        str: JSON，含 success / bill_ids 字段
    
- **kingdee_delete_bills** — 删除单据（仅草稿状态可删除，已提交/已审核的单据需先反审核）。

    返回结构化结果：success=true 时表示删除成功。

    Returns:
        str: JSON，含 success / bill_ids 字段
    
- **kingdee_cancel_bills** — 撤销单据或基础资料（草稿/审批中状态回退，action=CancelAssign）。

    - FormId 参数化通用工具（非某单专用，理由：撤销是标准动作应走通用工具防重复），
      适用于单据 + 基础资料（如 SAL_SaleOrder / PUR_Requisition / BD_Customer / BD_Material 等）。
    - action 依据：范探源 2026-08-07 三重证据查证（元数据 OperationNumber +
      OperationNumberConst.cs 反编译 + 官方论坛/第三方实测），撤销 = CancelAssign
      （旧文档误作 Cancel，勿引用）。
    - 端点：默认走**独立 CancelAssign 端点**（无需 opNumber，QA 严过关 2026-08-07 真机验证
      B→D 成功），data={"Ids":"1,2,3"} 或 {"Numbers":[...]}，比走 ExecuteOperation 更简单直接。
    - 传参：bill_ids（FID 列表，优先）或 bill_nos（单据编号列表），至少一个。
    - 二开单据自定义撤销动作时，可显式传 operation 覆盖默认 CancelAssign（此时走
      ExecuteOperation + 顶层 opNumber）。

    Returns:
        str: JSON，含 success / fid / ids / action / endpoint 字段（注意是 fid/ids 而非 id）
    
- **kingdee_void_bills** — 作废单据（opNumber=Cancel，非 Invalid！全库无 Invalid 常量）。

    - FormId 参数化通用工具（非某单专用，理由：作废是标准动作应走通用工具防重复），
      仅适用于单据（如 SAL_SaleOrder / PUR_PurchaseOrder / STK_InStock 等）。
    - action 依据：范探源 2026-08-07 三重证据查证——作废 = Cancel，
      旧文档误作 Invalid（OperationNumberConst.cs 反编译确认全库无 Invalid 常量），勿引用。
    - 端点/格式：ExecuteOperation，opNumber=Cancel 放**顶层**（与 formid 平级），
      data 只放业务参数 {"Ids":"..."} 或 {"Numbers":[...]}（QA 严过关真机实测格式）。
    - 传参：bill_ids（FID 列表，优先）或 bill_nos（单据编号列表），至少一个。
    - 二开单据自定义作废动作时，可显式传 operation 覆盖默认 Cancel。

    Returns:
        str: JSON，含 success / fid / ids / action / endpoint 字段（注意是 fid/ids 而非 id）
    
- **kingdee_close_bill** — 整单关闭单据（已审核单据业务关闭，opNumber 随表单而异）。

    - FormId 参数化通用工具（非某单专用，理由：整单关闭是标准动作应走通用工具防重复），
      适用于单据（销售订单、采购申请单、发货通知单等）。
    - action 依据：范探源 2026-08-07 三重证据查证 + QA 严过关真机实测——整单关闭
      opNumber 因表单而异（如 SAL_SaleOrder=YLBillClose、PUR_Requisition=BillClose、
      PUR_PurchaseOrder=BillClose、SAL_DELIVERYNOTICE=BillClose），无法静态固定，需真机确认。
    - 端点/格式：ExecuteOperation，opNumber 放顶层，data 只放业务参数。
    - 解析优先级：显式 operation 参数 > 该 form_id 元数据 Operations 按中文名
      「整单关闭/关闭单据」匹配 OperationNumber（复用元数据缓存 _query_metadata）；
      匹配不到返回明确中文错误（提示显式传 operation）。
    - 传参：bill_ids（FID 列表，优先）或 bill_nos（单据编号列表），至少一个。

    Returns:
        str: JSON，含 success / fid / ids / action / action_source / endpoint 字段
    
- **kingdee_unclose_bill** — 整单反关闭单据（已整单关闭的单据恢复业务，opNumber 随表单而异）。

    - FormId 参数化通用工具（非某单专用，理由：反关闭是标准动作应走通用工具防重复），
      适用于单据（销售订单、采购申请单、发货通知单等）。
    - action 依据：范探源 2026-08-07 三重证据查证 + QA 严过关真机实测——反关闭
      opNumber 因表单而异（如 SAL_SaleOrder=YLUnBillClose、PUR_Requisition=Unclose、
      PUR_PurchaseOrder=BillUnClose、SAL_DELIVERYNOTICE=UncloseBill），无法静态固定，需真机确认。
    - 端点/格式：ExecuteOperation，opNumber 放顶层，data 只放业务参数。
    - 解析优先级：显式 operation 参数 > 该 form_id 元数据 Operations 按中文名
      「整单反关闭/反关闭」匹配 OperationNumber（复用元数据缓存 _query_metadata）；
      匹配不到返回明确中文错误（提示显式传 operation）。
    - 传参：bill_ids（FID 列表，优先）或 bill_nos（单据编号列表），至少一个。

    Returns:
        str: JSON，含 success / fid / ids / action / action_source / endpoint 字段
    
- **kingdee_forbid_bills** — 禁用基础资料（opNumber=Forbid，非 UnForbid；Disable 已废弃慎用）。

    - FormId 参数化通用工具（非某单专用，理由：禁用是标准动作应走通用工具防重复），
      仅适用于基础资料（如 BD_Customer / BD_Supplier / BD_Material / BD_Stock 等）。
    - action 依据：范探源 2026-08-07 三重证据查证 + QA 严过关真机实测——禁用 = Forbid，
      Disable 已废弃慎用，勿用 UnForbid（无此常量）。
    - 端点/格式：ExecuteOperation，opNumber=Forbid 放**顶层**，data 只放业务参数。
    - 传参：bill_ids（FID 列表，优先）或 bill_nos（编号列表，基础资料用 FNumber），至少一个。
    - 二开基础资料自定义禁用动作时，可显式传 operation 覆盖默认 Forbid。

    Returns:
        str: JSON，含 success / fid / ids / action / endpoint 字段（注意是 fid/ids 而非 id）
    
- **kingdee_enable_bills** — 反禁用基础资料（opNumber=Enable）。

    - FormId 参数化通用工具（非某单专用，理由：反禁用是标准动作应走通用工具防重复），
      仅适用于基础资料（如 BD_Customer / BD_Supplier / BD_Material / BD_Stock 等）。
    - action 依据：范探源 2026-08-07 三重证据查证 + QA 严过关真机实测——反禁用 = Enable。
    - 端点/格式：ExecuteOperation，opNumber=Enable 放**顶层**，data 只放业务参数。
    - 传参：bill_ids（FID 列表，优先）或 bill_nos（编号列表，基础资料用 FNumber），至少一个。
    - 二开基础资料自定义反禁用动作时，可显式传 operation 覆盖默认 Enable。

    Returns:
        str: JSON，含 success / fid / ids / action / endpoint 字段（注意是 fid/ids 而非 id）
    
- **kingdee_push_bill** — 将源单据下推生成目标单据（如销售订单下推销售出库单、采购订单下推采购入库单）。

    常用下推场景：
    - 销售订单 → 销售出库单:  form_id=SAL_SaleOrder,    target_form_id=SAL_OUTSTOCK
    - 采购订单 → 采购入库单:  form_id=PUR_PurchaseOrder, target_form_id=STK_InStock
    - 采购订单 → 收料通知单:  form_id=PUR_PurchaseOrder, target_form_id=PUR_ReceiveBill
    - 销售订单 → 销售退货单:  form_id=SAL_SaleOrder,    target_form_id=SAL_RETURNSTOCK

    转换规则说明：
    - 默认（rule_id=空，enable_default_rule=false）：Kingdee 使用系统配置的默认转换规则
    - enable_default_rule=true：强制启用该单据的默认下推规则，忽略 rule_id
    - rule_id 显式指定：绕过默认规则，直接使用指定规则（下推失败时常用此方式）

    采购订单下推限制（关联数量规则）：
    - 采购订单【关联数量】>=【订单数量】时，无法下推收料单/入库单
      （关联数量 = 累计收料数量 + 累计入库数量）
    - 勾选【控制交货数量】时：
      - 关联数量 >= 交货下限时，无法下推
      - 关联数量 + 本次下推数量 > 交货上限时，目标单据无法保存
    - 单据状态必须为"已审核"，且未关闭、业务状态为"正常"

    响应包含：
    - Result.ResponseStatus：保存结果（IsSuccess 判断整体是否成功）
    - Result.ConvertResponseStatus：每行下推转换结果（可查看具体分录成功/失败）

    Returns:
        str: JSON，含 success / bill_nos / next_action 字段（成功时包含目标单据编号）
    
- **kingdee_create_and_audit** — 一次性走完 Save → Submit → Audit 三步，避免 AI 漏掉中间步骤。

    任意一步失败即停止（不自动重试），返回 halted_at 和 recovery_hint 告诉 AI
    从哪里手动接手。失败日志按整体 op="create_and_audit" 记录一次（不会三倍膨胀）。

    适用场景：明确要"一条龙"创建并使单据生效，没有中间审批/校验需求。
    需要中间步骤校验时，请改用手工链路 kingdee_save_bill → kingdee_submit_bills → kingdee_audit_bills。

    Returns:
        str: JSON。成功：success=true、halted_at=null、steps 三条均 success。
             失败：success=false、halted_at 指出卡点、recovery_hint 给出下一步建议。
    
- **kingdee_push_and_audit** — 一次性走完 Push → (可选 Submit + Audit) 全流程。

    Push 生成的目标单默认是草稿；本工具自动批量提交+审核所有生成的目标单 FID。
    任何一步失败即停止；失败日志按整体 op="push_and_audit" 记录一次。

    auto_submit_audit=False 时退化为纯 push（与 kingdee_push_bill 等价，但返回 steps 结构）。

    Returns:
        str: JSON。含 steps、target_bill_nos、target_fids、halted_at / recovery_hint。
    
- **kingdee_create_lx_billing** — 二开收款单(TRNV_Receipt)/付款单(TRNV_PaymentSlip) 一站式创建：push → save 补字段 → submit → audit。

    背景：金蝶 WebAPI push 接口对二开收/付款单 **不会携带业务字段**（金额、物料、SONo 等全为空/0），
    必须在 push 后用 save 把字段补上才能进入审核。本工具把这四步合并，专为账套初始化导在途收/付款数据设计。

    工作流：
    1. push: 源单(SAL_SaleOrder/PUR_PurchaseOrder) → 草稿目标单（保留 _LK 上下游关联）
    2. save: 把 amount / material / qty / so_no 等业务字段写入草稿（is_delete_entry=false 不破坏 _LK）
    3. submit + audit（auto_audit=True 时）

    任一步失败立即停止，返回 halted_at 和 recovery_hint 指引手工接手。

    Returns:
        str: JSON。含 steps、target_bill_no、target_fid、halted_at / recovery_hint。
    
- **kingdee_query_user** — 查询金蝶系统中的用户列表。

    常用 filter_string：
    - 指定用户名: "FUserID.FNumber='user001'"
    - 在岗状态: "FIsActive=1"
    - 指定部门: "FDepartment.FNumber='D001'"

    推荐 field_keys：
    FUserID,FName,FNumber,FDepartment.FName,FIsActive,FCreateDate

    Returns:
        str: JSON 格式的用户列表
    
- **kingdee_query_role** — 查询金蝶系统中的角色列表。

    常用 filter_string：
    - 指定角色名: "FRoleID.FNumber='admin'"
    - 启用状态: "FIsActive=1"

    推荐 field_keys：
    FRoleID,FName,FNumber,FIsActive,FCreateDate,FDescription

    Returns:
        str: JSON 格式的角色列表
    
- **kingdee_query_permission** — 查询金蝶系统中的权限列表。

    常用 filter_string：
    - 指定角色: "FRoleId.FNumber='ROLE001'"
    - 指定对象类型: "FObjectType='BD_Material'"

    推荐 field_keys：
    FPermissionId,FName,FNumber,FObjectType,FObjectName,FIsAllow

    Returns:
        str: JSON 格式的权限列表
    
- **kingdee_query_sequence** — 查询金蝶系统中的编码规则（SequenceRule）列表。

    常用 filter_string：
    - 指定单据类型: "FObjectType='PUR_PurchaseOrder'"
    - 指定编码规则: "FSequenceRuleId.FNumber='SEQ001'"

    推荐 field_keys：
    FSequenceRuleId,FName,FNumber,FObjectType,FDescription,FIsActive

    Returns:
        str: JSON 格式的编码规则列表
    
- **kingdee_query_number_rule** — 查询金蝶系统中的单据编号规则列表。

    常用 filter_string：
    - 指定单据类型: "FObjectType='SAL_SaleOrder'"
    - 指定规则名: "FNumberRuleId.FNumber='NR001'"

    推荐 field_keys：
    FNumberRuleId,FName,FNumber,FObjectType,FPrefix,FSequenceLength,FDateFormat

    Returns:
        str: JSON 格式的单据编号规则列表
    
- **kingdee_query_system_config** — 查询金蝶系统中的系统配置参数。

    常用 filter_string：
    - 指定配置项: "FConfigKey='MaxUploadSize'"
    - 指定分类: "FCategory='System'"

    推荐 field_keys：
    FConfigId,FConfigKey,FConfigValue,FDescription,FCategory,FIsActive

    Returns:
        str: JSON 格式的系统配置列表
    
- **kingdee_list_forms** — 搜索金蝶系统中可用的表单类型（form_id）。

    不知道 form_id 时，先调用此工具搜索。例如：
    - 输入"员工"返回 BD_Empinfo
    - 输入"采购"返回采购相关的表单列表
    - 留空返回所有常用表单

    Returns:
        str: JSON 格式的表单列表，含 form_id、名称、描述、推荐字段、数据库表名
    
- **kingdee_get_fields** — 获取指定表单的完整字段信息和业务规则。

    不知道查询哪些字段时，或需要了解表单的业务限制时，先调用此工具。
    本工具会调用金蝶 QueryBusinessInfo 接口拉取真实字段定义（带缓存）。

    返回内容：
    - name/desc/db_tables/business_rules: 来自本地表单目录
    - recommended_fields: 推荐查询字段（精简版，给 LLM 看的）
    - metadata.fields: 所有主表字段（含 caption/type/must）
    - metadata.entries: 所有分录子表及其字段
    - metadata.required_fields: 主表必填字段列表
    - save_template: 自动生成的最小可保存 model 骨架（仅含必填字段）

    字段格式说明：
    - FXxx 是普通字段
    - FXxx.FName 是关联字段取名称（例：FSupplierId.FName）
    - FXxx.FNumber 是关联字段取编码（例：FSupplierId.FNumber）

    Returns:
        str: JSON 格式的字段信息
    
- **kingdee_query_pending_approvals** — 查询待审批的单据列表。

    查询当前处于审批中状态（已提交、待审核）的单据。

    Returns:
        str: JSON 格式的待审批单据列表
    
- **kingdee_query_workflow_status** — 查询单据的审批流状态。

    返回单据当前的审批状态和单据详情。

    Returns:
        str: JSON 格式的审批状态信息
    
- **kingdee_workflow_approve** — 审批通过或驳回单据。

    - approve: 审核通过（待审核 → 已审核）
    - reject:  驳回（已审核 → 反审核回到待审核状态）
    - 返回结构化结果，包含 success / next_action 字段

    Returns:
        str: JSON，含 success / action / bill_id 字段
    
- **kingdee_query_expense_reimburse** — 查询费用报销单。

    专门用于查询费用报销单据，支持按状态、金额、日期筛选。

    Returns:
        str: JSON 格式的费用报销单列表
    
- **kingdee_query_loan_balance** — 查询历史借款余额（人人报销域）。

    对应金蝶 ApiDoc「人人报销 → 历史借款余额」模块，FormId: ER_HistoricalLoanBalance。
    用于查询员工/部门的借款余额快照，支持按状态、申请人、日期筛选。

    ⚠️ 环境注意：该单据在部分账套（如芯之蝶测试账套 <ACCT_ID>）未启用，
    kingdee_get_fields 会返回「未知表单」。本工具代码已就绪，待目标账套启用该模块后即可连真机使用；
    字段 Key 以金蝶标准元数据为准，若实测报「字段不存在」请先用 kingdee_get_fields 复核。

    推荐 field_keys：
    FID,FBillNo,FDate,FDocumentStatus,FApplicantId.FName,FEmployeeId.FName,FLoanAmount,FRepaidAmount,FUnRepayAmount
    
- **kingdee_query_sales_outstock** — 查询销售出库单（发货单）。

    对应金蝶 ApiDoc 销售管理域「销售出库」模块，FormId: SAL_OUTSTOCK。
    用于查询已发货/出库的明细，支持按客户、仓库组织、日期、单据状态筛选。

    ⚠️ 字段 Key 警示（真机实测，2026-08-07）：
    本环境客户字段的元数据 Key 是 **FCustomerID**（大写 ID 后缀），并非 SAL_SaleOrder
    常见的 FCustId，也不是 kingdee_list_forms 推荐的 FCustId。直接传 FCustId 会报
    「元数据中标识为FCustId的字段不存在」。字段 Key 一律以 kingdee_get_fields 元数据为准。

    常用 filter_string：
    - 已审核: "FDocumentStatus='C'"
    - 指定客户: "FCustomerID.FNumber='C001'"
    - 日期区间: "FDate>='2026-05-01' and FDate<='2026-05-31'"

    推荐 field_keys（已按本环境元数据校验可用）：
    FID,FBillNo,FDate,FDocumentStatus,FCustomerID.FName,FStockOrgId.FName
    
- **kingdee_query_delivery_notice** — 查询发货通知单。

    对应金蝶 ApiDoc 销售管理域「发货通知」模块，FormId: SAL_DELIVERYNOTICE。
    用于查询待发货/已发货通知单及其客户信息，支持按客户、日期、单据状态筛选。

    ⚠️ 字段 Key 警示（真机实测，范探源已验证）：
    本账套客户字段的元数据 Key 是 **FCustomerID**（大写 ID 后缀）。误用 FCustId 会报
    「元数据中标识为FCustId的字段不存在」——本环境的 FCustId 在元数据中不存在，切勿改回 FCustId。
    字段 Key 一律以 kingdee_get_fields 元数据为准。

    ⚠️ 动作范围说明：标准保存/提交/审核动作已由通用 kingdee_save_bill / kingdee_submit_bills /
    kingdee_audit_bills 等按 FormId 参数化覆盖，本工具仅做查询，不负责写操作。

    常用 filter_string：
    - 已审核: "FDocumentStatus='C'"
    - 指定客户: "FCustomerID.FNumber='C001'"
    - 日期区间: "FDate>='2026-05-01' and FDate<='2026-05-31'"

    推荐 field_keys（已按本环境元数据校验可用）：
    FID,FBillNo,FDate,FDocumentStatus,FCustomerID.FName
    
- **kingdee_query_stock_in** — 查询采购入库单。

    对应金蝶 ApiDoc 库存管理域「采购入库」模块，FormId: STK_InStock。
    用于查询已完成/在途的采购入库单及其供应商信息，支持按供应商、仓库、日期、单据状态筛选。

    ⚠️ 字段 Key 警示（真机实测，范探源已验证）：
    本单据业务伙伴是**供应商**，字段 Key 用 **FSupplierId**（注意与销售类单据的 FCustId /
    FCustomerID 不同，采购入库单的客户字段并不存在）。误用 FCustId 会报「字段不存在」。
    字段 Key 一律以 kingdee_get_fields 元数据为准。

    ⚠️ 动作范围说明：标准保存/提交/审核动作已由通用 kingdee_save_bill / kingdee_submit_bills /
    kingdee_audit_bills 等按 FormId 参数化覆盖，本工具仅做查询，不负责写操作。

    常用 filter_string：
    - 已审核: "FDocumentStatus='C'"
    - 指定供应商: "FSupplierId.FNumber='V001'"
    - 日期区间: "FDate>='2026-05-01' and FDate<='2026-05-31'"

    推荐 field_keys（已按本环境元数据校验可用）：
    FID,FBillNo,FDate,FDocumentStatus,FSupplierId.FName
    
- **kingdee_query_fixed_asset** — 查询固定资产卡片主数据（FA_FAGet / BD_MainData，formId: FA）。
    固定资产是企业长期使用的有形资产，如房屋、机器设备、运输工具等。
    支持按资产编号、名称、状态、使用部门等条件筛选。
    常用 filter_string：
    - 已审核: "FDocumentStatus='C'"
    - 指定资产编号: "FNumber='FA001'"
    - 指定使用部门: "FUseDeptId.FNumber='D001'"
    - 在用资产: "FStatus='USING'"
    推荐 field_keys：
    FID,FNumber,FName,FAssetSource,FSpecification,FUsedPeriod,FOriginalAmount,FDepreciateRate,FUseDeptId.FName,FDocumentStatus,FStatus
    
- **kingdee_query_asset_card** — 查询资产卡片（FA_FAGet 或子单据）。
    资产卡片是固定资产的详细记录，包含原值、累计折旧、净值、卡片状态等信息。
    常用 filter_string：
    - 指定资产编号: "FNumber='FA001'"
    - 指定保管人: "FCustodian.FNumber='EMP001'"
    - 已计提折旧: "FTotalDepreciate>0"
    推荐 field_keys：
    FID,FNumber,FName,FAssetSource,FOriginalAmount,FTotalDepreciate,FNetAmount,FDepreciateMonth,FUsefulLife,FSalvageValue,FCustodian.FName
    
- **kingdee_query_asset_depreciation** — 查询资产折旧记录（FA_DepreciationBill）。
    折旧记录是固定资产计提折旧的明细，反映每月折旧费用、累计折旧、净值变化。
    常用 filter_string：
    - 指定期间: "FYear=2024 and FPeriod=3"
    - 指定资产: "FAssetId.FNumber='FA001'"
    推荐 field_keys：
    FID,FYear,FPeriod,FAssetId.FNumber,FAssetId.FName,FDepreciateDeptId.FName,FDepreciateAmount,FOriginalAmount,FTotalDepreciate,FNetAmount
    
- **kingdee_save_asset** — 新增或修改固定资产（FA_FAGet）。
    固定资产新建后状态为"草稿"，需提交+审核后才生效。
    修改已审核资产需要反审核后才能操作。
    
- **kingdee_query_asset_transfer** — 查询资产调拨单（FA_Transfer）。
    资产调拨记录固定资产在部门或使用人之间的转移。
    常用 filter_string：
    - 已审核: "FDocumentStatus='C'"
    - 指定资产: "FAssetId.FNumber='FA001'"
    - 原使用部门: "FOldDeptId.FNumber='D001'"
    推荐 field_keys：
    FID,FBillNo,FTransferDate,FDocumentStatus,FAssetId.FNumber,FAssetId.FName,FOldDeptId.FName,FNewDeptId.FName,FTransferReason
    
- **kingdee_query_asset_scrape** — 查询资产报废单（FA_Scrape）。
    资产报废记录固定资产的处置，包括正常报废、提前报废、毁损等。
    常用 filter_string：
    - 已审核: "FDocumentStatus='C'"
    - 指定资产: "FAssetId.FNumber='FA001'"
    - 报废类型: "FScrapeType='NORMAL'"
    推荐 field_keys：
    FID,FBillNo,FScrapeDate,FDocumentStatus,FAssetId.FNumber,FAssetId.FName,FOriginalAmount,FTotalDepreciate,FNetAmount,FScrapeType,FHandleMethod
    
- **kingdee_query_purchase_requisitions** — 查询采购申请单（PUR_Requisition）列表。

    采购申请单是采购流程的起点，用于向采购部门提出物料或服务采购需求。
    申请单可下推生成采购订单、采购询价单等。

    常用 filter_string：
    - 已审核: "FDocumentStatus='C'"
    - 指定申请人: "FApplicantId.FNumber='EMP001'"
    - 指定申请部门: "FRequestDeptId.FNumber='D001'"

    推荐 field_keys：
    FID,FBillNo,FDate,FDocumentStatus,FApplicantId.FName,FRequestDeptId.FName,FTotalAmount

    Returns:
        str: JSON 格式的采购申请单列表
    
- **kingdee_query_quality_inspections** — 查洵来料检验单（QIS_InspectBill/IQC）列表。

    来料检验单用于对采购物料进行质量检验，判断是否允许入库。

    常用 filter_string：
    - 已检验: "FDocumentStatus='C'"
    - 检验结果-合格: "FResult='1'" 或 "FPassQty>0"
    - 检验结果-不合格: "FFailQty>0"

    推荐 field_keys：
    FID,FBillNo,FDate,FDocumentStatus,FSupplierId.FName,FMaterialId.FName,FPassQty,FFailQty,FInspectTypeId.FName

    Returns:
        str: JSON 格式的来料检验单列表
    
- **kingdee_query_stock_transfer_apply** — 查询调拨申请单（STK_TransferApply）列表。

    调拨申请单用于申请仓库之间物料的转移，经审核后可下推生成调拨单。

    常用 filter_string：
    - 已审核: "FDocumentStatus='C'"
    - 指定调出仓库: "FSendStockId.FNumber='WH01'"
    - 指定调入仓库: "FReceiveStockId.FNumber='WH02'"

    推荐 field_keys：
    FID,FBillNo,FDate,FDocumentStatus,FSendStockId.FName,FReceiveStockId.FName

    Returns:
        str: JSON 格式的调拨申请单列表
    
- **kingdee_query_audit_log** — 查询金蝶云星空的审计日志（BOS_AuditLog）。

    记录单据的审核操作：谁在什么时候审核了哪张单据、审核结果是什么。
    用于合规审计、审批追溯、反舞弊检查。

    推荐场景：
    - 合规要求：保留所有审核操作的审计轨迹
    - 问题排查：某张单据的审核历史
    - 责任追溯：谁在什么时间通过了/驳回了审批

    返回字段说明：
    - FCREATEDATE: 审核时间
    - FCREATORID: 审核人
    - FOBJECTID: 单据内码
    - FFORMID: 单据类型
    - FAUDITRESULT: 审核结果（通过/驳回/取消）
    - FMEMO: 审核意见

    Returns:
        str: JSON 格式的审计日志列表
    
- **kingdee_query_operation_logs** — 查询金蝶云星空的上机操作日志（BOS_OperateLog）。

    记录用户在系统中的所有操作：登录、登出、进入业务对象、业务操作等。
    用于安全审计、故障排查、操作追溯。

    推荐场景：
    - 排查某张单据是谁在什么时候操作的
    - 安全审计：检查异常登录或批量操作
    - 合规要求：追溯敏感操作记录

    返回字段说明：
    - FDATETIME: 操作时间
    - FUSERID: 操作用户
    - FCOMPUTERNAME: 机器名称
    - FCLIENTIP: 客户端IP
    - FENVIRONMENT: 操作场景（0=登入系统, 1=进入业务对象, 3=业务操作, 4=登出系统）
    - FOPERATENAME: 操作名称（登录/单据查询/批量保存等）
    - FDESCRIPTION: 操作描述
    - FInterId: 对象内码（关联单据号）
    - FTimeConsuming: 耗时(毫秒)
    - FClientType: 客户端类型

    Returns:
        str: JSON 格式的操作日志列表
    
- **kingdee_query_change_log** — 查询金蝶云星空的单据变更记录（BOS_ModifyLog）。

    记录单据字段的修改历史：谁在什么时候修改了什么字段、从什么值改成了什么值。
    用于数据变更追溯、合规审计、问题排查。

    推荐场景：
    - 数据治理：追踪关键字段的变更历史
    - 问题排查：某张单据的修改记录
    - 合规要求：保留重要数据的修改轨迹

    返回字段说明：
    - FCREATEDATE: 修改时间
    - FCREATORID: 修改人
    - FOBJECTID: 单据内码
    - FFIELDNAME: 字段名称
    - FOLDVALUE: 修改前的值
    - FNEWVALUE: 修改后的值

    Returns:
        str: JSON 格式的变更记录列表
    
- **kingdee_query_approval_flow** — 查询金蝶云星空的审批流程记录。

    记录单据从提交到最终审核的完整审批轨迹，包括每个节点的审批人、时间、结果和意见。
    用于审批追溯、流程优化、合规检查。

    推荐场景：
    - 审批追溯：某张单据走过了哪些审批节点
    - 流程优化：分析审批时长和瓶颈
    - 合规检查：确认关键单据是否按流程审批

    注意：金蝶审批流程数据可能存储在多个表单中，
    如 V_SFA_ApprovalRecord（审批记录）、Workflow_Instance（流程实例）等。
    如查询无结果，请用 kingdee_get_fields 查看实际可用字段。

    Returns:
        str: JSON 格式的审批流程列表
    
- **kingdee_query_permission_changes** — 查询金蝶云星空的权限变更记录。

    记录用户权限的授予、撤销、修改操作。
    用于安全审计、合规检查、权限追溯。

    推荐场景：
    - 安全审计：谁在什么时候被授予/撤销了什么权限
    - 合规要求：保留权限变更的审计轨迹
    - 问题排查：某用户无法访问某功能的原因

    注意：金蝶权限数据可能存储在多个表单中，
    如 SEC_Permission（权限记录）、SEC_UserRole（用户角色关系）等。
    如查询无结果，请用 kingdee_get_fields 查看实际可用字段。

    Returns:
        str: JSON 格式的权限变更列表
    
- **kingdee_query_data_backup** — 查询金蝶云星空的数据备份记录。

    记录系统的数据备份和恢复操作。
    用于灾备验证、合规检查、恢复演练。

    推荐场景：
    - 灾备验证：确认备份是否按计划执行
    - 合规要求：保留备份操作的审计轨迹
    - 恢复演练：查找可用的备份点

    注意：金蝶备份数据可能存储在系统配置表或其他后台表单中，
    如需访问请确认当前用户有系统管理权限。
    如查询无结果，请用 kingdee_get_fields 查看实际可用字段。

    Returns:
        str: JSON 格式的数据备份记录列表
    
- **kingdee_query_purchase_inquiry** — 查洵采购询价单（SVM_InquiryBill/RFQ）列表。

    采购询价单（Request for Quotation）用于向供应商询价，收集报价信息。

    常用 filter_string：
    - 已审核: "FDocumentStatus='C'"
    - 指定供应商: "FSupplierId.FNumber='S001'"

    推荐 field_keys：
    FID,FBillNo,FDate,FDocumentStatus,FSupplierId.FName,FMaterialId.FName,FPrice

    Returns:
        str: JSON 格式的询价单列表
    
- **kingdee_query_supplier_quotes** — 查洵供应商报价单（SVM_QuoteBill）列表。

    供应商报价单是供应商对询价单的响应，包含物料价格信息。
    可用于比价分析，选择最优供应商。

    常用 filter_string：
    - 已审核: "FDocumentStatus='C'"
    - 指定供应商: "FSupplierId.FNumber='S001'"
    - 指定物料: "FMaterialId.FNumber='MAT001'"

    推荐 field_keys：
    FID,FBillNo,FDate,FDocumentStatus,FSupplierId.FName,FMaterialId.FName,FPrice,FQuantity

    Returns:
        str: JSON 格式的报价单列表
    
- **kingdee_query_misc_movement_detail** — 查询杂项出入库明细表（STK_MiscMovementDetail）。

    用于查看杂项出入库的明细数据，包括其他入库、其他出库等。

    常用 filter_string：
    - 指定日期范围: "FBillDate>='2024-01-01' and FBillDate<='2024-12-31'"
    - 指定物料: "FMaterialId.FNumber='MAT001'"
    - 指定仓库: "FStockId.FNumber='WH01'"

    推荐 field_keys（默认已包含关键字段）：
    FID,FBillNo,FBillDate,FDocumentStatus,FStockOrgId.FName,
    FMaterialId.FNumber,FMaterialId.FName,FUnitId.FName,FQty,FPrice,FAmount

    Returns:
        str: JSON 格式的杂项出入库明细列表
    
- **kingdee_query_transfer_pending_detail** — 查询分步式调出未调入明细表（STK_TransferPendingDetail）。

    用于查看分步式调拨流程中，已调出但未调入的单据明细。

    常用 filter_string：
    - 指定调出日期范围: "FOutDate>='2024-01-01' and FOutDate<='2024-12-31'"
    - 指定物料: "FMaterialId.FNumber='MAT001'"
    - 指定调出仓库: "FOutStockId.FNumber='WH01'"

    推荐 field_keys（默认已包含关键字段）：
    FID,FBillNo,FOutDate,FInDate,FDocumentStatus,FStockOrgId.FName,
    FOutStockId.FName,FInStockId.FName,FMaterialId.FNumber,FMaterialId.FName,
    FUnitId.FName,FOutQty,FInQty,FPendingQty

    Returns:
        str: JSON 格式的分步式调出未调入明细列表
    
- **kingdee_query_transfer_apply** — 查询调拨申请单（STK_TransferApply）列表。

    调拨申请单是调拨业务的起点，可下推生成直接调拨单或分步式调拨单。

    常用 filter_string：
    - 已审核: "FDocumentStatus='C'"
    - 指定日期范围: "FBillDate>='2024-01-01' and FBillDate<='2024-12-31'"
    - 指定调出仓库: "FOutStockId.FNumber='WH01'"
    - 指定调入仓库: "FInStockId.FNumber='WH02'"
    - 未关闭: "FCloseStatus='A' and FBusinessClose='A'"

    推荐 field_keys（默认已包含关键字段）：
    FID,FBillNo,FBillDate,FDocumentStatus,FStockOrgId.FName,
    FOutStockId.FName,FInStockId.FName,FTransferType,
    FMaterialId.FNumber,FMaterialId.FName,FUnitId.FName,FQty,FPrice,FAmount

    Returns:
        str: JSON 格式的调拨申请单列表
    
- **kingdee_query_transfer_direct** — 查询直接调拨单（STK_TransferDirect）列表。

    直接调拨单用于一步完成调拨业务，同时更新调出仓和调入仓库存。

    常用 filter_string：
    - 已审核: "FDocumentStatus='C'"
    - 指定日期范围: "FBillDate>='2024-01-01' and FBillDate<='2024-12-31'"
    - 指定调出仓库: "FOutStockId.FNumber='WH01'"
    - 指定调入仓库: "FInStockId.FNumber='WH02'"
    - 未关闭: "FCloseStatus='A' and FBusinessClose='A'"

    推荐 field_keys（默认已包含关键字段）：
    FID,FBillNo,FBillDate,FDocumentStatus,FStockOrgId.FName,
    FOutStockId.FName,FInStockId.FName,FMaterialId.FNumber,
    FMaterialId.FName,FUnitId.FName,FQty,FPrice,FAmount

    Returns:
        str: JSON 格式的直接调拨单列表
    
- **kingdee_push_stock_transfer** — 从调拨申请单下推到直接调拨单（STK_TransferApply -> STK_TransferDirect）。

    用于将调拨申请单下推生成直接调拨单，一步完成调拨。

    参数说明：
    - form_id: 固定为 STK_TransferApply（调拨申请单）
    - target_form_id: 固定为 STK_TransferDirect（直接调拨单）
    - source_bill_nos: 调拨申请单的单据编号列表

    转换规则说明：
    - 默认（rule_id=空）：使用系统配置的默认转换规则
    - enable_default_rule=true：强制启用默认下推规则
    - rule_id 显式指定：绕过默认规则，使用指定规则

    响应包含：
    - Result.ResponseStatus：保存结果（IsSuccess 判断整体是否成功）
    - Result.ConvertResponseStatus：每行下推转换结果

    Returns:
        str: JSON，含 success / bill_nos / next_action 字段
    
- **kingdee_query_material_cost** — 查询物料成本库（BD_MaterialCost）。

    返回物料的标准成本、最新成本、平均成本等信息。

    常用 filter_string：
    - 指定物料: "FMaterialId.FNumber='MAT001'"
    - 指定成本组织: "FCostOrgId.FNumber='100'"

    推荐 field_keys：
    FMaterialId.FNumber,FMaterialId.FName,FUnitId.FName,FStdCost,FLatestCost,FAvgCost

    Returns:
        str: JSON 格式的物料成本列表
    
- **kingdee_query_material_target_cost** — 查询物料目标成本单（BD_MatTargetCost）。

    常用 filter_string：
    - 已审核: "FDocumentStatus='C'"
    - 指定物料: "FMaterialId.FNumber='MAT001'"

    推荐 field_keys：
    FBillNo,FDate,FDocumentStatus,FMaterialId.FNumber,FMaterialId.FName,FTargetCost

    Returns:
        str: JSON 格式的目标成本单列表
    
- **kingdee_query_cost_calculation** — 查询成本计算单（CB_CostCalBill）列表。

    常用 filter_string：
    - 指定年度: "FYear=2024"
    - 指定期间: "FPeriod='01'"
    - 指定物料: "FMaterialId.FNumber='MAT001'"

    推荐 field_keys：
    FYear,FPeriod,FMaterialId.FNumber,FMaterialId.FName,FCostAmt,FMaterialCost,FLabourCost

    Returns:
        str: JSON 格式的成本计算单列表
    
- **kingdee_query_cost_centers** — 查询成本中心基础资料（CB_CostCenter）。

    常用 filter_string：
    - 指定编码: "FNumber like 'CC%'"
    - 启用状态: "FIsActive='1'"

    推荐 field_keys：
    FNumber,FName,FDeptId.FName,FIsActive

    Returns:
        str: JSON 格式的成本中心列表
    
- **kingdee_query_cost_items** — 查询成本项目基础资料（CB_CostItem）。

    常用 filter_string：
    - 指定编码: "FNumber like 'CI%'"
    - 成本项目类型: "FCostItemType='1'"

    推荐 field_keys：
    FNumber,FName,FCostItemType,FIsActive

    Returns:
        str: JSON 格式的成本项目列表
    
- **kingdee_query_product_standard_cost** — 查询产品标准成本（STD_ProductCostQuery）。

    常用 filter_string：
    - 指定物料: "FMaterialId.FNumber='MAT001'"
    - 指定成本版本: "FCostVersionId.FNumber='STD01'"

    推荐 field_keys：
    FMaterialId.FNumber,FMaterialId.FName,FUnitId.FName,FStdCost,FMaterialCost,FLabourCost,FFeeCost

    Returns:
        str: JSON 格式的产品标准成本列表
    
- **kingdee_query_cost_adjustments** — 查询成本调整单（STK_CostAdjust）。

    常用 filter_string：
    - 已审核: "FDocumentStatus='C'"
    - 指定调整类型: "FAdjustType='1'"

    推荐 field_keys：
    FBillNo,FDate,FDocumentStatus,FCostOrgId.FNumber,FCostOrgId.FName,FAdjustType,FAdjustAmount

    Returns:
        str: JSON 格式的成本调整单列表
    
- **kingdee_save_cost_adjustment** — 新建或修改成本调整单（STK_CostAdjust）。

    model 示例：
    {
      "FDate": "2024-01-15",
      "FCostOrgId": {"FNumber": "100"},
      "FAdjustType": "1",
      "FCostAdjustEntry": [
        {"FMaterialId": {"FNumber": "MAT001"}, "FAdjustQty": 100, "FAdjustPrice": 10.5}
      ]
    }

    Returns:
        str: JSON，含 FID 和 FBillNo
    
- **kingdee_query_instant_cost_compare** — 查询即时成本对比分析表（STK_InstantCostCompare）。

    对比即时成本与核算成本的差异。

    常用 filter_string：
    - 指定物料: "FMaterialId.FNumber='MAT001'"
    - 指定仓库: "FStockId.FNumber='WH01'"

    推荐 field_keys：
    FMaterialId.FNumber,FMaterialId.FName,FStockId.FName,FInstantCost,F核算成本,FDiffAmt

    Returns:
        str: JSON 格式的即时成本对比列表
    
- **kingdee_query_cost_trend** — 查询成本价趋势分析表（STK_CostTrend）。

    分析物料成本价格的变化趋势。

    常用 filter_string：
    - 指定物料: "FMaterialId.FNumber='MAT001'"
    - 指定日期范围: "FDate>='2024-01-01' and FDate<='2024-12-31'"

    推荐 field_keys：
    FMaterialId.FNumber,FMaterialId.FName,FDate,FCostPrice,FPriceChange

    Returns:
        str: JSON 格式的成本价趋势列表
    
- **kingdee_query_finished_product_cost** — 查询完工入库产品成本（CB_FinishInCostQuery）。

    常用 filter_string：
    - 指定生产订单: "FMoBillNo='MO000001'"
    - 指定期间: "FYear=2024 and FPeriod='01'"

    推荐 field_keys：
    FMoBillNo,FMaterialId.FNumber,FMaterialId.FName,FFinishQty,FCostPrice,FCostAmt

    Returns:
        str: JSON 格式的完工成本列表
    
- **kingdee_query_material_cost_usage** — 查询生产材料耗用成本（CB_MaterialCostQuery）。

    常用 filter_string：
    - 指定生产订单: "FMoBillNo='MO000001'"
    - 指定物料: "FMaterialId.FNumber='MAT001'"

    推荐 field_keys：
    FMoBillNo,FMaterialId.FNumber,FMaterialId.FName,FConsumeQty,FCostPrice,FCostAmt

    Returns:
        str: JSON 格式的材料耗用成本列表
    
- **kingdee_query_production_orders** — 查询生产订单（PRD_MO）列表。

    常用 filter_string：
    - 已审核: "FDocumentStatus='C'"
    - 指定日期: "FDate>='2024-01-01'"
    - 进行中: "FStatus='2'"  (1=计划,2=确认,3=投料,4=汇报,5=入库)
    - 指定物料: "FMaterialId.FNumber='MAT001'"

    推荐 field_keys：
    FID,FBillNo,FDate,FDocumentStatus,FMaterialId.FName,FQty,FPlanStartDate,FPlanFinishDate,FStatus

    Returns:
        str: JSON 格式的生产订单列表
    
- **kingdee_query_production_pick_materials** — 查询生产领料单（PRD_PickMtrl）列表。

    常用 filter_string：
    - 已审核: "FDocumentStatus='C'"
    - 指定生产订单: "FMoBillNo='MO000001'"
    - 指定仓库: "FStockId.FNumber='CK001'"

    推荐 field_keys：
    FID,FBillNo,FDate,FDocumentStatus,FMoBillNo,FMaterialId.FName,FPickQty,FStockId.FName

    Returns:
        str: JSON 格式的生产领料单列表
    
- **kingdee_query_production_stock_in** — 查询生产入库单（PRD_Instock）列表。

    常用 filter_string：
    - 已审核: "FDocumentStatus='C'"
    - 指定生产订单: "FMoBillNo='MO000001'"
    - 指定仓库: "FStockId.FNumber='CK001'"

    推荐 field_keys：
    FID,FBillNo,FDate,FDocumentStatus,FMoBillNo,FMaterialId.FName,FInQty,FStockId.FName

    Returns:
        str: JSON 格式的生产入库单列表
    
- **kingdee_view_production_order** — 查看生产订单（PRD_MO）完整详情。

    必填参数：
    - form_id: "PRD_MO"
    - bill_id: 单据 FID 或 bill_no: 单据编号

    Returns:
        str: JSON 格式的生产订单完整数据
    
- **kingdee_save_production_order** — 新建或修改生产订单（PRD_MO）。

    新建示例：
    {
      "FDate": "2024-01-15",
      "FMaterialId": {"FNumber": "MAT001"},
      "FQty": 100,
      "FPlanStartDate": "2024-01-20",
      "FPlanFinishDate": "2024-01-25"
    }

    Returns:
        str: JSON，含 FID 和 FBillNo
    
- **kingdee_submit_production_orders** — 提交生产订单（PRD_MO）至审核队列。

    Returns:
        str: JSON，含 success / next_action / bill_ids
    
- **kingdee_audit_production_orders** — 审核生产订单（PRD_MO）。

    Returns:
        str: JSON，含 success / bill_ids
    
- **kingdee_push_production_pick** — 从生产订单下推生成生产领料单（PRD_PickMtrl）。

    Returns:
        str: JSON，含 success / target_bill_nos / next_action
    
- **kingdee_push_production_stock_in** — 从生产领料单下推生成生产入库单（PRD_Instock）。

    Returns:
        str: JSON，含 success / target_bill_nos / next_action
    
- **kingdee_query_mrp_result** — 查询 MRP 运算结果（PLAN_MRPResult）。

    来自销售订单/销售预测/库存不足等需求，经 MRP 运算生成的计划订单建议。
    可下推生成采购申请/生产订单。

    Returns:
        str: JSON 数组，每条含 FBillNo/FMaterialId/FSrcBillNo/FPurchaseQty 等字段。
    
- **kingdee_query_production_plan** — 查询生产计划单（PLAN_ProductionPlan）。

    生产计划单是 MRP 运算后手工调整的计划单据，可直接下推生成生产订单。

    Returns:
        str: JSON 数组。
    
- **kingdee_query_production_report** — 查询生产汇报单（PRD_MOReport）。

    生产汇报记录工序完成数量/工时/良品率等信息，是生产入库的提前工序。

    Returns:
        str: JSON 数组，含 FBillNo/FMOId/FMaterialId/FReportQty/FHourQty 等。
    
- **kingdee_query_report** — 通过金蝶 WebAPI **GetSysReportData（查询报表数据）** 查询任意总账/财务报表。

    端点：Kingdee.BOS.WebApi.ServicesStub.DynamicFormService.GetSysReportData.common.kdsvc
    （实测确认：formid 必须作为独立 HTTP 表单字段、data 为内层参数的 JSON 字符串。
    此前"表单标识为空"的根因是 formid 被嵌进了 data JSON 对象；KDSReportAPIService
    端点实测也一律 Unknown Error，不可用。）

    请求体为 HTTP 双字段：formid = 报表标识；data = JSON 字符串（即本工具 params.data）。
    model 典型结构：FieldKeys(返回字段) + Model(过滤条件) + StartRow/Limit(分页)。
    与单据查询(ExecuteBillQuery)不同，报表分页用 StartRow/Limit，**不是** PageIndex/PageSize；
    账簿用 FACCTBOOKID.FNumber（按编码，如 "001"）；期间用
    FSTARTYEAR/FSTARTPERIOD/FENDYEAR/FENDPERIOD，层级用 FBALANCELEVEL。
    ⚠️ FieldKeys 必须是报表真实列 Key——猜的列名会触发服务端 totalWidth 渲染错误；
    FBALANCELEVEL=0（全部级次）时**必须**配 FSHOWFULLNAME=true，否则
    AccountBalanceStatement.UpdateAcctName 会因 PadLeft(-N) 抛 "totalWidth 要求非负数"。
    💡 0 行结果通常是该账簿/期间 T_GL_BALANCE 本身无数据，并非查询失败
    （book '001' 金蝶蓝海科技只有 2020 年演示数据，2026 年返回 0 行属于正常）。

    已实测确认的报表 formId（财务会计 → 总账）：
      - 科目余额表   = GL_RPT_AccountBalance
      - 总账账龄分析表 = GL_AgingSchedule（注意：无 RPT_ 前缀）
    其余报表 formId 需在 BOS/ApiDoc 逐张查证（核算维度余额表、数量金额总账、日报表、
    多账簿系列、试算平衡表、现金流量表、现金流量查询、报表项目 KDS_RptItem 等）。

    params.data（model）权威结构——科目余额表（金蝶开发者社区官方案例 + 2026-08-05 实测
    book '001' 金蝶蓝海科技 → 2020 年 2 月 期初/本期/本年累计/期末数据完整 72 行）：
      {"FieldKeys":"FBALANCEID,FBALANCENAME,FACCTTYPE,FACCTGROUP,FCyName,"
                    "FBEGINDEBIT,FBEGINCREDIT,FDEBIT,FCREDIT,"
                    "FYTDDEBIT,FYTDCREDIT,FENDDEBIT,FENDCREDIT",
       "SchemeId":"","StartRow":0,"Limit":10,
       "IsVerifyBaseDataField":"true","FilterString":[],
       "Model":{"FACCTBOOKID":{"FNumber":"001"},"FCURRENCY":"1",
                "FSTARTYEAR":2020,"FSTARTPERIOD":2,"FENDYEAR":2020,"FENDPERIOD":2,
                "FBALANCELEVEL":1,"FSHOWDETAIL":false,"FFORBIDBALANCE":true,
                "FBALANCEZERO":true,"FPERIODNOBALANCE":true,"FYEARNOBALANCE":true,
                "FSHOWFULLNAME":true}}

    返回：金蝶原始 JSON（含报表数据 Rows），前端/调用方按需解析。

    Raises/Returns:
        str: JSON（成功为报表数据；失败为错误 JSON）
    

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `uvx` (confidence: high):

```json
"mcpServers": {
  "kingdeemcp": {
    "command": "uvx",
    "args": ["kingdee-mcp"],
    "env": {
      "KINGDEE_SERVER_URL": "",
      "KINGDEE_ACCT_ID": "",
      "KINGDEE_USERNAME": "",
      "KINGDEE_PASSWORD": ""
    }
  }
}
```

**Requires environment variables:** `KINGDEE_SERVER_URL`, `KINGDEE_ACCT_ID`, `KINGDEE_USERNAME`, `KINGDEE_PASSWORD` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What KingdeeMCP does

KingdeeMCP exposes Kingdee Cloud Star ERP operations through the Model Context Protocol. AI assistants can use natural-language requests to query or mutate ERP records while the server translates tool calls into Kingdee WebAPI requests.

The tool set covers 17 business areas and 101 tools. Supported areas include purchasing, sales, inventory, production, cost accounting, fixed assets, outsourcing, finance, receipts, approvals, audit logs, permissions, reports, attachments, and general bill processing. Developers can also inspect forms and fields, retrieve bill templates, validate bills, refresh cached metadata, and explore selected SQL Server structures.

Typical requests include finding approved purchase orders, creating a sales order, checking inventory, submitting or auditing bills, reviewing pending approvals, and retrieving financial reports. Nine example business scenarios are included for common query, creation, approval, and bill-push workflows.

## How it works

The default transport is stdio, where a local MCP client starts the package as a subprocess. Remote deployments can use SSE at `/sse` or Streamable HTTP at `/mcp`; the process can listen on a specified host and port. Docker deployments default to Streamable HTTP on port 8000, while a container can also be run in stdio mode.

Authentication uses Kingdee's account-password `ValidateUser` login rather than an application ID and secret. The logged-in account's ERP permissions and WebAPI data permissions therefore govern operations. The server uses asynchronous requests, retries failed connections, and can log in again when a session expires. Pydantic validation supplies structured tool parameters.

## Setup and configuration

Install the package with `pip install kingdee-mcp`, or run it directly with `uvx kingdee-mcp`. Configure the required `KINGDEE_SERVER_URL`, `KINGDEE_ACCT_ID`, `KINGDEE_USERNAME`, and `KINGDEE_PASSWORD` variables. The server URL must include `/k3cloud/`.

A local client configuration launches `uvx` with `kingdee-mcp` as its argument and passes these variables in the process environment. Command-line options or `KINGDEE_MCP_TRANSPORT`, `KINGDEE_MCP_HOST`, and `KINGDEE_MCP_PORT` select the transport and listener settings.

Docker images are available from `ghcr.io/wahailong/kingdeemcp`. A `.env` file can provide credentials, and the `--check` option performs a one-time Kingdee login without starting the service. SQL Server exploration requires additional database settings and the Microsoft ODBC driver; the container includes only the base Unix ODBC library.

## Tools and capabilities

Representative tools include:

- Query purchase orders, sales orders, inventory, production orders, materials, partners, users, roles, receipts, and financial reports.
- Save, submit, audit, unaudit, delete, close, validate, and push bills.
- Approve workflow items and inspect approval flows, operation logs, audit logs, change logs, and permission changes.
- Discover forms, fields, bill templates, metadata candidates, SQL Server tables, columns, and table structures.
- Upload and download header or line-item attachments using chunked transfer.
- Query system configuration, quality inspections, expense reimbursements, number rules, loan balances, and backups.

## Limitations and notes

KingdeeMCP is a third-party open-source project rather than an official Kingdee product. A Kingdee account must have the permissions required by the requested modules and operations; the server does not replace ERP authorization. Remote HTTP transport also does not replace Kingdee login.

The SQL Server inspection tools need separate database connectivity and ODBC setup. Keep credentials in environment variables rather than embedding them in client prompts or tool arguments. Existing configurations based on the older application-ID and application-secret login must be migrated to the account-password variables.

_Full upstream README: https://allmcps.com/mcp/kingdeemcp/readme_