sanxiao-mcp
sanxiao-mcp —— Kingdee Cloud·星辰「삼효 프로젝트 관리」MCP Server
GC032 재무 에이전트 · 삼효 엔드. 애플리케이션 식별자 bdi_projectmanagement,
구독 주소 https://cloud.kingdee.com/kae/#/market/detail?sid=1285.
《삼효 프로젝트 관리 API_2025》공식 문서 + 《Kingdee 삼효 프로젝트 관리 API 개발 프레임워크》에 따라 구현. 1기 읽기 전용: 조회류 전체 허용, 쓰기류 코드는 구현되어 있으나 기본적으로 가드에 의해 거부됨.
삼효 API의 형태 (이것을 먼저 이해하면 나머지는 쉽다)
삼효는 "업무 하나에 엔드포인트 하나"가 아니라 공통 문서(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 }따라서 본 서비스의 구조도 "하나의 출구 + 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개의 헤더만携带하면 되고, 모두 Cloud Star 표준 API에서 사전에 획득함:
헤더 | 값 출처 |
| 제품 회계세트 레벨 token, Star 표준 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(조립만 하고 전송하지 않음, 1기에도 사람이 메시지를 대조하는 데 사용 가능)
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=*여도 차단.
2기 쓰기 활성화 순서: SX_READONLY=false → SX_ALLOW_WRITE_ACTIONS
에 동작을 하나씩 추가하며 그레이스케일. 한 번에 *로 가지 말 것.
모든 호출과 차단은 sanxiao.audit logger에 기록됨.
실제 메시지가 문서의 인상을 뒤집음
공식에서 별도로 제공한 《삼효-API 참조 코드》는 완전한 bdi_projectfile 문서 메시지
(tests/fixtures/projectfile_reference.json에 저장됨). 문서 예시보다 신뢰할 수 있으며,
네 가지 당연한 가정을 뒤집음 — 각각 tests/test_reference_payload.py
에 고정되어 있어, 되돌리면 즉시 빨간불:
문서 예시가 주는 인상 | 실제 메시지 |
모든 필드에 | 빈 값 필드는 |
|
|
| 네이티브 |
|
|
그중 세 번째가 가장 치명적: 이전 field_from_dict의 str(d["fValue"]) 한 줄이
{"fType":"enum","fValue":true}를 만나면 Python 스타일의 "True"를 생성 —
대문자 T 문자열, 서버가 인식하지 못하며, 오류 메시지도 이 문제라고 알려주지 않음.
이제 fValue는 항상 원본 그대로 투과.
장점은 getById의 반환값을 saveOrUpdate에 직접 넣을 수 있다는 것(필드 하나둘 수정 후 저장),
왕복 무손실, 이 경로는 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와 필드명 모두 이 표기. "편의상 수정"하지 말 것.
필드 식별자 출처
추측하지 말 것. 권위 있는 획득 방법은 Star 화면: 문서 목록 → 더보기 → 데이터 가져오기 → 템플릿 관리 → 새 템플릿.
실행 후에도 역조회 가능: 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와의 관계
둘은 동일한 Star 회계세트의 두 가지 오픈 기능이며, 각각 독립 배포:
kingdee-star-mcp | sanxiao-mcp | |
게이트웨이 |
|
|
인증 | HMAC 서명 + app-token 2계층 자격증명 | 헤더 4개, 서명 없음 |
엔드포인트 |
|
|
범위 | 재무(전표, 지출, 거래처) | 프로젝트 관리(프로젝트, 작업시간, 예산, 지출) |
삼효의 Token은 먼저 Star 표준 API를 통해 획득해야 함 — 이미 kingdee-star-mcp
에서 인증 체인을 통과했다면, 획득한 token과 인증 푸시의 domain/groupname/
accountid를 본 프로젝트의 .env에 직접 입력하면 됨.
알려진 미해결 사항
공식 문서가 통일된 응답체 스키마를 제공하지 않아,
client._unwrap()은 관대한 언랩:errcode/success/data를 인식하면 정규화, 인식하지 못하면 원본 반환 — 데이터를 더 주는 쪽을 선택, 구조를 잘못 추측하여 데이터를 삼키지 않음. 실제 응답을 확보한 후 tighten 가능.문서 상태 코드가 문서에 완전히 나열되지 않음. 참조 코드에서 프로젝트 마스터
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.-