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: mcp-timely

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 / client

Authentifizierung: 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:

Stolperfallen-Hinweis: Die offizielle Dokumentation schreibt ausdrücklich „beim Debuggen im API-Markt der Cloud-Plattform kann X-GW-Router-Addr ignoriert 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.txt

Unter Windows einfach run_test.bat doppelklicken.

MCP-Tools (28)

Metainformationen

Generische Ebene —— vollständige Abbildung der offiziellen Schnittstellen

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:

1. Aktionsklassifizierung —— listQuery/getById/operation sind lesend, die übrigen sieben sind schreibend.

2. operationKey-Whitelist —— operation ist oberflächlich eine Lese-Schnittstelle, aber operationKey ist ein freier String, daher wird für die neun Methoden aus Dokument 10.1–10.9 eine weitere Whitelist angewendet.

3. Finanzklassen dauerhaft schreibgeschützt —— Schreib- und Prozessaktionen für Zahlungsbelege (bdi_ex_pay*), selbst bei SX_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:

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_projectstauts ist 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:

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: Wenn errcode/success/data erkannt 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 von billstatus bei Geschäftsbelegen ist noch nicht autoritativ geklärt. Der status-Parameter der semantischen Ebene gibt derzeit die Rohkennung unverändert weiter.

• Im Referenzcode widersprechen sich die fType einiger Felder selbst —— phaseplanenddate, phaseenddate sind als num deklariert, 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.