sanxiao-mcp — MCP-сервер «Управление проектами по трём эффектам» Kingdee Cloud·Xingchen

GC032 Финансовый агент · модуль «Три эффекта». Идентификатор приложения bdi_projectmanagement, адрес подписки https://cloud.kingdee.com/kae/#/market/detail?sid=1285.

Реализовано на основе официальной документации «API управления проектами по трём эффектам_2025» + «Фреймворк разработки API управления проектами по трём эффектам Kingdee». Первая фаза — только чтение: все запросы открыты, код записи готов, но по умолчанию отклоняется защитой.

Форма API «Трёх эффектов» (сначала поймите это, остальное просто)

«Три эффекта» — это не «один бизнес — одна конечная точка», а универсальный CRUD для документов (Bill): все документы — карточки проектов, займы, возмещения, платежи, учёт рабочего времени, заявки на закупку — используют один и тот же набор интерфейсов, управляемых через 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 }

Поэтому структура этого сервиса — «один выход + два уровня обёртки», а не десятки констант конечных точек.

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

Аутентификация: четыре заголовка, без подписи

В отличие от kingdee-star-mcp (шлюз jdy) — по-другому — для «Трёх эффектов» не требуется HMAC-подпись, достаточно четырёх заголовков, все они заранее получаются через стандартный API Xingchen:

Предупреждение о подводных камнях: в официальной документации явно указано, что «при отладке на маркетплейсе облачной платформы можно игнорировать X-GW-Router-Addr». Поэтому многие отлаживают на маркетплейсе, а в коде получают 404 — потому что при вызове из кода обязательно нужно передавать этот заголовок. config.headers() уже обрабатывает это, не удаляйте.

После получения четырёх элементов заполните .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 (только собирает, не отправляет; в первой фазе можно использовать для ручной проверки сообщений) sx_save_or_update / sx_submit / sx_un_submit / sx_audit / sx_un_audit / sx_delete / sx_push

Как писать условия запроса

Официальный qParams — это массив условий: верхние элементы соединяются и, внутри группы условий — через 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() или группу or в sx_build_query. Поля записей пишутся как «идентификатор записи.идентификатор поля», например projectfileteam.teamstaff.

Модель безопасности

Защита — белый список + отказ по умолчанию в три уровня:

1. Классификация действий — listQuery/getById/operation — чтение, остальные семь — запись.

2. Белый список operationKey — operation на вид интерфейс чтения, но operationKey — свободная строка, поэтому для девяти методов из разделов 10.1–10.9 документации делается ещё один белый список.

3. Финансовые операции запрещены навсегда — запись и действия процесса для платёжных документов (bdi_ex_pay*), даже если SX_ALLOW_WRITE_ACTIONS=* — блокируется.

Порядок открытия записи во второй фазе: SX_READONLY=false → в SX_ALLOW_WRITE_ACTIONS добавляйте действия по одному для постепенного включения. Не переходите сразу к *.

Все вызовы и блокировки записываются в логгер sanxiao.audit.

Реальные сообщения опровергают впечатление от документации

Официальный дополнительный «Справочный код 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 в сообщении извлечены восемь 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, и имя поля имеют такое написание. Не «исправляйте» это.

Откуда берутся идентификаторы полей

Не гадайте. Авторитетный способ — интерфейс Xingchen: список документов → Ещё → Импорт данных → Управление шаблонами → Новый шаблон.

После запуска можно также проверить обратным способом: sx_get_form_config(form_id) вызовет operation.getUserconfig и вернёт конфигурацию полей этого документа.

В forms.py зарегистрировано 15 formId: семь из официальной документации (bdi_projectfile, bdi_ex_loan, bdi_ex_bx, bdi_ex_pay, bdi_fillinworkinghours, pur_bill_request, bd_auxinfo), восемь — из ссылок на базовые записи в сообщении справочного кода. Остальные документы можно передавать formId напрямую в sx_list_query, предварительная регистрация не нужна.

Аналогично с именами полей — только поля bdi_projectfile проверены по реальному сообщению (обратите внимание: там используется status/enable, нет billstatus; это поле бизнес-документов). Поля по умолчанию для остальных документов всё ещё предполагаются по соглашению, после запуска проверьте через sx_get_form_config.

Отношение к kingdee-star-mcp

Оба — два открытых возможности одного и того же учётного экземпляра Xingchen, развёрнуты независимо:

Токен Token для «Трёх эффектов» нужно сначала получить через стандартный API Xingchen — если вы уже прошли цепочку авторизации в kingdee-star-mcp, можно взять полученный токен и domain/groupname/ accountid из push-уведомления об авторизации и напрямую заполнить в .env этого проекта.

Известные пробелы

• В официальной документации нет единой схемы ответа, client._unwrap() выполняет мягкую распаковку: если распознаёт errcode/success/data — нормализует, если нет — возвращает как есть: лучше отдать больше данных, чем потерять из-за неверной структуры. После получения реальных ответов можно ужесточить.

• Коды статусов документов в документации перечислены не полностью. В справочном коде для карточки проекта status="A", enable="1", но что означают A/B/C и допустимые значения billstatus для бизнес-документов — авторитетного объяснения нет. Параметр status в семантическом слое пока передаёт исходный идентификатор.

• В справочном коде есть несколько полей с противоречивым fType — phaseplanenddate, phaseenddate объявлены как num, но явно являются датами. Это несогласованность в самом сообщении производителя, модель принимает как есть, без исправлений, чтобы не «навредить».

• Загрузка вложений идёт через base64, для больших файлов нужно оценить лимит размера шлюза, в документации не указано.