sanxiao-mcp
sanxiao-mcp —— 金蝶云・星辰「三效プロジェクト管理」MCP Server
GC032 財務エージェント・三效端。アプリ識別子 bdi_projectmanagement、
購読アドレス https://cloud.kingdee.com/kae/#/market/detail?sid=1285。
『三效プロジェクト管理 API_2025』公式ドキュメント + 『金蝶三效プロジェクト管理API開発フレームワーク』に基づいて実装。 一期は読み取り専用:クエリ系は全開放、書き込み系はコードは配置済みだがデフォルトでガードにより拒否される。
三效 API の形状(これを先に理解すれば、他はすべてうまくいく)
三效は「1ビジネス1エンドポイント」ではなく、汎用伝票(Bill)CRUD:
すべての伝票 —— プロジェクトマスタ、借入、経費精算、支払、工数入力、購買申請 —— は同じ一連のインターフェースを経由し、
formId + フィールド識別子で駆動される。
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 }したがって、本サービスの構造も「1つの出口 + 2層のカプセル化」であり、数十のエンドポイント定数ではない。
Related MCP server: iGuat-MCP
目次
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認証:4つのリクエストヘッダ、署名なし
kingdee-star-mcp(jdy オープンゲートウェイ)とは異なる —— 三效は HMAC 署名を必要とせず、
4つのヘッダを携帯するだけでよい。すべて雲星辰標準 API で事前に取得する:
ヘッダ | 取得元 |
| 製品帳票レベルのトークン。星辰標準 API 認証で取得 |
| IDC ドメイン = 【リアルタイム受信認可】プッシュメッセージ内の |
| 認可情報。オープンプラットフォームがサンドボックスメッセージ受信アドレスにプッシュ |
| 同上 |
落とし穴のヒント:公式ドキュメントには「雲プラットフォーム API マーケットでデバッグする際は
X-GW-Router-Addrを無視してよい」と明記されている。そのため多くの人がマーケットで疎通確認できても、コードにすると 404 になる —— コード呼び出しでは必ずこのヘッダを付ける必要があるからだ。config.headers()で処理済みなので、削除しないこと。
4要素を取得したら .env に記入する(テンプレートは .env.example 参照)。
クイックスタート
pip install -r requirements.txt
cp .env.example .env # 填入四要素
pytest -q # 69 项单测应全绿
python test_connection.py # 分层联调,结果写入 connection_test_result.txtWindows は run_test.bat をダブルクリックするだけ。
MCP ツール(28個)
メタ情報
ツール | 用途 |
| ゲートウェイアドレス、読み取り専用スイッチ、4要素の準備状態と欠落項目 |
| 登録済みの formId、中国語名、デフォルトフィールド |
| 利用可能な action、読み取り専用 operation ホワイトリスト、現在許可されている書き込みアクション |
汎用層 —— 公式インターフェースを完全マッピング
ツール | 公式インターフェース |
|
|
|
|
|
|
| ローカルツール:簡略化条件を |
セマンティック層 —— formId を覚える必要はない
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
書き込み層 —— デフォルトで拒否
sx_build_bill_payload(組み立てるだけで送信しない。一期でも人手によるメッセージ確認に使える)
sx_save_or_update / sx_submit / sx_un_submit / sx_audit / sx_un_audit
/ sx_delete / sx_push
クエリ条件の書き方
公式 qParams は条件配列:最上位の各項目間は and、条件グループ内は joinKey で接続される。
[
{ "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')比較演算子:= > >= < <= != like likeLeft。in はない —— query.any_of()
または sx_build_query の or グループで代替する。明細フィールドは「明細識別子.フィールド識別子」と書く。
例:projectfileteam.teamstaff。
セキュリティモデル
ガードはホワイトリスト + デフォルト拒否の3層:
action 分類 ——
listQuery/getById/operationは読み取り、残りの7つは書き込み。operationKey ホワイトリスト ——
operationは表面的には読み取りインターフェースだが、operationKeyは自由文字列なので、ドキュメント 10.1–10.9 の9メソッドに対して再度ホワイトリストを適用。資金系は永久書き込み禁止 —— 支払伝票(
bdi_ex_pay*)の書き込みとフローアクションは、SX_ALLOW_WRITE_ACTIONS=*でもブロックされる。
二期で書き込みを開放する順序:SX_READONLY=false → SX_ALLOW_WRITE_ACTIONS
にアクションを1つずつ追加してグレイリリースする。一気に * にしないこと。
すべての呼び出しとブロックは sanxiao.audit logger に出力される。
実際のメッセージがドキュメントの印象を覆した
公式が別途提供する『三效-API参考コード』は完全な bdi_projectfile 伝票メッセージ
(tests/fixtures/projectfile_reference.json として保存済み)。これはドキュメントの例より信頼でき、
4つの思い込みを覆した —— それぞれ tests/test_reference_payload.py で固定されており、
元に戻すと即座にテストが失敗する:
ドキュメント例が与える印象 | 実際のメッセージ |
すべてのフィールドに | 空値フィールドはキー自体が存在しない |
|
|
| ネイティブの |
|
|
その中の3番目が最も致命的:以前の field_from_dict 内の str(d["fValue"]) が、
{"fType":"enum","fValue":true} に遭遇すると Python スタイルの "True" を生成する ——
大文字 T の文字列で、サーバーは認識できず、エラーメッセージもこの問題を教えてくれない。
現在は fValue を常にそのまま透過させる。
利点として、getById の戻り値をそのまま saveOrUpdate に渡せる(1、2フィールド変更して保存)、
往復で損失がなく、この経路は test_roundtrip_is_lossless で保護されている。
さらに、メッセージの bd フィールドから8つの基本資料 formId を抽出し、forms.py に登録済み:
bd_employee、bd_department、bd_customer、bdi_bd_customer_fork、
bdi_projecttypes、bdi_projectarea、bdi_projectstauts、bdi_projectroles。
bdi_projectstautsは誤字ではない —— 公式が status を stauts と綴っており、 formId とフィールド名は両方この綴り。勝手に「修正」しないこと。
フィールド識別子の入手元
推測するな。 権威ある取得方法は星辰の画面: 伝票リスト → その他 → データインポート → テンプレート管理 → 新規テンプレート。
起動後は逆引きも可能:sx_get_form_config(form_id) で
operation.getUserconfig を呼び、その伝票のフィールド設定を返す。
forms.py には15個の formId を登録:7つは公式ドキュメント由来
(bdi_projectfile、bdi_ex_loan、bdi_ex_bx、bdi_ex_pay、
bdi_fillinworkinghours、pur_bill_request、bd_auxinfo)、
8つは参考コードのメッセージ内の基本資料参照由来。その他の伝票は formId
を直接 sx_list_query に渡せばよく、事前登録は不要。
フィールド名も同様 —— bdi_projectfile のフィールドのみ実際のメッセージで検証済み
(status/enable を使用し、billstatus はないことに注意。それは業務伝票のフィールド)。
その他の伝票のデフォルトフィールドは慣例に基づく推測のままなので、疎通後は sx_get_form_config で検証すること。
kingdee-star-mcp との関係
両者は同じ星辰帳票の2つのオープン能力であり、それぞれ独立してデプロイされる:
kingdee-star-mcp | sanxiao-mcp | |
ゲートウェイ |
|
|
認証 | HMAC 署名 + app-token 2層の資格情報 | 4ヘッダ、署名なし |
エンドポイント |
|
|
カバレッジ | 財務(伝票、経費精算、往来) | プロジェクト管理(プロジェクト、工数、予算、経費精算) |
三效の Token は星辰標準 API で事前に取得する必要がある —— すでに kingdee-star-mcp
で認証チェーンを疎通しているなら、取得したトークンと認可プッシュ内の domain/groupname/
accountid をそのまま本プロジェクトの .env に記入できる。
既知の未対応事項
公式ドキュメントは統一されたレスポンスボディスキーマを提供しておらず、
client._unwrap()は緩いアンラップを行う:errcode/success/dataを認識できれば正規化し、認識できなければそのまま返す —— データを多めに渡す方を選び、 構造を誤推測してデータを飲み込まない。実際のレスポンスを取得したら厳密化できる。伝票ステータスコードはドキュメントに完全には記載されていない。参考コードではプロジェクトマスタ
status="A"、enable="1"だが、 A/B/C がそれぞれ何を意味するか、業務伝票のbillstatusの値域は、まだ権威ある説明がない。 セマンティック層のstatusパラメータは現在、元の識別子をそのまま透過する。参考コードには
fTypeが自己矛盾しているフィールドがいくつかある ——phaseplanenddate、phaseenddateはnumと宣言されているが明らかに日付。これはベンダーメッセージ自体の不整合であり、 モデル層はそのまま受け入れ、修正しない —— 「余計な手助け」をしないため。添付ファイルのアップロードは base64 で行われ、大容量ファイルはゲートウェイのサイズ上限を評価する必要があるが、ドキュメントには記載がない。
Available Tools
28 toolssx_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
Scored across 28 tools
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.
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.
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.
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
Related MCP Connectors
Manage Timequip projects, tasks, comments, members, and dashboards through MCP.
One governed MCP endpoint for 40+ business systems. Read-only, source-cited answers.
A paid remote MCP for AI SDK data query MCP, built to return verdicts, receipts, usage logs, and aud
MCP server for Arcoro and ExakTime — workforce data, jobs, cost codes and locations.
Related MCP Servers
- FlicenseAqualityDmaintenanceEnables read-only access to Kingdee Cloud Star financial data, invoice tax calculation, and generation of reimbursement draft payloads through MCP tools.17-
- FlicenseNot gradedqualityDmaintenanceEnables read-only queries of i桂航 campus data, including schedules, classes, terms, and campus information through MCP tools.-
- AlicenseNot gradedqualityBmaintenanceProvides 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
- FlicenseNot gradedqualityAmaintenanceEnables 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.-