kingdee_star —— Kingdee Cloud MCP Server

GC032 Finanz-Agent · Kingdee-Seite (die DingTalk-Seite ist bereits über DingTalk MCP angebunden, dieses Repository macht nur Kingdee). Abgestimmt auf Anforderung v2.1: Phase 1 nur lesend + Rechnungssteuerberechnung + Erzeugung von Meldungen für noch zu erfassende Spesenabrechnungen.

Wichtige Änderung in v0.2.0: Authentifizierung, Endpunkte und Steuer-Engine wurden gemäß offizieller Dokumentation und Sandbox-Tests neu geschrieben. Die Endpunkt-Konstanten aus v0.1.0 (wie /finance/expense) existieren auf dem echten Gateway nicht, bitte nicht weiterverwenden.

Inhaltsverzeichnis

kingdee_star/
├── kingdee_star/
│   ├── config.py        # 环境/凭据（两层：ISV + 租户），只读/写开关
│   ├── signer.py        # jdy 网关签名（X-Api-Signature / app_signature）
│   ├── models.py        # Invoice / ExpenseDraft / ExpenseLine
│   ├── tax_engine.py    # 发票税额决策树（专票/铁路/航空/旅客运输/公路水路/其他）
│   ├── guards.py        # 只读守卫 + 受控写入守卫（白名单+默认拒绝）+ 审计
│   └── star_client.py   # 鉴权 + 只读查询 + 报销报文生成
├── test_connection.py   # 分层联调测试（配置→网络→鉴权→只读→dry-run）
├── run_test.bat         # Windows 一键跑：装依赖 + 单测 + 联调
├── tests/               # pytest：税额引擎 + 签名算法
└── .env.example         # 配置模板

Related MCP server: QuickBooks Online MCP Server

Authentifizierung (zwei Ebenen von Anmeldedaten, nicht verwechseln)

Kette:

POST /jdyconnector/app_management/push_app_authorize?outerInstanceId=...
     → data[0].appKey / appSecret
GET  /jdyconnector/app_management/kingdee_auth_token?app_key=..&app_signature=..
     → data['app-token']（有效期约 2h）
GET  /jdy/v2/{module}/{object}
     → 头带 app-token + X-Api-* 签名 + X-GW-Router-Addr

Drei häufige Stolperfallen (in signer.py bereits behandelt, vor Änderungen zuerst die Kommentare lesen):

1. hash_hmac(..., raw_output=false) liefert einen Hex-String zurück, die Base64-Eingabe ist dieser Hex-String, nicht der rohe Digest.

2. Die Header-Namen in der zu signierenden Zeichenkette sind kleingeschrieben, und die nonce steht vorne, der timestamp hinten – entgegengesetzt zur Reihenfolge, die in X-Api-SignHeaders deklariert ist; am Ende steht zusätzlich ein Zeilenumbruch.

3. X-GW-Router-Addr (aus dem domain-Feld der Push-Meldung, z. B. https://tf.jdy.com) ist ein global verpflichtender Header – in der offiziellen Dokumentation sind alle 370 Schnittstellen als Pflichtfeld markiert.

Schnellstart

pip install -r requirements.txt
cp .env.example .env        # 填入凭据
pytest -q                   # 单测应全绿
python test_connection.py   # 联调：配置→网络→鉴权→只读→dry-run

Unter Windows einfach run_test.bat doppelklicken (Ergebnis wird in connection_test_result.txt geschrieben).

Verwendung als MCP Server

python -m kingdee_star.server        # stdio

kingdee-star aus mcp.config.json in die mcpServers-Konfiguration des Clients übernehmen (cwd und env anpassen). Kompatibel mit den beiden Hauptversionen mcp 1.x und 2.x.

Werkzeugliste (17)

Ausgangs-/Eingangsrechnungen sind nicht zwei Endpunkte, sondern werden über bill_type / invoice_type von fi/invoice_fp gefiltert.

⚠ Realistische Einschränkungen beim Schreiben von Spesenabrechnungen

Die offizielle offene Plattform umfasst insgesamt 370 Schnittstellen, das ebx-Modul hat nur ein einziges GET für „Spesenabrechnungsdetails", es gibt weder eine Spesenabrechnungsliste noch irgendeine Schnittstelle zum Speichern von Spesenabrechnungen.

Daher kann das „automatische Ausfüllen von Spesenabrechnungsentwürfen mit Rechnungen" aus Anforderung v2.1 nicht über die offene API in der Datenbank gespeichert werden:

• kdy_fill_reimbursement erzeugt nur Meldungen mit bereits berechneter Steuer und bestandener Compliance-Prüfung, dry_run=False wird explizit abgelehnt.

• Für eine echte automatische Übernahme bleibt nur der Weg über nicht-offene API-Kanäle (RPA / Frontend-Schnittstellen / bei Kingdee eine kundenspezifische Schnittstelle anfragen).

Sicherheitsgrenzen

• JDY_READONLY=true → rein lesend.

• Die Schutzschicht ist Whitelist + Standard-Ablehnung: Pfadmanipulationen (nachgestellter Schrägstrich, Unterpfade, Groß-/Kleinschreibung) können nicht umgangen werden.

• Zahlungen/Belege/Konten schreiben, Spesenabrechnungen zur Genehmigung einreichen → dauerhaft verboten (FORBID_ENDPOINTS), nur manuell auszuführen.

• Vollständige Prüfung: kingdee_star.audit-Log.

Steuer-Engine

Fehlt bei der Personenbeförderung die reisende Person → Compliance-Prüfung setzt auf nicht abzugsfähig. Negative (rote) Rechnungen werden direkt abgelehnt.