kingdee_star — Kingdee Cloud Star MCP Server

GC032 Financial Agent · Kingdee side (the DingTalk side is already connected via DingTalk MCP; this repo only handles Kingdee). Aligned with requirement v2.1: Phase 1 read-only + invoice tax calculation + reimbursement form pending-entry message generation.

v0.2.0 Important changes: Authentication, endpoints, and the tax engine have all been rewritten per the official docs and sandbox testing. The endpoint constants from v0.1.0 (like /finance/expense) do not exist on the real gateway; do not reuse them.

Table of Contents

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

Authentication (two layers of credentials, don't mix them up)

Flow:

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

Three easy pitfalls (already handled in signer.py; read the comments before changing anything):

1. hash_hmac(..., raw_output=false) returns a hex string; the base64 input is this hex, not the raw digest.

2. Header names in the string to sign are lowercase, and nonce comes first, timestamp last — the reverse of the order declared in X-Api-SignHeaders; there is also a trailing newline.

3. X-GW-Router-Addr (taken from the domain in the push message, e.g. https://tf.jdy.com) is a globally required header; all 370 endpoints in the official docs mark it as required.

Quick Start

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

On Windows, just double-click run_test.bat (results are written to connection_test_result.txt).

Using as an MCP Server

python -m kingdee_star.server        # stdio

Merge kingdee-star from mcp.config.json into the client's mcpServers config (adjust cwd and env). Compatible with both mcp 1.x and 2.x major versions.

Tool List (17)

Sales/output and purchase/input invoices are not two separate endpoints; filter via bill_type / invoice_type on fi/invoice_fp.

⚠ Real-world constraints on reimbursement writes

The official open platform has 370 endpoints in total; the ebx module has only one GET — "reimbursement detail", with neither a reimbursement list nor any reimbursement save endpoint.

Therefore, the "auto-fill reimbursement draft from invoice" in requirement v2.1 cannot be persisted via the open API:

• kdy_fill_reimbursement only produces pending-entry messages with tax already computed and compliance checks passed, dry_run=False is explicitly rejected.

• To actually write automatically, you can only go through non-open-API channels (RPA / frontend APIs / asking Kingdee for a custom endpoint).

Security Boundary

• JDY_READONLY=true → pure read-only.

• The guard layer is whitelist + deny by default: path variations (trailing slashes, sub-paths, case changes) cannot bypass it.

• Payment/voucher/account writes and reimbursement submission for approval → permanently forbidden (FORBID_ENDPOINTS), executed manually.

• Full audit: kingdee_star.audit log.

Tax Engine

Passenger transport deduction missing the traveler → compliance check marks it as non-deductible. Negative (red-letter) invoices are rejected outright.