sanxiao-mcp
sanxiao-mcp —— Kingdee Cloud·星辰 „Drei-Effekt-Projektmanagement" MCP-Server
GC032 Finanz-Agent · Drei-Effekt-Endpunkt. Anwendungs-ID bdi_projectmanagement,
Abonnement-URL https://cloud.kingdee.com/kae/#/market/detail?sid=1285.
Implementiert gemäß dem offiziellen Dokument „Drei-Effekt-Projektmanagement API_2025" + „Kingdee Drei-Effekt-Projektmanagement-API-Entwicklungsframework". Phase 1 nur lesend: Alle Abfragen vollständig geöffnet, Schreibklassen-Code ist vorhanden, wird aber standardmäßig von der Schutzfunktion abgelehnt.
Die Form der Drei-Effekt-API (erst das verstehen, der Rest ist einfach)
Drei-Effekt ist nicht „ein Geschäftsfall, ein Endpunkt", sondern generisches Beleg-CRUD (Bill):
Alle Belege —— Projektstammdaten, Darlehen, Erstattungen, Zahlungen, Arbeitszeiterfassung, Beschaffungsanträge —— laufen über dieselbe Schnittstellengruppe,
gesteuert über formId + Feldkennungen.
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 }Daher ist die Struktur dieses Dienstes ebenfalls „ein Ausgang + zwei Ebenen der Kapselung", nicht dutzende Endpunkt-Konstanten.
Related MCP server: iGuat-MCP
Inhaltsverzeichnis
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 / clientAuthentifizierung: vier Request-Header, keine Signatur
Anders als kingdee-star-mcp (jdy-Open-Gateway) —— Drei-Effekt benötigt keine HMAC-Signatur,
es genügen vier Header, die alle vorab über die Standard-API von Cloud·星辰 bezogen werden:
Header | Bezugsquelle |
| Token auf Produkt-Mandantenebene, über die Standard-API-Authentifizierung von 星辰 bezogen |
| IDC-Domain = |
| Autorisierungsinformation, von der offenen Plattform an die Sandbox-Nachrichtenempfangsadresse gepusht |
| Ebenso |
Stolperfallen-Hinweis: Die offizielle Dokumentation schreibt ausdrücklich „beim Debuggen im API-Markt der Cloud-Plattform kann
X-GW-Router-Addrignoriert werden". Daher haben viele im Markt erfolgreich getestet, aber im Code kommt 404 —— weil der Code-Aufruf zwingend diesen Header benötigt.config.headers()behandelt das bereits, nicht löschen.
Nach Erhalt der vier Elemente in .env eintragen (Vorlage siehe .env.example).
Schnellstart
pip install -r requirements.txt
cp .env.example .env # 填入四要素
pytest -q # 69 项单测应全绿
python test_connection.py # 分层联调,结果写入 connection_test_result.txtUnter Windows einfach run_test.bat doppelklicken.
MCP-Tools (28)
Metainformationen
Tool | Zweck |
| Gateway-Adresse, Nur-Lese-Schalter, Bereitschaftsstatus der vier Elemente und fehlende Einträge |
| Registrierte formIds, chinesische Namen, Standardfelder |
| Verfügbare Aktionen, Nur-Lese-Operations-Whitelist, aktuell freigegebene Schreibaktionen |
Generische Ebene —— vollständige Abbildung der offiziellen Schnittstellen
Tool | Offizielle Schnittstelle |
|
|
|
|
|
|
| Lokales Tool: übersetzt vereinfachte Bedingungen in |
Semantische Ebene —— formId muss man nicht auswendig lernen
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
Schreibeebene —— standardmäßig abgelehnt
sx_build_bill_payload (nur Zusammenbau, kein Senden; in Phase 1 auch zur manuellen Prüfung der Nachricht nutzbar)
sx_save_or_update / sx_submit / sx_un_submit / sx_audit / sx_un_audit
/ sx_delete / sx_push
Wie Abfragebedingungen geschrieben werden
Offizielle qParams sind ein Bedingungsarray: Die Elemente der obersten Ebene sind und-verknüpft, innerhalb einer Bedingungsgruppe über joinKey verbunden.
[
{ "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')Vergleichsoperatoren: = > >= < <= != like likeLeft. Es gibt kein in —— stattdessen query.any_of()
oder die Oder-Gruppe von sx_build_query verwenden. Positionsfelder werden als „Positionskennung.Feldkennung" geschrieben,
z. B. projectfileteam.teamstaff.
Sicherheitsmodell
Die Schutzfunktion ist Whitelist + Standard-Ablehnung in drei Ebenen:
Aktionsklassifizierung ——
listQuery/getById/operationsind lesend, die übrigen sieben sind schreibend.operationKey-Whitelist ——
operationist oberflächlich eine Lese-Schnittstelle, aberoperationKeyist ein freier String, daher wird für die neun Methoden aus Dokument 10.1–10.9 eine weitere Whitelist angewendet.Finanzklassen dauerhaft schreibgeschützt —— Schreib- und Prozessaktionen für Zahlungsbelege (
bdi_ex_pay*), selbst beiSX_ALLOW_WRITE_ACTIONS=*gesperrt.
Reihenfolge für das Öffnen des Schreibens in Phase 2: SX_READONLY=false → in SX_ALLOW_WRITE_ACTIONS
Aktionen einzeln per Gray-Release hinzufügen. Nicht in einem Schritt auf *.
Alle Aufrufe und Sperrungen werden an den sanxiao.audit-Logger ausgegeben.
Echte Nachrichten widerlegen den Eindruck der Dokumentation
Der offiziell zusätzlich bereitgestellte „Drei-Effekt-API-Referenzcode" ist eine vollständige bdi_projectfile-Belegnachricht
(gespeichert als tests/fixtures/projectfile_reference.json). Sie ist glaubwürdiger als die Dokumentationsbeispiele
und widerlegt vier naheliegende Annahmen —— jede davon ist in tests/test_reference_payload.py
festgenagelt; eine Rückänderung führt sofort zu roten Tests:
Eindruck aus den Dokumentationsbeispielen | Echte Nachricht |
Jedes Feld hat | Leere Felder haben gar keinen |
|
|
| Native |
| Auch |
Davon ist die dritte am kritischsten: Früher erzeugte ein str(d["fValue"]) in field_from_dict
bei {"fType":"enum","fValue":true} ein Python-stiliges "True" ——
ein String mit großem T, den der Server nicht erkennt, und die Fehlermeldung verrät nicht, dass es hieran liegt.
Jetzt wird fValue ausnahmslos unverändert durchgereicht.
Der Vorteil: Die Rückgabe von getById kann direkt an saveOrUpdate zurückgegeben werden (ein oder zwei Felder ändern und speichern),
der Roundtrip ist verlustfrei; dieser Weg wird von test_roundtrip_is_lossless abgesichert.
Zusätzlich wurden aus dem bd-Feld der Nachricht acht Stammdaten-formIds extrahiert und in forms.py registriert:
bd_employee, bd_department, bd_customer, bdi_bd_customer_fork,
bdi_projecttypes, bdi_projectarea, bdi_projectstauts, bdi_projectroles.
bdi_projectstautsist kein Tippfehler —— offiziell wurde status als stauts geschrieben, formId und Feldname haben beide diese Schreibweise. Nicht „kurzerhand korrigieren".
Woher die Feldkennungen kommen
Nicht raten. Die maßgebliche Bezugsmethode ist die 星辰-Oberfläche: Belegliste → Mehr → Daten importieren → Vorlagenverwaltung → Neue Vorlage.
Nach dem Start kann man auch rückwärts prüfen: sx_get_form_config(form_id) ruft
operation.getUserconfig auf und liefert die Feldkonfiguration des Belegs.
forms.py registriert 15 formIds: sieben aus der offiziellen Dokumentation
(bdi_projectfile, bdi_ex_loan, bdi_ex_bx, bdi_ex_pay,
bdi_fillinworkinghours, pur_bill_request, bd_auxinfo),
acht aus den Stammdaten-Referenzen in der Referenzcode-Nachricht. Übrige Belege können die formId
direkt an sx_list_query übergeben, ohne vorherige Registrierung.
Gleiches gilt für Feldnamen —— nur die Felder von bdi_projectfile sind anhand der echten Nachricht verifiziert
(beachte: es verwendet status/enable, kein billstatus; das ist ein Feld von Geschäftsbelegen).
Die Standardfelder der übrigen Belege sind weiterhin nach Konvention abgeleitet; nach erfolgreichem Betrieb bitte mit sx_get_form_config verifizieren.
Beziehung zu kingdee-star-mcp
Beide sind zwei offene Fähigkeiten desselben 星辰-Mandanten, jeweils unabhängig bereitgestellt:
kingdee-star-mcp | sanxiao-mcp | |
Gateway |
|
|
Authentifizierung | HMAC-Signatur + app-token, zwei Ebenen von Anmeldedaten | Vier Header, keine Signatur |
Endpunkte |
|
|
Abdeckung | Finanzen (Belege, Erstattungen, Kontokorrent) | Projektmanagement (Projekte, Arbeitszeiten, Budgets, Erstattungen) |
Das Token von Drei-Effekt muss zuerst über die Standard-API von 星辰 bezogen werden —— wenn die Autorisierungskette
bereits in kingdee-star-mcp durchlaufen wurde, können das erhaltene Token sowie domain/groupname/
accountid aus dem Autorisierungs-Push direkt in die .env dieses Projekts eingetragen werden.
Bekannte Lücken
Die offizielle Dokumentation gibt kein einheitliches Rückgabe-Schema vor;
client._unwrap()macht ein lockeres Entpacken: Wennerrcode/success/dataerkannt werden, wird normalisiert, sonst unverändert zurückgegeben —— lieber mehr Daten liefern, als durch falsche Strukturannahmen Daten zu verschlucken. Nach Erhalt echter Rückgaben kann es verschärft werden.Die Belegstatuscodes sind in der Dokumentation nicht vollständig aufgeführt. Im Referenzcode hat die Projektakte
status="A",enable="1", aber was A/B/C jeweils bedeuten und der Wertebereich vonbillstatusbei Geschäftsbelegen ist noch nicht autoritativ geklärt. Derstatus-Parameter der semantischen Ebene gibt derzeit die Rohkennung unverändert weiter.Im Referenzcode widersprechen sich die
fTypeeiniger Felder selbst ——phaseplanenddate,phaseenddatesind alsnumdeklariert, sind aber offensichtlich Daten. Das ist eine Inkonsistenz der Herstellernachricht selbst; die Modellebene übernimmt sie unverändert ohne Korrektur, um nicht „kontraproduktiv zu helfen".Anhangs-Upload erfolgt per base64; bei großen Dateien muss das Gateway-Volumenlimit bewertet werden, die Dokumentation gibt es nicht an.
Available Tools
28 toolssx_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
Scored across 28 tools
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.
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.
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.
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
Related MCP Connectors
Manage Timequip projects, tasks, comments, members, and dashboards through MCP.
One governed MCP endpoint for 40+ business systems. Read-only, source-cited answers.
A paid remote MCP for AI SDK data query MCP, built to return verdicts, receipts, usage logs, and aud
MCP server for Arcoro and ExakTime — workforce data, jobs, cost codes and locations.
Related MCP Servers
- FlicenseAqualityDmaintenanceEnables read-only access to Kingdee Cloud Star financial data, invoice tax calculation, and generation of reimbursement draft payloads through MCP tools.17-
- FlicenseNot gradedqualityDmaintenanceEnables read-only queries of i桂航 campus data, including schedules, classes, terms, and campus information through MCP tools.-
- AlicenseNot gradedqualityBmaintenanceProvides 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
- FlicenseNot gradedqualityAmaintenanceEnables 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.-