Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@kingdee-mcp 查看采购订单 20260806JX-01"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
金蝶云星空（K3Cloud）MCP Server。通过 Model Context Protocol 让 AI 助手（Cursor、Claude Desktop、Claude Code、Cline、Cherry Studio 等）用自然语言查询和操作金蝶 ERP。已验证部署通过
AI 助手（Cursor / Claude / …）
│ MCP（stdio / SSE）
▼
kingdee-mcp
│ Kingdee Web API SDK
▼
金蝶云星空 K3Cloud15 个 MCP 工具：查询、翻页/落盘/日期分片、查看详情、元数据；以及保存、提交、审核、反审核、删除、下推等
通用 form_id：同一套工具适配物料、客户、销售/采购订单、出入库等表单
只读 / 读写模式：readonly 时写入工具会从工具列表中移除（并保留运行时守卫）
自动会话恢复：会话超时后自动重新登录
多传输协议：stdio（本地 IDE）、sse / streamable-http（远程）
Docker 友好：默认监听 0.0.0.0:8181，可对接阿里云 CLB 等负载均衡
Related MCP server: kingdee-k3cloud-mcp
Python 3.10+
可访问的金蝶云星空环境
集成用户账号（建议专用账号，按最小权限授权）
git clone https://github.com/YanSir1999/kingdee-mcp.git
cd kingdee-mcp
python -m venv .venv
# Windows
.venv\Scripts\activate
# macOS / Linux
source .venv/bin/activate
pip install -e .cp .env.example .env编辑 .env：
变量 | 必填 | 说明 |
| 是 | 金蝶地址，建议以 |
| 是 | 账套 ID |
| 是 | 集成用户账号 |
| 建议 | 密码（ |
| 否 | SSE 监听地址；Docker/CLB 用 |
| 否 | SSE 端口，默认 |
| 否 |
|
| 否 | SSE/HTTP Bearer Token；不设则不鉴权 |
| 否 | 鉴权元数据对外 URL（启用 |
| 否 | SSE Host 白名单，逗号分隔；解决远程 |
kingdee-mcp
# 或
kingdee-mcp --transport stdio --mode readonly项目内 .cursor/mcp.json 示例：
{
"mcpServers": {
"kingdee-mcp": {
"command": "D:\\workspace\\kingdee-mcp\\.venv\\Scripts\\kingdee-mcp.exe",
"cwd": "D:\\workspace\\kingdee-mcp"
}
}
}凭证从项目根目录 .env 加载，无需写进 JSON。
{
"mcpServers": {
"kingdee-mcp-remote": {
"url": "https://your-domain.example.com/sse"
}
}
}若启用了 MCP_API_KEY：
{
"mcpServers": {
"kingdee-mcp-remote": {
"url": "https://your-domain.example.com/sse",
"headers": {
"Authorization": "Bearer your-secret-api-key"
}
}
}
}{
"mcpServers": {
"kingdee-mcp": {
"command": "kingdee-mcp",
"args": ["--mode", "readonly"],
"env": {
"KD_SERVER_URL": "https://your-server/k3cloud/",
"KD_ACCT_ID": "your_acct_id",
"KD_USERNAME": "your_username",
"KD_PASSWORD": "your_password"
}
}
}
}docker build -t kingdee-mcp:local .镜像默认：
传输：sse
模式：readonly
端口：8181
监听：0.0.0.0
仓库已提供通用 docker-compose.yml（本地 build，无内网镜像地址）：
docker compose up -d --build典型拓扑：
客户端 https://your-domain/sse
→ CLB（443）
→ 后端 ECS/容器 :8181
→ kingdee-mcp（SSE）建议在 .env 中设置：
FASTMCP_HOST=0.0.0.0
FASTMCP_PORT=8181
MCP_ALLOWED_HOSTS=your-domain.example.com,localhost:*,127.0.0.1:*
MCP_ISSUER_URL=https://your-domain.example.com
MCP_MODE=readonly连通性自检：
curl -i -N -H "Accept: text/event-stream" https://your-domain.example.com/sse正常应返回 200 与 event: endpoint。
readonly / readwrite）工具 | 说明 |
| 查询单据（二维数组） |
| 查询单据（JSON，字段名为 key） |
| 估算行数 |
| 自动翻页拉取 |
| 翻页流式落盘（ndjson/csv） |
| 按日期分片 + 翻页 |
| 单条详情 |
| 表单元数据 |
readwrite）工具 | 说明 |
| 保存/新增 |
| 提交 |
| 审核 |
| 反审核 |
| 删除 |
| 自定义操作（禁用/反禁用等） |
| 下推 |
常用 form_id 示例：
FormId | 说明 |
| 物料 |
| 客户 |
| 供应商 |
| 销售订单 |
| 采购订单 |
| 生产订单 |
| 入/出库单 |
默认 MCP_MODE=readonly（或 --mode readonly）：
写入工具从 MCP 工具列表中移除
即使被直接调用，也会返回 只读模式：写入操作已禁用
kingdee-mcp --mode readonly # 仅查询
kingdee-mcp --mode readwrite # 开放写入「查一下昨天的销售订单」
「查看采购订单 20260806JX-01」
「付款条件编码 023 是什么」
「统计本月销售订单数量」
# MCP Inspector（远程 SSE）
npx @modelcontextprotocol/inspector https://your-domain.example.com/sse
# 单元测试
pip install -e ".[dev]"
pytestkingdee-mcp/
├── src/kingdee_mcp/
│ ├── server.py # MCP Server 与工具实现
│ └── form_id_reference.py # 常用 FormId 参考
├── tests/
├── Dockerfile
├── docker-compose.yml
├── .env.example
├── LICENSE
├── NOTICE
├── SECURITY.md
├── pyproject.toml
├── README.md
└── README.en.md不要将 .env 提交到 Git（详见 SECURITY.md）
生产环境优先 MCP_MODE=readonly
远程 SSE 建议设置 MCP_API_KEY，并配置 MCP_ALLOWED_HOSTS
金蝶侧使用专用集成用户，按模块与数据范围最小化授权
核心能力与工具设计参考并受益于上游开源项目：
详见 NOTICE。
估算某查询条件下的数据行数（不返回数据内容）。用于大数据量查询前的探测。
返回 JSON 格式： {"estimated_rows": N, "is_exact": true/false, "hint": "..."} 当 is_exact=false 时，实际行数 ≥ estimated_rows，建议按月/周分片查询。
Args: form_id: 表单ID。如 SAL_SaleOrder、PUR_PurchaseOrder、BD_MATERIAL 等 filter_string: 过滤条件。如 "FDate >= '2025-01-01' AND FDate < '2026-01-01'"
| Name | Required | Description | Default |
|---|---|---|---|
| form_id | Yes | ||
| filter_string | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the return format including estimated_rows, is_exact, and hint, and explains the implication of is_exact=false (actual rows >= estimated). It also states that no data content is returned, which is a key behavioral trait. Given no annotations, this covers the main behavioral aspects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is organized with a clear purpose, usage, return format, and attributes. Each section provides useful info without unnecessary fluff, though it is somewhat verbose for a simple count tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 2 parameters (both explained), an output schema, and the description covers the return fields, the estimation caveat, and usage guidance. Considering the moderate complexity, the description is fully sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides no descriptions (coverage 0%), but the description gives concrete examples for both form_id (e.g., SAL_SaleOrder) and filter_string (e.g., FDate condition), adding essential meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it estimates the number of rows for a query condition (估算某查询条件下的数据行数) and explicitly notes it does not return data content (不返回数据内容), distinguishing it from sibling query tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states the intended use as probing before large data volume queries (用于大数据量查询前的探测) and advises monthly/weekly sharding when the estimate is not exact (建议按月/周分片查询). It does not name alternatives explicitly but provides clear context for when to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| form_id | Yes | ||
| start_row | No | ||
| top_count | No | ||
| field_keys | Yes | ||
| order_string | No | ||
| filter_string | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
自动翻页查询直到拉完或达到 max_rows 安全上限。
适合估算 ≤ 数千行的场景。大数据量（> 5000 行）请用 query_bill_to_file（落盘） 或 query_bill_range（日期分片），避免超过 MCP 1 MB 返回限制。
返回格式： {"rows": [...], "row_count": N, "exhausted": true/false, "next_start_row": N, # 仅 exhausted=false 时 "hint": "..."} # 仅 exhausted=false 时
Args: form_id: 表单ID。如 SAL_SaleOrder、PUR_PurchaseOrder、BD_MATERIAL 等 field_keys: 查询字段，逗号分隔。如 "FBillNo,FDate,FAmount" filter_string: 过滤条件。如 "FDate >= '2025-01-01'" order_string: 排序字段。如 "FDate ASC" max_rows: 安全上限，默认 20000；超过则提前终止并返回 exhausted=false page_size: 每页行数，默认 2000，建议不超过 2000
| Name | Required | Description | Default |
|---|---|---|---|
| form_id | Yes | ||
| max_rows | No | ||
| page_size | No | ||
| field_keys | Yes | ||
| order_string | No | ||
| filter_string | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses the pagination loop, early termination via max_rows, exhausted flag semantics, next_start_row continuation, and the MCP response limit rationale. This is rich behavioral context beyond a simple 'query' operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections: purpose, usage guidance, return format, and parameter breakdown. It is front-loaded with the core behavior, and every line adds value with no filler content. The use of bullets and examples enhances readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has moderate complexity (auto-pagination), but the description covers all aspects: purpose, when to use, parameter semantics, return format, and edge cases (exhausted=false, next_start_row). It is self-contained and sufficient for a correct invocation, especially given the absent annotations and schema descriptions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description thoroughly explains all 6 parameters with concrete examples (e.g., form_id: SAL_SaleOrder, field_keys: FBillNo,FDate,FAmount, filter_string: FDate >= '2025-01-01'). It also clarifies default values and constraints for max_rows and page_size, fully compensating for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool performs auto-paginated queries until all records are fetched or max_rows is reached. It distinguishes itself from siblings by explicitly naming alternatives for large datasets (query_bill_to_file, query_bill_range) and defines the exact resource (bills) and operation (query).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states that this tool is suitable for estimating ≤ 5000 rows and directs users to query_bill_to_file or query_bill_range for larger datasets, citing the MCP 1 MB return limit. This provides clear when-to-use and when-not-to-use guidance with alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| form_id | Yes | ||
| start_row | No | ||
| top_count | No | ||
| field_keys | Yes | ||
| order_string | No | ||
| filter_string | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
按日期自动切片 + 翻页，适合跨月/跨年查询。
将 [date_from, date_to) 按 chunk 切成 N 段，每段独立翻页拉取。 output_path 为空时内联返回（受 MCP 1 MB 限制，适合小跨度）； 非空时流式落盘，适合大跨度（年级）查询。
返回格式（内联）： {"rows": [...], "row_count": N, "chunks": K, "exhausted": true} 返回格式（落盘）： {"path": "...", "row_count": N, "bytes": M, "chunks": K, "format": "ndjson"} 若中途出错：{"error": "...", "path": "...", "row_count": <已写入>, "bytes": M}
Args: form_id: 表单ID。如 SAL_SaleOrder、PUR_PurchaseOrder 等 field_keys: 查询字段，逗号分隔 date_field: 日期字段名。通常是 FDate 或 FCreateDate date_from: 起始日期（含），YYYY-MM-DD date_to: 结束日期（不含），YYYY-MM-DD extra_filter: 额外过滤条件（与日期条件 AND 拼接） chunk: 切片粒度，month（默认）/ week / day output_path: 落盘路径（绝对路径）。空=内联返回 page_size: 每页行数，默认 2000
| Name | Required | Description | Default |
|---|---|---|---|
| chunk | No | month | |
| date_to | Yes | ||
| form_id | Yes | ||
| date_from | Yes | ||
| page_size | No | ||
| date_field | Yes | ||
| field_keys | Yes | ||
| output_path | No | ||
| extra_filter | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses key behaviors: automatic date slicing, independent pagination per chunk, the 1 MB inline limit, streaming write behavior when output_path is set, and error handling with partial row counts. This is exceptionally transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a one-line summary, behavior explanation, output format examples, and a parameter list. It is slightly long but every section earns its place. The return format examples are slightly redundant given the output schema exists, but they provide valuable concrete context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex tool with 9 parameters and chunking logic, the description is complete. It covers all parameters, behavioral nuances, output modes, error handling, and format details. An agent can confidently select and invoke this tool correctly based on this description alone.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero description coverage, but the description compensates fully. Every parameter is explained with meaning and examples: form_id (e.g., SAL_SaleOrder), field_keys (comma-separated), date_field (e.g., FDate), date_from/to (inclusive/exclusive), extra_filter (AND-combined), chunk (month/week/day), output_path (empty vs absolute path), and page_size (default 2000).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: it automatically slices a date range into chunks and paginates through each chunk, making it suitable for cross-month/year queries. This distinguishes it from siblings like query_bill (likely single-range) and query_bill_all (likely without chunking).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description specifies that it is suited for cross-month/year queries and explains the trade-off between inline return (MCP 1 MB limit) and streaming to file for large spans. It does not explicitly name alternative tools, but the context is clear enough for an agent to decide when to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
自动翻页并流式写入本地文件，适合大数据量导出（万行以上）。
不在内存中累积数据，写入完成后返回文件路径和统计信息。 文件可用 Read 工具抽检，或交由 pandas/polars 处理。
返回格式： {"path": "...", "row_count": N, "bytes": M, "format": "ndjson"} 若中途出错：{"error": "...", "path": "...", "row_count": <已写入>, "bytes": M}
Args: form_id: 表单ID。如 SAL_SaleOrder、PUR_PurchaseOrder、BD_MATERIAL 等 field_keys: 查询字段，逗号分隔。如 "FBillNo,FDate,FAmount" filter_string: 过滤条件。如 "FDate >= '2025-01-01'" output_path: 输出文件绝对路径。如 "/tmp/orders.ndjson" format: 输出格式，ndjson（每行一个 JSON 对象）或 csv，默认 ndjson page_size: 每页行数，默认 2000 max_rows: 最大写入行数，默认 500000；超过则截断并正常返回
| Name | Required | Description | Default |
|---|---|---|---|
| format | No | ndjson | |
| form_id | Yes | ||
| max_rows | No | ||
| page_size | No | ||
| field_keys | Yes | ||
| output_path | No | ||
| filter_string | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full responsibility. It discloses auto-pagination, streaming writes, no in-memory accumulation, return format with row_count/bytes, error behavior with partial rows, and max_rows truncation—all beyond what the schema shows.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with purpose and use case, followed by a concise return-format spec and a clearly structured Args list. Every section earns its place given the tool's complexity (7 parameters and rich behavior).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema is included in the description (@return/error shape) and the parameters are fully documented, the description covers the entire invocation lifecycle: when to use, how to call, and what to expect on success/failure. No major gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate fully. It explains every parameter with concrete examples (e.g., form_id like 'SAL_SaleOrder', filter_string like "FDate >= '2025-01-01'"), defaults, and the output_path example. This is exemplary.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource+outcome: '自动翻页并流式写入本地文件' (auto-paginate and stream-write to local file). It clearly distinguishes from siblings like query_bill and view_bill by emphasizing file output for large exports.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states suitability for large data exports ('适合大数据量导出（万行以上）') and explains the streaming/no-memory-accumulation advantage. It mentions the file can be read by Read tool or pandas/polars, but does not explicitly state when to avoid this tool or name alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
查询金蝶云星空表单的元数据（字段结构信息）。
用于获取某个表单有哪些字段、字段类型等信息，便于构造查询和保存参数。
Args: form_id: 表单ID。如 SUB_ReqChange(委外订单变更单)、SUB_SubReqOrder(委外订单)、 SAL_SaleOrder、PUR_PurchaseOrder、BD_MATERIAL 等
| Name | Required | Description | Default |
|---|---|---|---|
| form_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are absent, so the description must carry the burden. It uses '查询' (query) which implies a read-only operation, and mentions it is for metadata retrieval, so the non-destructive nature is reasonably implicit. However, it does not explicitly state safety, permissions, or error behavior, but the simplicity of the operation and the presence of an output schema mitigate this.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and focused, with a clear purpose statement, a usage rationale, and a labeled Args section with an example. No unnecessary filler. It is slightly verbose due to the paragraph format, but every sentence contributes value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (1 parameter, no nested objects) and has an output schema, so the description need not detail return values. It covers purpose, typical use cases, and parameter semantics. It does not mention edge cases or prerequisites, but these are not essential for such a straightforward metadata query.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides only a type and no description for form_id (0% schema coverage). The description compensates by defining form_id as '表单ID' and providing concrete examples (e.g., SUB_ReqChange, SAL_SaleOrder), adding meaningful guidance beyond the schema. It could go further by explaining how to discover other form IDs, but the examples are valuable.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the function: '查询金蝶云星空表单的元数据（字段结构信息）' (query metadata/field structure of Kingdee Cloud Star forms). It identifies the specific verb (query), resource (metadata), and scope (form field information), distinguishing it from sibling bill-querying tools. Examples of common form IDs further clarify the target resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the purpose: to retrieve field information for constructing query and save parameters ('便于构造查询和保存参数'). This gives clear context for when to use the tool. It does not explicitly contrast with sibling tools or mention when not to use it, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
查看金蝶云星空单条记录的完整详情。
通过编号或内码查看单条记录的所有字段信息。
Args: form_id: 表单ID。如 BD_MATERIAL、SAL_SaleOrder 等 number: 单据编号。如 "MATERIAL001"（number 和 bill_id 二选一） bill_id: 单据内码ID（number 和 bill_id 二选一）
| Name | Required | Description | Default |
|---|---|---|---|
| number | No | ||
| bill_id | No | ||
| form_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the full burden. It explicitly states '查看' (view), indicating a read-only behavior, and promises '所有字段信息' (all field information), describing what the agent can expect. No side effects or prerequisites are mentioned, but for a straightforward view operation this is reasonable transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and structured. The main purpose is stated in two brief sentences, followed by a compact parameter list with examples. Every sentence contributes value and there is no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, usage, and all parameters effectively. Since an output schema exists, the absence of return-value explanations is acceptable. The only notable gap is the lack of explicit sibling differentiation, but the 'single record' focus already suggests the tool's niche, making it fairly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description fully compensates. It defines form_id with examples (BD_MATERIAL, SAL_SaleOrder), explains number as the document number with an example, and clarifies bill_id as the internal ID, plus the mutual exclusivity rule. This adds substantial semantic meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: '查看金蝶云星空单条记录的完整详情' (view complete details of a single record). It specifies a precise verb (view), a resource (bill record), and a scope (single record), which distinguishes it from sibling tools like query_bill that likely handle lists or broader queries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains how to use the tool: by number or internal ID, with the constraint that number and bill_id are mutually exclusive. It implies the appropriate context (when you need complete details of one specific record) but does not explicitly name alternatives or state when not to use it, so it falls slightly short of full exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.3.2count_billquery_billquery_bill_allquery_bill_jsonquery_bill_rangequery_bill_to_filequery_metadataview_billScored across 8 tools
The query_bill family contains five tools (query_bill, query_bill_json, query_bill_all, query_bill_to_file, query_bill_range) with heavily overlapping purposes; query_bill and query_bill_json are completely undifferentiated and have no descriptions. While some tools have mode-specific suffixes, an agent could easily select the wrong one without deep inspection.
Tool names follow a consistent lowercase verb_noun pattern (query_, count_, view_), and the query_bill_* variants share a clear prefix. However, the naming doesn't fully clarify the differences between _all, _range, _to_file, and _json, and query_bill vs query_bill_json is ambiguous.
Eight tools is well-scoped for a specialized ERP data access server. Each tool serves a distinct operational mode (basic query, paginated query, date-range query, file export, count, detail, metadata), and the count feels neither thin nor bloated.
The read-query surface is comprehensive: multiple query modes, row counting, single-record detail, and metadata retrieval cover the expected needs for a Kingdee data query MCP. Minor gaps include a lack of form discovery (listing available form IDs) and no write/update operations, but these may be intentionally outside scope.
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
AI for Tally Prime and Tally ERP 9. Hosted MCP server to ask your accounts in any language.
MCP server for AI dialogue using various LLM models via AceDataCloud
MCP server exposing klokin time-tracking operations (employees, time entries, stores) to AI clients.
