Skip to main content
Glama
sanxiao-mcp
by adambbhe

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

Header

Bezugsquelle

Token

Token auf Produkt-Mandantenebene, über die Standard-API-Authentifizierung von 星辰 bezogen

X-GW-Router-Addr

IDC-Domain = domain-Feld in der Push-Nachricht von 【Echtzeit-Empfangsautorisierung】

groupname

Autorisierungsinformation, von der offenen Plattform an die Sandbox-Nachrichtenempfangsadresse gepusht

accountid

Ebenso

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

Tool

Zweck

sx_health

Gateway-Adresse, Nur-Lese-Schalter, Bereitschaftsstatus der vier Elemente und fehlende Einträge

sx_list_forms

Registrierte formIds, chinesische Namen, Standardfelder

sx_capabilities

Verfügbare Aktionen, Nur-Lese-Operations-Whitelist, aktuell freigegebene Schreibaktionen

Generische Ebene —— vollständige Abbildung der offiziellen Schnittstellen

Tool

Offizielle Schnittstelle

sx_list_query

listQuery

sx_get_by_id

getById

sx_operation

operation (durch Nur-Lese-Whitelist eingeschränkt)

sx_build_query

Lokales Tool: übersetzt vereinfachte Bedingungen in qParams, sendet keine Anfrage

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:

Eindruck aus den Dokumentationsbeispielen

Echte Nachricht

Jedes Feld hat fValue

Leere Felder haben gar keinen fValue-Schlüssel, nicht fValue:""

enum muss mit fValueText kombiniert werden

status/enable/enablecostamtctl haben nur fValue

fValue ist immer ein String

Native true / false / 0 kommen vor, gemischt mit dem String "10"

fValueText ist nur für enum

Auch bd trägt es, für den Anzeigenamen der Stammdaten

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:

kingdee-star-mcp

sanxiao-mcp

Gateway

api.kingdee.com jdy-Gateway

bj1-api.kingdee.com Drei-Effekt-Gateway

Authentifizierung

HMAC-Signatur + app-token, zwei Ebenen von Anmeldedaten

Vier Header, keine Signatur

Endpunkte

/jdy/v2/{module}/{object}, hunderte

common/{action}, zehn

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

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.
      -