kingdee_star —— 킹디 클라우드 스타 MCP 서버

GC032 재무 에이전트 · 킹디 측(딩톡 측은 딩톡 MCP로 이미 연동됨, 본 리포지토리는 킹디만 다룸). 요구사항 v2.1 정렬: 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에 선언된 순서와 반대이며, 끝에 개행 문자가 하나 더 있음.

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 서버로 사용

python -m kingdee_star.server        # stdio

mcp.config.json의 kingdee-star를 클라이언트 mcpServers 설정에 병합(cwd와 env 수정). mcp 1.x 및 2.x 두 메이저 버전 모두 호환.

도구 목록(17)

매출/매입 세금 계산서는 두 개의 엔드포인트가 아니라 fi/invoice_fp의 bill_type / invoice_type으로 필터링.

⚠ 지출 입력의 현실적 제약

공식 오픈 플랫폼에는 총 370개 인터페이스가 있으며, ebx 모듈에는 「지출 상세」 GET 하나만 존재하고, 지출 목록도, 지출 저장 인터페이스도 없음.

따라서 요구사항 v2.1의 「세금 계산서 자동 입력 지출 초안」은 오픈 API로는 DB에 저장할 수 없음:

• kdy_fill_reimbursement는 세액 계산 완료, 규정 준수 검증 통과한 입력 대기 전문만 생성하며, dry_run=False는 명시적으로 거부됨.

• 실제 자동 입력을 하려면 비공개 API 채널(RPA / 프론트엔드 인터페이스 / 킹디에 맞춤 인터페이스 요청)만 가능.

보안 경계

• JDY_READONLY=true → 순수 읽기 전용.

• 가드 계층은 화이트리스트 + 기본 거부: 경로 변형(끝 슬래시, 하위 경로, 대소문자) 모두 우회 불가.

• 지급/전표/계정과목 입력, 지출 제출 승인 → 영구 금지(FORBID_ENDPOINTS), 수동 실행.

• 전체 감사: kingdee_star.audit 로그.

세액 엔진

여객 운송 공제에 탑승자 정보 누락 → 규정 준수 검증에서 공제 불가 처리. 음수(적자) 세금 계산서는 직접 거부.