kingdee_star —— Servidor MCP de Kingdee Cloud Galaxy

Agente financiero GC032 · lado Kingdee (el lado DingTalk ya está conectado mediante el MCP de DingTalk; este repositorio solo cubre Kingdee). Alineado con el requisito v2.1: Fase 1 solo lectura + cálculo de impuestos de facturas + generación de mensajes pendientes de registro para solicitudes de reembolso.

Cambio importante en v0.2.0: La autenticación, los endpoints y el motor de impuestos se han reescrito según la documentación oficial y las pruebas reales en el sandbox. Las constantes de endpoints de v0.1.0 (como /finance/expense) no existen en la pasarela real; no las reutilice.

Índice

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

Autenticación (dos niveles de credenciales, no los confunda)

Cadena:

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

Tres trampas fáciles de pisar (signer.py ya las maneja; lea los comentarios antes de modificar):

1. hash_hmac(..., raw_output=false) devuelve una cadena hexadecimal; la entrada del base64 es este hex, no el digest crudo.

2. Los nombres de cabecera en la cadena a firmar están en minúsculas, y el nonce va primero, el timestamp después, en orden inverso al declarado en X-Api-SignHeaders; además hay un salto de línea al final.

3. X-GW-Router-Addr (tomado del domain del mensaje push, p. ej. https://tf.jdy.com) es una cabecera obligatoria global; los 370 endpoints de la documentación oficial la marcan todos como obligatoria.

Inicio rápido

pip install -r requirements.txt
cp .env.example .env        # 填入凭据
pytest -q                   # 单测应全绿
python test_connection.py   # 联调：配置→网络→鉴权→只读→dry-run

En Windows, haga doble clic en run_test.bat (el resultado se escribe en connection_test_result.txt).

Uso como servidor MCP

python -m kingdee_star.server        # stdio

Fusione kingdee-star de mcp.config.json en la configuración mcpServers del cliente (cambie cwd y env). Compatible con las versiones principales 1.x y 2.x de mcp.

Lista de herramientas (17)

Las facturas de ventas/salientes y de compras/entrantes no son dos endpoints; se filtran con bill_type / invoice_type de fi/invoice_fp.

⚠ Restricciones reales de escritura de reembolsos

La plataforma abierta oficial tiene 370 endpoints en total; el módulo ebx solo tiene un GET de «detalle de solicitud de reembolso», no hay ni lista de solicitudes de reembolso ni ningún endpoint de guardado de solicitudes de reembolso.

Por lo tanto, el «rellenado automático de borradores de solicitudes de reembolso con facturas» del requisito v2.1 no se puede persistir mediante la API abierta:

• kdy_fill_reimbursement solo produce mensajes pendientes de registro con impuestos ya calculados y validación de cumplimiento superada; dry_run=False se rechaza explícitamente.

• Para escribir automáticamente de verdad, solo queda el canal no-API-abierta (RPA / interfaz frontend / solicitar a Kingdee una interfaz personalizada).

Límites de seguridad

• JDY_READONLY=true → solo lectura pura.

• La capa de guardia es de lista blanca + denegación por defecto: las variaciones de ruta (barra final, subrutas, mayúsculas/minúsculas) no pueden eludirla.

• Pagos/escritura de comprobantes/cuentas, envío de reembolsos a aprobación → prohibidos permanentemente (FORBID_ENDPOINTS), ejecución manual.

• Auditoría completa: registro kingdee_star.audit.

Motor de impuestos

Deducción de transporte de pasajeros sin viajero → la validación de cumplimiento la marca como no deducible. Las facturas con importe negativo (facturas en rojo) se rechazan directamente.