Skip to main content
Glama
sanxiao-mcp
by adambbhe

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

제품 회계세트 레벨 token, Star 표준 API 인증으로 획득

X-GW-Router-Addr

IDC 도메인 = 【실시간 수신 인증】푸시 메시지의 domain 필드

groupname

인증 정보, 오픈 플랫폼이 샌드박스 메시지 수신 주소로 푸시

accountid

동일

함정 주의: 공식 문서에 "클라우드 플랫폼 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.txt

Windows는 run_test.bat을 더블클릭.

MCP 도구 (28개)

메타 정보

도구

용도

sx_health

게이트웨이 주소, 읽기 전용 스위치, 4요소 준비 상태 및 누락 항목

sx_list_forms

등록된 formId, 한글명, 기본 필드

sx_capabilities

사용 가능한 action, 읽기 전용 operation 화이트리스트, 현재 허용된 쓰기 동작

공통 계층 — 공식 인터페이스 전체 매핑

도구

공식 인터페이스

sx_list_query

listQuery

sx_get_by_id

getById

sx_operation

operation(읽기 전용 화이트리스트 제약)

sx_build_query

로컬 도구: 단순 조건을 qParams로 변환, 요청 미전송

의미 계층 — 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계층:

  1. action 분류 — listQuery/getById/operation은 읽기, 나머지 7개는 쓰기.

  2. operationKey 화이트리스트 — operation은 표면상 읽기 인터페이스지만 operationKey 는 자유 문자열이므로, 문서 10.1–10.9의 9개 메서드에 대해 다시 화이트리스트 적용.

  3. 자금류 영구 금지 쓰기 — 지불 문서(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 에 고정되어 있어, 되돌리면 즉시 빨간불:

문서 예시가 주는 인상

실제 메시지

모든 필드에 fValue가 있음

빈 값 필드는 fValue 키가 전체적으로 나타나지 않음, fValue:""가 아님

enum은 반드시 fValueText 필요

status/enable/enablecostamtctl 모두 fValue만 있음

fValue는 모두 문자열

네이티브 true / false / 0이 문자열 "10"과 혼용됨

fValueText는 enum 전용

bd도 포함, 기초자료의 표시명을 저장하는 데 사용

그중 세 번째가 가장 치명적: 이전 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

게이트웨이

api.kingdee.com jdy 게이트웨이

bj1-api.kingdee.com 삼효 게이트웨이

인증

HMAC 서명 + app-token 2계층 자격증명

헤더 4개, 서명 없음

엔드포인트

/jdy/v2/{module}/{object} 수백 개

common/{action} 10개

범위

재무(전표, 지출, 거래처)

프로젝트 관리(프로젝트, 작업시간, 예산, 지출)

삼효의 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 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.
      -