Skip to main content
Glama
sanxiao-mcp
by adambbhe

sanxiao-mcp — Kingdee Cloud·Xingchen "Sanxiao Project Management" MCP Server

GC032 Financial Agent · Sanxiao endpoint. App identifier bdi_projectmanagement, subscription URL https://cloud.kingdee.com/kae/#/market/detail?sid=1285.

Implemented per the official 《Sanxiao Project Management API_2025》 documentation + 《Kingdee Sanxiao Project Management API Development Framework》. Phase 1 read-only: all query operations enabled; write operations are in place in code but rejected by guards by default.

The shape of the Sanxiao API (understand this first, the rest is easy)

Sanxiao is not "one endpoint per business" — it is generic Bill CRUD: all bills — project profiles, loans, reimbursements, payments, working-hour entries, purchase requests — go through the same set of interfaces, driven by formId + field identifiers.

POST https://bj1-api.kingdee.com/bdiprojectapi/common/{action}
后端  openapi/ierp/kapi/app/bdi_projectmanagement/{action}

action ∈ { listQuery, getById, saveOrUpdate, submit, unSubmit,
           audit, unAudit, delete, push, operation }

So this service's structure is also "one gateway + two layers of wrapping", rather than dozens of endpoint constants.

Related MCP server: iGuat-MCP

Table of Contents

sanxiao/
├── config.py    环境与鉴权四要素;url() / headers() 在这里定形
├── forms.py     formId 登记表 + 中文别名解析(项目档案 → bdi_projectfile)
├── query.py     qParams 结构化查询 DSL:构造、校验、还原成类 SQL 可读串
├── models.py    saveOrUpdate 字段模型(8 种 fType + 分录 + 下推 + 附件)
├── guards.py    白名单 + 默认拒绝 + 审计
├── client.py    唯一 HTTP 出口 _post(),读写方法都从这里过
└── server.py    28 个 MCP 工具(通用层 + 语义层)
test_connection.py   L1 配置 → L2 网络 → L3 鉴权 → L4 只读 → L5 守卫
tests/               pytest:query / models / guards / client

Authentication: four request headers, no signature

Unlike kingdee-star-mcp (jdy open gateway) — Sanxiao requires no HMAC signature, just four headers, all obtained in advance via the standard Xingchen API:

Header

Source of value

Token

Product account-set-level token, obtained via Xingchen standard API authentication

X-GW-Router-Addr

IDC domain = the domain field in the 【Real-time Receiving Authorization】push message

groupname

Authorization info, pushed by the open platform to the sandbox message receiving address

accountid

Same as above

Pitfall warning: The official docs explicitly state "when debugging in the cloud platform API marketplace, X-GW-Router-Addr can be ignored". So many people get it working in the marketplace, then hit 404 as soon as they write code — because code calls must include this header. config.headers() already handles this; don't delete it.

Once you have the four elements, fill them into .env (template in .env.example).

Quick Start

pip install -r requirements.txt
cp .env.example .env        # 填入四要素
pytest -q                   # 69 项单测应全绿
python test_connection.py   # 分层联调,结果写入 connection_test_result.txt

On Windows, just double-click run_test.bat.

MCP Tools (28)

Meta Information

Tool

Purpose

sx_health

Gateway address, read-only switch, readiness status of the four elements and what's missing

sx_list_forms

Registered formIds, Chinese names, default fields

sx_capabilities

Available actions, read-only operation whitelist, currently permitted write actions

Generic Layer — Full Mapping of Official Interfaces

Tool

Official Interface

sx_list_query

listQuery

sx_get_by_id

getById

sx_operation

operation (constrained by the read-only whitelist)

sx_build_query

Local tool: translates simplified conditions into qParams, sends no request

Semantic Layer — No Need to Memorize formIds

sx_list_projects / sx_list_reimbursements / sx_list_loans / sx_list_payments / sx_list_working_hours / sx_get_bill sx_query_cost_budget / sx_query_material_budget / sx_query_working_hour_budget sx_get_user_permission / sx_get_form_config / sx_workflow_status / sx_get_app_parameter

Write Layer — Rejected by Default

sx_build_bill_payload (only assembles, does not send; usable in phase 1 for manual review of the payload) sx_save_or_update / sx_submit / sx_un_submit / sx_audit / sx_un_audit / sx_delete / sx_push

How to Write Query Conditions

The official qParams is an array of conditions: top-level items are joined by and, and within a condition group items are joined by joinKey.

[
  { "childGroup": false, "qKey": "number", "qCp": "like", "qValue": "ew" },
  { "childGroup": true,  "joinKey": "or", "childCondition": [
      { "childGroup": false, "qKey": "number", "qCp": "=", "qValue": "new5" },
      { "childGroup": false, "qKey": "number", "qCp": "=", "qValue": "New" }
  ]}
]
// 等价于 number like '%ew%' and (number='new5' or number='New')

Comparison operators: = > >= < <= != like likeLeft. There is no in — use query.any_of() or the or-group in sx_build_query to simulate it. Entry fields are written as "entry identifier.field identifier", e.g. projectfileteam.teamstaff.

Security Model

The guard is a whitelist + default-deny three-layer design:

  1. Action classification — listQuery/getById/operation are reads; the other seven are writes.

  2. operationKey whitelist — operation looks like a read interface, but operationKey is a free-form string, so the nine methods in doc sections 10.1–10.9 get a second whitelist pass.

  3. Funds-related operations permanently write-blocked — writes and workflow actions on payment bills (bdi_ex_pay*), even SX_ALLOW_WRITE_ACTIONS=* will not bypass this.

Order for enabling writes in phase 2: SX_READONLY=false → add actions one by one in SX_ALLOW_WRITE_ACTIONS for gray rollout. Do not jump straight to *.

All calls and blocks are logged to the sanxiao.audit logger.

Real Payloads Overturn What the Docs Suggest

The official 《Sanxiao-API Reference Code》 is a complete bdi_projectfile bill payload (saved as tests/fixtures/projectfile_reference.json). It is more trustworthy than the doc examples, and overturns four assumptions taken for granted — each one is pinned down in tests/test_reference_payload.py, and reverting any of them will fail immediately:

What the doc examples suggest

What the real payload shows

Every field has fValue

Empty-value fields omit the fValue key entirely, not fValue:""

enum must come with fValueText

status/enable/enablecostamtctl all have only fValue

fValue is always a string

Native true / false / 0 appear, mixed with string "10"

fValueText is exclusive to enums

bd also carries it, holding the display name of the base data

The third one is the most dangerous: an earlier str(d["fValue"]) in field_from_dict, when hitting {"fType":"enum","fValue":true}, would produce Python-style "True" — a string with a capital T, which the server does not recognize, and the error message will not tell you this is the cause. Now fValue is passed through as-is.

The benefit is that getById responses can be fed straight back into saveOrUpdate (change one or two fields and save again), lossless round-trip, and this path is guarded by test_roundtrip_is_lossless.

Additionally, eight base-data formIds were extracted from the bd field of the payload and registered in forms.py: bd_employee, bd_department, bd_customer, bdi_bd_customer_fork, bdi_projecttypes, bdi_projectarea, bdi_projectstauts, bdi_projectroles.

bdi_projectstauts is not a typo — the vendor spelled status as stauts, and both the formId and field names use that spelling. Don't "fix it" out of habit.

Where Field Identifiers Come From

Don't guess. The authoritative method is in the Xingchen UI: Bill list → More → Import Data → Template Management → New Template.

Once running, you can also look it up in reverse: sx_get_form_config(form_id) calls operation.getUserconfig and returns that bill's field configuration.

forms.py registers 15 formIds: seven from the official docs (bdi_projectfile, bdi_ex_loan, bdi_ex_bx, bdi_ex_pay, bdi_fillinworkinghours, pur_bill_request, bd_auxinfo), and eight base-data references from the reference-code payload. For other bills, just pass the formId directly to sx_list_query — no need to register first.

Same for field names — only bdi_projectfile's fields have been verified against the real payload (note it uses status/enable, not billstatus; that belongs to business bills). The default fields for other bills are still inferred by convention; after getting them working, please verify with sx_get_form_config.

Relationship with kingdee-star-mcp

The two are two open capabilities of the same Xingchen account set, each deployed independently:

kingdee-star-mcp

sanxiao-mcp

Gateway

api.kingdee.com jdy gateway

bj1-api.kingdee.com Sanxiao gateway

Auth

HMAC signature + app-token two-layer credentials

Four headers, no signature

Endpoints

/jdy/v2/{module}/{object} hundreds

common/{action} ten

Coverage

Finance (vouchers, reimbursements, receivables/payables)

Project management (projects, working hours, budgets, reimbursements)

Sanxiao's Token must first be obtained via the Xingchen standard API — if you've already gotten the authorization chain working in kingdee-star-mcp, you can fill the token you obtained along with the domain/groupname/accountid from the authorization push directly into this project's .env.

Known Gaps

  • The official docs do not provide a unified response body schema; client._unwrap() does a loose unwrap: if it can recognize errcode/success/data it normalizes, otherwise it returns as-is — better to return extra data than to swallow data by guessing the structure wrong. It can be tightened once real responses are available.

  • Bill status codes are not fully documented. In the reference code, project profile status="A", enable="1", but what A/B/C each mean, and the value domain of billstatus for business bills, still lack authoritative explanation. The semantic layer's status parameter currently passes through the raw identifier.

  • In the reference code, a few fields have contradictory fType values — phaseplanenddate, phaseenddate are declared as num yet are clearly dates. This is an inconsistency in the vendor's own payload; the model layer accepts it as-is without correction, so as not to "help in the wrong direction".

  • Attachment upload goes through base64; large files need evaluation against the gateway size limit, which the docs do not specify.

Available Tools

28 tools
sx_auditC

审核单据(官方 audit)。默认被只读守卫拒绝。

Inputs: data_id (required), form_id (required).

sx_build_bill_payloadA

【只组装不发送】把单据 dict 校验并序列化成官方 dataJsonStr,供人工核对。

bill 形如: {"billFormId":"bdi_fillinworkinghours","billId":"0","billNo":"", "fields":[{"fType":"text","fKey":"billno","fValue":"..."}, {"fType":"bd","fFormId":"bdi_projectfile","fKey":"projectfiles","fValue":"..."}, {"fType":"entry","fKey":"entryworkinghours", "fEntities":[{"entryId":"0","entryFields":[...]}]}]} 本工具不调用任何接口,只读环境下也可放心使用。

Inputs: bill (required).

sx_build_queryA

把简化条件翻译成官方 qParams 数组,不发起请求,用于先验证再查询。

conditions 每项形如 {"key": "billdate", "op": ">=", "value": "2025-01-01"}; 或分组 {"join": "or", "children": [ ...同上... ]}。 返回 qParams 数组与类 SQL 的可读描述。

Inputs: conditions (required).

sx_capabilitiesA

列出可用的 action、只读 operation 方法白名单,以及当前放行的写动作。

Inputs: no named parameters.

sx_deleteB

删除单据(官方 delete)。默认被只读守卫拒绝。

Inputs: data_id (required), form_id (required).

sx_get_app_parameterC

获取三效系统参数(operation.loadAppParameter)。

Inputs: para_code (required), app_code.

sx_get_billB

查任意单据详情,form_id 支持中文别名。with_attachments=True 时带上默认附件面板。

Inputs: data_id (required), form_id (required), with_attachments.

sx_get_by_idC

按单据 Id 查详情(官方 getById)。attach_keys 为附件面板标识,如 ["attachmentpanel"]。

Inputs: data_id (required), form_id (required), attach_keys.

sx_get_form_configC

查询单据字段配置(operation.getUserconfig)——想知道某单据有哪些字段标识时用这个。

Inputs: form_id (required), form_id_ex, entry_marks.

sx_get_user_permissionC

查询当前用户对若干单据的权限(operation.getUserPermission)。

Inputs: form_ids (required).

sx_healthB

健康检查:返回网关地址、只读开关、鉴权四要素就绪状态与缺失项。

Inputs: no named parameters.

sx_list_formsA

列出本服务已登记的三效单据标识(formId)、中文名与默认查询字段。

未登记的单据仍可直接把 formId 传给 sx_list_query,此表只是便利。 formId 与字段标识的权威来源:星辰单据列表 → 更多 → 引入数据 → 模板管理 → 新增模板。

Inputs: no named parameters.

sx_list_loansC

查询借款单(bdi_ex_loan)。

Inputs: fields, status, bill_no, date_to, +4 more.

sx_list_paymentsB

查询付款单(bdi_ex_pay)。只读——付款类写操作在本服务中永久禁止。

Inputs: fields, status, bill_no, date_to, +4 more.

sx_list_projectsC

查询项目档案(bdi_projectfile)。keyword 对项目名称做 like 模糊匹配。

Inputs: fields, keyword, order_by, page_size, +1 more.

sx_list_queryA

列表查询任意三效单据(官方 listQuery)。

form_id: 单据标识或中文别名,如 bdi_projectfile / "项目档案" fields: 字段标识,逗号分隔;分录字段写「分录标识.字段标识」, 如 "id,number,name,projectfileteam.teamstaff";留空取默认字段 params: qParams 条件数组,叶子形如 {"childGroup": false, "qKey": "number", "qCp": "like", "qValue": "ew"} 条件组形如 {"childGroup": true, "joinKey": "or", "childCondition": [ ...叶子... ]} 顶层各项之间是 and。比较符:=,>,>=,<,<=,!=,like,likeLeft order_by: 如 "id desc,name asc" data_permission: all 全部 / self 仅制单人自己

Inputs: form_id (required), fields, params, order_by, +3 more.

sx_list_reimbursementsB

查询报销单(bdi_ex_bx)。日期形如 2025-01-01;status 为单据状态标识,如 A 暂存。

Inputs: fields, status, bill_no, date_to, +4 more.

sx_list_working_hoursC

查询工时填报(bdi_fillinworkinghours)。分录标识 entryworkinghours。

Inputs: fields, status, bill_no, date_to, +4 more.

sx_operationB

执行三效自定义方法(官方 operation)。

只读白名单:loadAppParameter, getUserPermission, getUserconfig, materialBudget, costBudget, workingHourBudget, getAttachFieldPermission, enableWorkflow, isInWorkflow。参数用 dict 传,本工具负责序列化成 官方要求的 operationParJsonStr 字符串。

Inputs: operation_key (required), par.

sx_pushA

单据下推(官方 push),如借款单下推报销单。

按单据下推传 bill_ids;按分录下推传 entry_ids + src_entry_mark(源单分录标识)。 返回的目标单据数据包在保存时需回传 pushPar。默认被只读守卫拒绝。

Inputs: src_form_id (required), dest_form_id (required), bill_ids, entry_ids, +1 more.

sx_query_cost_budgetB

查询费用预算(operation.costBudget)。now_bill_id 新建单据传 0。

Inputs: form_id (required), project_id (required), cost_id, now_bill_id, +2 more.

sx_query_material_budgetC

查询物料预算(operation.materialBudget)。

Inputs: form_id (required), project_id (required), material_id, now_bill_id, +1 more.

sx_query_working_hour_budgetC

查询工时预算(operation.workingHourBudget)。

Inputs: form_id (required), project_id (required), now_bill_id.

sx_save_or_updateB

保存/修改单据(官方 saveOrUpdate)。默认被只读守卫拒绝,需 SX_READONLY=false 且 SX_ALLOW_WRITE_ACTIONS 含 saveOrUpdate 才会真正发送。

Inputs: bill (required).

sx_submitC

提交单据审批(官方 submit)。默认被只读守卫拒绝。

Inputs: data_id (required), form_id (required).

sx_un_auditC

反审核单据(官方 unAudit)。默认被只读守卫拒绝。

Inputs: data_id (required), form_id (required).

sx_un_submitC

撤销提交(官方 unSubmit)。默认被只读守卫拒绝。

Inputs: data_id (required), form_id (required).

sx_workflow_statusC

查工作流状态:是否启用工作流;给了 bill_id 时再查该单是否已在流程中。

Inputs: form_id (required), bill_id.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.9/5.0

    Scored across 28 tools

    Disambiguation4/5

    Most tools target distinct resources or actions, e.g. list_query is generic while list_projects is form-specific. However, sx_get_by_id and sx_get_bill both retrieve single bills with similar semantics, and sx_operation overlaps with specific query tools, creating minor ambiguity.

    Naming Consistency3/5

    All tools share the sx_ prefix, and most follow verb_noun patterns (sx_list_*, sx_get_*, sx_query_*, sx_build_*). However, sx_health and sx_capabilities are nouns rather than verbs, and there is mixing between list/get/query verbs with no strict rule, slightly reducing predictability.

    Tool Count2/5

    With 28 tools, the server clearly exceeds the 25-tool threshold for heavy sets. While many tools target specific query types, generic tools like sx_list_query could absorb some of them, making the surface feel redundant and bloated.

    Completeness4/5

    The toolset covers the full lifecycle of bills: list, get, save/update, delete, audit, submit, unsubmit, unaudit, and push. It also includes capabilities like budget queries, permissions, form config, and health checks. Only minor gaps exist, such as batch operations or specialized export tools, but core workflows are well-supported.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      A
      quality
      D
      maintenance
      Enables read-only access to Kingdee Cloud Star financial data, invoice tax calculation, and generation of reimbursement draft payloads through MCP tools.
      17
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables read-only queries of i桂航 campus data, including schedules, classes, terms, and campus information through MCP tools.
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Provides MCP access to an internal performance and consulting project collaboration system, enabling management of projects, stages, tasks, materials, evidence, approvals, and experience in a traceable chain, with Feishu for organization sync and collaboration.
      Apache 2.0
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables Claude, Cursor, and other AI assistants to query and operate Kingdee Cloud Star ERP—covering purchasing, sales, inventory, manufacturing, costing, fixed assets, financial reports, and approvals—using natural language through 87 MCP tools.
      -