sanxiao-mcp —— Servidor MCP de «Gestión de Proyectos de Tres Efectos» de Kingdee Cloud·Star

Agente financiero GC032 · extremo de Tres Efectos. Identificador de aplicación bdi_projectmanagement, dirección de suscripción https://cloud.kingdee.com/kae/#/market/detail?sid=1285.

Implementado según el documento oficial «API de Gestión de Proyectos de Tres Efectos API_2025» + «Marco de desarrollo de la API de Gestión de Proyectos de Tres Efectos de Kingdee». Fase uno solo lectura: todas las consultas habilitadas, el código de escritura está en su sitio pero bloqueado por defecto por el guardián.

La forma de la API de Tres Efectos (entiende esto primero, el resto es fácil)

Tres Efectos no es «un negocio, un endpoint», sino CRUD de documentos genéricos (Bill): todos los documentos — archivo de proyecto, préstamos, reembolsos, pagos, registro de horas de trabajo, solicitudes de compra — pasan por el mismo conjunto de interfaces, impulsados por formId + identificadores de campo.

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 }

Por eso la estructura de este servicio también es «una salida + dos capas de encapsulación», en lugar de decenas de constantes de endpoints.

Related MCP server: mcp-timely

Índice

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

Autenticación: cuatro cabeceras, sin firma

A diferencia de kingdee-star-mcp (puerta de enlace abierta de jdy) — no igual — Tres Efectos no requiere firma HMAC, solo hay que llevar cuatro cabeceras, todas obtenidas previamente mediante la API estándar de Cloud Star:

Aviso de trampa: la documentación oficial indica explícitamente que «al depurar en el mercado de API de la plataforma en la nube se puede ignorar X-GW-Router-Addr». Por eso muchos lo prueban en el mercado y funciona, pero al pasar al código da 404 — porque la llamada desde código debe llevar esta cabecera. config.headers() ya lo gestiona, no lo borres.

Una vez obtenidos los cuatro elementos, rellena .env (plantilla en .env.example).

Inicio rápido

pip install -r requirements.txt
cp .env.example .env        # 填入四要素
pytest -q                   # 69 项单测应全绿
python test_connection.py   # 分层联调，结果写入 connection_test_result.txt

En Windows, haz doble clic en run_test.bat.

Herramientas MCP (28)

Capa de metainformación

Capa genérica — mapeo completo de las interfaces oficiales

Capa semántica — no hace falta memorizar 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

Capa de escritura — rechazada por defecto

sx_build_bill_payload (solo ensambla, no envía; en la fase uno también sirve para que una persona revise el mensaje) sx_save_or_update / sx_submit / sx_un_submit / sx_audit / sx_un_audit / sx_delete / sx_push

Cómo escribir las condiciones de consulta

El qParams oficial es un array de condiciones: los elementos de nivel superior se combinan con and, dentro de un grupo de condiciones se conectan mediante 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')

Operadores de comparación: = > >= < <= != like likeLeft. No hay in — se simula con query.any_of() o con el grupo or de sx_build_query. Los campos de detalle se escriben como «identificador de detalle.identificador de campo», por ejemplo projectfileteam.teamstaff.

Modelo de seguridad

El guardián es de lista blanca + rechazo por defecto en tres capas:

1. Clasificación de acciones — listQuery/getById/operation son lectura, los otros siete son escritura.

2. Lista blanca de operationKey — operation en apariencia es una interfaz de lectura, pero operationKey es una cadena libre, así que se aplica una segunda lista blanca a los nueve métodos de las secciones 10.1–10.9 del documento.

3. Prohibición permanente de escritura en clases financieras — las escrituras y acciones de flujo del documento de pago (bdi_ex_pay*), incluso con SX_ALLOW_WRITE_ACTIONS=*, se bloquean.

Orden para abrir escritura en la fase dos: SX_READONLY=false → añadir acciones una a una en SX_ALLOW_WRITE_ACTIONS para hacer despliegue gradual. No pasar directamente a *.

Todas las llamadas e interceptaciones se registran en el logger sanxiao.audit.

Los mensajes reales desmienten la impresión que da la documentación

El «Código de referencia de la API de Tres Efectos» que la empresa proporciona por separado es un mensaje completo del documento bdi_projectfile (guardado como tests/fixtures/projectfile_reference.json). Es más fiable que los ejemplos de la documentación, y desmiente cuatro suposiciones que parecían obvias — cada una está fijada en tests/test_reference_payload.py, y cualquier cambio que las revierta fallará de inmediato:

La tercera es la más problemática: antes, en field_from_dict, una línea str(d["fValue"]), al encontrarse con {"fType":"enum","fValue":true} producía un "True" de estilo Python — una cadena con T mayúscula que el servidor no reconoce, y el mensaje de error no te dice que el problema está ahí. Ahora fValue se transmite tal cual, sin transformación.

La ventaja es que la respuesta de getById se puede alimentar directamente a saveOrUpdate (cambiar uno o dos campos y guardar), la ida y vuelta es sin pérdidas, y este camino está protegido por test_roundtrip_is_lossless.

Además, del campo bd del mensaje se han extraído ocho formId de datos maestros, registrados en forms.py: bd_employee, bd_department, bd_customer, bdi_bd_customer_fork, bdi_projecttypes, bdi_projectarea, bdi_projectstauts, bdi_projectroles.

bdi_projectstauts no es un error tipográfico — la empresa escribió status como stauts, y tanto el formId como el nombre del campo usan esa grafía. No lo «corrijas de paso».

De dónde salen los identificadores de campo

No adivines. La forma autoritativa es la interfaz de Star: Lista de documentos → Más → Importar datos → Gestión de plantillas → Nueva plantilla.

Una vez en marcha también se puede consultar a la inversa: sx_get_form_config(form_id) llama a operation.getUserconfig y devuelve la configuración de campos de ese documento.

forms.py registra 15 formId: siete proceden de la documentación oficial (bdi_projectfile, bdi_ex_loan, bdi_ex_bx, bdi_ex_pay, bdi_fillinworkinghours, pur_bill_request, bd_auxinfo), y ocho de las referencias a datos maestros en el mensaje del código de referencia. Para el resto de documentos basta con pasar el formId directamente a sx_list_query, sin necesidad de registrarlo antes.

Lo mismo con los nombres de campo — solo los campos de bdi_projectfile están verificados contra el mensaje real (observa que usa status/enable, no billstatus; ese es un campo de los documentos de negocio). Los campos por defecto del resto de documentos siguen siendo una inferencia por convención; una vez que funcione, verifícalos con sx_get_form_config.

Relación con kingdee-star-mcp

Ambos son dos capacidades abiertas de la misma cuenta de Star, desplegadas de forma independiente:

El Token de Tres Efectos debe obtenerse primero mediante la API estándar de Star — si ya has completado el flujo de autorización en kingdee-star-mcp, puedes rellenar directamente el token obtenido y el domain/groupname/ accountid del push de autorización en el .env de este proyecto.

Huecos conocidos

• La documentación oficial no proporciona un esquema unificado del cuerpo de respuesta; client._unwrap() hace un desempaquetado laxo: si reconoce errcode/success/data, normaliza; si no los reconoce, devuelve tal cual — mejor dar más datos que tragarse datos por adivinar mal la estructura. Una vez que tengas respuestas reales, se puede ajustar.

• Los códigos de estado de los documentos no están completos en la documentación. En el código de referencia, el archivo de proyecto tiene status="A", enable="1", pero qué significan A/B/C y el dominio de valores de billstatus en los documentos de negocio aún no tienen una explicación autoritativa. El parámetro status de la capa semántica transmite actualmente el identificador original tal cual.

• En el código de referencia hay varios campos cuyo fType es contradictorio — phaseplanenddate, phaseenddate se declaran como num pero claramente son fechas. Es una inconsistencia del propio mensaje del proveedor; la capa de modelo los acepta tal cual sin corregirlos, para no «echar una mano que estorba».

• La subida de adjuntos va en base64; para archivos grandes hay que evaluar el límite de volumen de la puerta de enlace, la documentación no lo especifica.