kingdee_star —— MCP-сервер Kingdee Cloud Star

GC032 Финансовый агент · сторона Kingdee (со стороны DingTalk уже подключена через DingTalk MCP, этот репозиторий — только Kingdee). Выравнивание по требованиям 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

Аутентификация (два уровня учётных данных, не перепутайте)

Цепочка:

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

Три частые ловушки (обработаны в 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

Объедините kingdee-star из mcp.config.json в конфигурацию mcpServers клиента (измените cwd и env). Совместим с двумя мажорными версиями mcp — 1.x и 2.x.

Список инструментов (17)

Счета-фактуры по продажам и по закупкам — это не два эндпоинта, фильтрация через bill_type / invoice_type в fi/invoice_fp.

⚠ Реальные ограничения записи возмещений

В официальной открытой платформе всего 370 интерфейсов, в модуле ebx есть только один GET — «детали报销单», нет ни списка报销单, ни какого-либо интерфейса сохранения报销单.

Поэтому «автозаполнение черновика报销单 счетами-фактурами» из требований v2.1 не может быть записано в базу через открытый API:

• kdy_fill_reimbursement выдаёт только готовый к вводу报文 с уже рассчитанным налогом и прошедшей проверкой соответствия, dry_run=False будет явно отклонён.

• Для реальной автоматической записи возможен только не-открытый API-канал (RPA / фронтовые интерфейсы / заказ кастомного интерфейса у Kingdee).

Границы безопасности

• JDY_READONLY=true → чистое чтение.

• Защитный слой — белый список + отказ по умолчанию: обход через изменение пути (хвостовой слэш, подпути, регистр) невозможен.

• Запись платежей/проводок/счетов, отправка возмещений на утверждение → навсегда запрещено (FORBID_ENDPOINTS), выполняется вручную.

• Полный аудит: журнал kingdee_star.audit.

Механизм расчёта налога

При вычете по пассажирским перевозкам отсутствует пассажир → проверка соответствия помечает как не подлежащий вычету. Отрицательные (красные) счета-фактуры отклоняются напрямую.