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: mcp-timely

목차

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에서 사전에 획득함:

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

메타 정보

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

의미 계층 — 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 에 고정되어 있어, 되돌리면 즉시 빨간불:

그중 세 번째가 가장 치명적: 이전 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 회계세트의 두 가지 오픈 기능이며, 각각 독립 배포:

삼효의 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, 대용량 파일은 게이트웨이 용량 상한 평가 필요, 문서에 명시되지 않음.