KingdeeMCP: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

# Install in development mode
pip install -e .

# Run the MCP server directly
kingdee-mcp

# Run with uvx (no install needed)
uvx kingdee-mcp

# Build distribution package
pip install hatchling
python -m hatchling build

# Install with all deps
pip install "mcp[cli]>=1.0.0" httpx pydantic

Run tests:

# Unit + mock tests (no Kingdee server required)
python -m pytest tests/ -v

# Integration tests (requires Kingdee server + env vars)
KINGDEE_SERVER_URL=http://your-server/k3cloud/ \
KINGDEE_ACCT_ID=... KINGDEE_USERNAME=... \
KINGDEE_APP_ID=... KINGDEE_APP_SEC=... \
KINGDEE_LCID=2052 \
python -m pytest tests/test_integration.py -v

# End-to-end workflow tests (requires real Kingdee env, same vars as above)
# Auto-skipped when KINGDEE_* env vars are absent — never commit credentials in source.
python -m pytest tests/e2e -v -m e2e

Run the evaluation layer (evals/ — agent 行为评估与回归对比，详见 evals/README.md）:

# 离线自检整条评估管线（mock agent + mock 账套状态，无需金蝶、不写数据）
python -m evals.run_eval --dry-run

# 真实评估（连测试账套；需先把 evals/config.yaml 的 test_account.confirmed 设为 true）
python -m evals.run_eval

Architecture

This is a single-file MCP Server (src/kingdee_mcp/server.py) that bridges AI clients to Kingdee Cloud K/3 ERP via its WebAPI.

Request Flow

1. AI client calls a tool → FastMCP dispatches to the decorated async function
2. Function calls _post(ep_key, payload) with a [form_id, {params}] list
3. _post() checks the global _session_id cache; calls _login() if absent
4. On 401 or session-expired response, auto re-logins and retries once
5. All tools return JSON strings (success or error message from _err())

Key Internals

• _EP dict — maps short names ("query", "save", etc.) to full Kingdee WebAPI endpoint paths
• _session_id global — cached session cookie (kdservice-sessionid) from LoginByAppSecret
• FORM_CATALOG dict — maps form_id → {name, alias[], fields} used by kingdee_list_forms and kingdee_get_fields to help the AI discover form IDs without hitting the API
• Pydantic input models — each tool has a dedicated model (QueryInput, SaveInput, BillIdsInput, etc.) with extra="forbid" for strict validation