kingdee_star —— 金蝶云星辰 MCP Server

GC032 財務智能体・金蝶側（钉钉側は钉钉 MCP で接続済みのため、本リポジトリは金蝶のみを対象とする）。 要件 v2.1 に整合：一期は読み取り専用 + 发票税额計算 + 报销单待录入报文生成。

v0.2.0 の重要変更：鉴权・端点・税额エンジンはすべて公式ドキュメントと沙箱実測に基づき書き直しました。 v0.1.0 の端点定数（/finance/expense など）は実際のゲートウェイには存在しないため、使用しないでください。

目次

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

鉴权（2 層の凭据、混同しないこと）

連鎖：

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

陥りやすい落とし穴が 3 つ（signer.py で処理済み。変更前はコメントを先に確認すること）：

1. hash_hmac(..., raw_output=false) は hex 文字列を返す。base64 の入力はこの hex であり、raw digest ではない。

2. 署名対象文字列内のヘッダー名は小文字で、nonce が先、timestamp が後。X-Api-SignHeaders で宣言された順序とは逆。末尾に改行が 1 つある。

3. X-GW-Router-Addr（推送报文内の domain を取得、例：https://tf.jdy.com）はグローバル必須ヘッダー。公式ドキュメントの 370 個の接口すべてに必須と記載されている。

クイックスタート

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

Windows は run_test.bat をダブルクリックするだけ（結果は connection_test_result.txt に書き込まれる）。

MCP Server として使用

python -m kingdee_star.server        # stdio

mcp.config.json 内の kingdee-star をクライアントの mcpServers 設定にマージする（cwd と env を変更）。 mcp 1.x と 2.x の両メジャーバージョンに対応。

ツール一覧（17）

销项/进项发票は 2 つの端点ではなく、fi/invoice_fp の bill_type / invoice_type でフィルタリングする。

⚠ 报销書き込みの現実的制約

公式オープンプラットフォームには合計 370 個の接口があるが、ebx モジュールには「报销单詳細」という GET が 1 つしかない。 报销单リストも、报销单保存接口も存在しない。

そのため、要件 v2.1 の「发票自動入力による报销单下書き」はオープン API ではデータベースに書き込めない：

• kdy_fill_reimbursement は税额計算済み・コンプライアンス検証済みの待录入报文のみを生成し、 dry_run=False は明示的に拒否される。

• 実際に自動書き込むには、非オープン API チャネル（RPA / フロントエンド接口 / 金蝶へのカスタム接口依頼）しかない。

セキュリティ境界

• JDY_READONLY=true → 完全読み取り専用。

• ガード層はホワイトリスト + デフォルト拒否：パス変形（末尾スラッシュ、サブパス、大文字小文字）では迂回できない。

• 支払い/伝票/科目の書き込み、报销の提出・承認 → 恒久禁止（FORBID_ENDPOINTS）、手動で実行。

• 全量監査：kingdee_star.audit ログ。

税额エンジン

旅客輸送控除で搭乗者情報が欠落 → コンプライアンス検証で控除不可に設定。マイナス（赤字）发票は直接拒否。