jushuitan-mcp
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., "@jushuitan-mcpSearch for the order upload API and show its request parameters and error codes."
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.
jushuitan-mcp
中文
聚水潭开放平台 API 文档 MCP Server —— 让 AI Agent(Claude、Cursor、ZCode、Cline 等)直接检索聚水潭开放 API 的接口分类、参数说明、错误码与请求/响应示例,不再需要人工翻文档。
数据来源于聚水潭开放平台官方文档站(openweb.jushuitan.com),通过其公开文档接口抓取并本地结构化。
⚠️ 本项目为非官方工具,仅聚合公开文档便于检索;文档内容版权归聚水潭所有。仓库不包含抓取的文档数据,使用前请自行执行
npm run fetch获取。
功能
工具 | 说明 |
| 列出全部接口分类(20 个)及接口数量 |
| 列出某分类下的所有接口(名称 / 路由 / docId) |
| 按关键词全局搜索接口(名称、路由、分类) |
| 查看接口完整文档,支持按节过滤(公共参数 / 请求参数 / 返回参数 / 错误码 / 各类示例) |
| 从官方文档站重新抓取并更新本地快照 |
get_api_doc 输出包含:请求地址(正式/测试环境 baseurl)、公共请求参数、请求参数说明(由官方 JSON Schema 展开,含嵌套层级与示例值)、返回参数说明、错误码与排查方法、请求/响应/异常示例、CURL/JAVA/C#/PHP 代码示例。
快速开始
要求 Node.js ≥ 20。
git clone https://github.com/CO2T5ZN/jushuitan-mcp.git
cd jushuitan-mcp
npm install
npm run build
npm run fetch # 拉取文档数据到 data/jushuitan-docs.json(约 10-30 秒)一键安装(把提示词复制给 AI Agent)
不想手动改配置的话,把下面这段提示词复制给你的 AI Agent(ZCode、Claude Code、Cursor、Cline 等)即可,详细步骤在仓库 README 里,Agent 克隆后会自行阅读执行:
请帮我安装 MCP Server「jushuitan-mcp」:把仓库 https://github.com/CO2T5ZN/jushuitan-mcp 克隆到本地目录,然后阅读仓库根目录的 README.md,按其中「给 AI Agent 的操作指引」完成构建、数据拉取与 MCP 注册,最后调用 list_categories 验证并向我报告结果。给 AI Agent 的操作指引
克隆与构建:把 https://github.com/CO2T5ZN/jushuitan-mcp.git 克隆到本地目录(若目标目录已存在且是该仓库则跳过克隆),进入仓库目录依次执行
npm install、npm run build、npm run fetch。fetch会从官方文档站拉取数据到data/jushuitan-docs.json,约 10-30 秒;若执行失败,可在完成 MCP 注册后改用refresh_data工具在线拉取。注册 MCP:把你自己的 MCP 服务器配置写入 Agent 所用的 MCP 配置文件——名称
jushuitan-mcp,stdio 方式,command: node,args: ["<仓库绝对路径>/dist/index.js"],env.JUSHUITAN_MCP_DATA设为<仓库绝对路径>/data/jushuitan-docs.json。各客户端的配置文件位置与格式见下节「客户端配置」;Windows 下 JSON 里路径必须用正斜杠或双反斜杠。验证:重新加载 / 重启后调用工具
list_categories,能返回 20 个接口分类即安装成功;向用户报告结果,失败则排查修复后重试。
客户端配置
通用前提:
服务器以 stdio 方式启动:
node <仓库绝对路径>/dist/index.js。配置中请使用绝对路径。首次使用前先在仓库目录执行
npm run fetch生成数据快照;如果没生成,也可以直接让 Agent 调用refresh_data工具在线拉取。建议在
env中设置JUSHUITAN_MCP_DATA指向数据文件绝对路径(IDE 启动 MCP 时不一定以仓库为工作目录)。Windows 路径注意:JSON 字符串里
\是转义符,"D:\Tools\..."会因非法转义(如\T)导致解析失败、无法保存。请改用正斜杠"D:/Tools/...",或写成双反斜杠"D:\\Tools\\..."。
ZCode(两种方式任选):
方式一:客户端界面添加 —— Settings → MCP → 添加,粘贴如下 JSON(单个服务器条目,无外层包装):
{
"jushuitan-mcp": {
"type": "stdio",
"command": "node",
"args": ["/path/to/jushuitan-mcp/dist/index.js"],
"env": {
"JUSHUITAN_MCP_DATA": "/path/to/jushuitan-mcp/data/jushuitan-docs.json"
}
}
}方式二:直接编辑配置文件 —— 工作区级 <repo>/.zcode/config.json(随仓库共享)或用户级 ~/.zcode/cli/config.json,文件里需要包一层 mcp.servers:
{
"mcp": {
"servers": {
"jushuitan-mcp": {
"type": "stdio",
"command": "node",
"args": ["/path/to/jushuitan-mcp/dist/index.js"],
"env": {
"JUSHUITAN_MCP_DATA": "/path/to/jushuitan-mcp/data/jushuitan-docs.json"
}
}
}
}
}注意:ZCode 配置文件不展开 ${...} 模板变量,command/args 必须写绝对路径;schema 校验严格,不要添加未知字段。保存后重启会话,在 Settings → MCP 中确认 jushuitan-mcp 已自动连接。仓库内的 .zcode/config.json.example 可复制后替换路径使用。
CodeBuddy(项目级:.codebuddy/mcp_settings.json;或在 IDE 的 MCP 管理界面添加):
{
"mcpServers": {
"jushuitan-mcp": {
"command": "node",
"args": ["/path/to/jushuitan-mcp/dist/index.js"],
"env": {
"JUSHUITAN_MCP_DATA": "/path/to/jushuitan-mcp/data/jushuitan-docs.json"
}
}
}
}Trae(v1.3.0+):AI 面板 → 右上角设置 → MCP → 添加 → 手动配置,粘贴以下 JSON 保存;也可直接写入项目级 .trae/mcp.json:
{
"mcpServers": {
"jushuitan-mcp": {
"command": "node",
"args": ["/path/to/jushuitan-mcp/dist/index.js"],
"env": {
"JUSHUITAN_MCP_DATA": "/path/to/jushuitan-mcp/data/jushuitan-docs.json"
}
}
}
}Claude Desktop / Cursor / Cline(Claude Desktop 写入 claude_desktop_config.json,Cursor/Cline 用设置界面或项目级 .mcp.json,格式相同):
{
"mcpServers": {
"jushuitan-mcp": {
"command": "node",
"args": ["/path/to/jushuitan-mcp/dist/index.js"],
"env": {
"JUSHUITAN_MCP_DATA": "/path/to/jushuitan-mcp/data/jushuitan-docs.json"
}
}
}
}通过 npx 运行(发布 npm 后可用):
{
"mcpServers": {
"jushuitan-mcp": {
"command": "npx",
"args": ["-y", "jushuitan-mcp"]
}
}
}npx 方式首次使用时,若无本地数据,可直接让 Agent 调用 refresh_data 工具在线拉取。
数据存放路径
快照默认写入/读取 data/jushuitan-docs.json,查找优先级:
环境变量
JUSHUITAN_MCP_DATA指定的文件路径当前工作目录
./data/jushuitan-docs.json包安装目录下的
data/jushuitan-docs.json
典型用法(Agent 视角)
list_categories → 浏览 20 个分类
list_apis(category="订单API") → 该分类 16 个接口
search_apis(keyword="订单上传") → 定位 /open/jushuitan/orders/upload
get_api_doc(api="/open/shops/query", section="request_params")
→ 只看请求参数
get_api_doc(api="1") → 按 docId 读完整文档开发
npm run build # tsc 编译到 dist/
npm test # 端到端 smoke test(stdio JSON-RPC,16 项断言)
npm run fetch # 重新抓取数据目录结构
src/
├── index.ts # stdio 入口
├── server.ts # MCP Server 与工具注册
├── tools.ts # 5 个工具的定义与处理
├── render.ts # Markdown 渲染
├── store.ts # 本地快照读写与检索
├── fetcher.ts # 官方文档接口抓取(cookie 维护/重试/并发控制)与数据归一化
├── schema.ts # JSON Schema -> 扁平参数表
├── text.ts # 富文本/表格转义
└── types.ts
scripts/smoke-test.mjs声明
本项目与聚水潭(上海聚水潭网络科技股份有限公司)无隶属关系。接口文档内容(含参数说明、示例)版权归原作者所有,请仅将其用于开发对接聚水潭开放平台时的参考。请合理使用 refresh_data,勿高频抓取。
Related MCP server: Daraja API MCP Server
English
An MCP server that exposes the Jushuitan Open Platform API documentation (an ERP/SaaS order platform widely used in China) to AI agents: 20 categories / ~175 APIs with routes, base URLs, common params, request/response param tables (flattened from official JSON Schemas), error codes, and request/response/exception examples.
The repo ships code only — doc content is fetched from the platform's public doc endpoint via npm run fetch and stored locally (data/jushuitan-docs.json, gitignored). Tools: list_categories, list_apis, search_apis, get_api_doc, refresh_data.
See the 中文 section above for full instructions; configuration is identical apart from language. To auto-install, copy the prompt in the 「一键安装」 block above and paste it into your AI agent.
License
MIT
Available Tools
5 toolsget_api_doc查看接口文档A
查看某个接口的完整文档:请求地址、公共参数、请求/返回参数说明、错误码、请求/响应/异常示例。可先用 list_apis 或 search_apis 找到接口。
| Name | Required | Description | Default |
|---|---|---|---|
| api | Yes | 接口标识:docId、路由(如 /open/shops/query)或接口名称(名称支持模糊匹配,命中多个时会列出候选) | |
| section | No | 只看某一节:overview/urls/common_params/request_params/response_params/errors/request_example/response_example/exception_example,默认全部 | all |
| category | No | 可选:限定分类(名称或ID),用于消除重名 |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It clearly describes a read-only lookup action ('查看') and spells out what the returned document contains. It does not mention permissions or side effects, but for a read-only doc retrieval tool this is adequate.
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 compact, front-loaded with the primary purpose, and every sentence earns its place by describing what the tool returns and how to find the target API.
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 3 parameters, full schema coverage, and no output schema, the description adequately covers the tool's purpose, result contents, and discovery workflow. It could note multi-match candidate behavior, but that is already in the parameter schema.
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 100%, so the baseline is 3. The description adds only a loose connection to list_apis/search_apis as a discovery step but does not add parameter-level detail 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 the action (查看/view) and the resource (某个接口的完整文档), and enumerates the document sections. It also distinguishes itself from list_apis and search_apis by implying those are for discovery while this one retrieves the full documentation.
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 gives clear usage context by telling the agent to '可先用 list_apis 或 search_apis 找到接口', i.e., discover first with siblings then use this tool. It does not explicitly state when not to use it, but the sequencing is strong enough guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_apis列出分类下的接口A
列出某个接口分类下的所有 API(名称、路由、docId)。
| Name | Required | Description | Default |
|---|---|---|---|
| category | Yes | 分类名称或分类ID,例如「订单API」或「4」 |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It implies a read-only listing operation but does not explicitly state non-mutating behavior, error cases, pagination, or limits. For a simple list tool, it is adequate but lacks explicit safety or boundary details.
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 a single, concise sentence that is front-loaded with the core action and resource, and includes the essential returned fields. No wasted words.
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 one-parameter tool with no output schema and no annotations, the description is nearly complete. It explains the action, the input context, and the output fields. Minor gaps like pagination or invalid-category behavior are not critical for basic usage, but the lack of any explicit read-only note leaves a small gap.
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 100% – the single parameter 'category' is already fully described in the schema. The description adds no extra parameter semantics beyond what the schema provides, so the baseline of 3 applies.
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 verb 'list' and the resource 'all APIs under a category', and specifies the returned fields (name, route, docId). This distinguishes it from sibling tools like list_categories or search_apis without ambiguity.
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 provides no guidance on when to use this tool versus the alternatives (list_categories, search_apis, get_api_doc). It only states what it does, leaving the agent to infer selection based on the tool name and context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_categories列出接口分类A
列出聚水潭开放平台 API 的全部分类(如 基础API、订单API、库存API…)及每个分类的接口数量。推荐作为浏览文档的第一步。
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses that the tool returns all categories and per-category interface counts, which is useful behavioral context. However, it does not mention whether the data is cached, whether it requires authentication, or what happens if the API list is unavailable. For a simple read-only listing tool with no annotations, this is adequate but not rich.
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 a single, compact sentence that front-loads the main purpose and includes concrete examples of categories. The recommendation is appended naturally without bloat. Every word earns its place.
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 zero-parameter, no-output-schema listing tool, the description is nearly complete: it states what is returned (categories and counts) and when to use it. The only minor gap is the lack of mention of authentication or data freshness, but these are not critical for a simple category listing tool.
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 tool has zero parameters, so there is no parameter semantics burden. The description adds value by explaining what the output contains (categories and counts), which is the closest equivalent to parameter/output semantics. Baseline 4 for zero-parameter tools is appropriate.
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 states a specific verb ('列出' = list), a clear resource ('聚水潭开放平台 API 的全部分类'), and the key content (categories like 基础API, 订单API, 库存API plus each category's interface count). It also distinguishes itself from siblings by framing this as the first step in browsing documentation, which differentiates it from list_apis/search_apis/get_api_doc.
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 recommends this tool as the first step for browsing the documentation ('推荐作为浏览文档的第一步'), giving clear context for when to use it. It does not explicitly name alternatives or state when not to use it, but the recommendation plus the sibling names (list_apis, search_apis, get_api_doc) make the usage context clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
refresh_data刷新文档数据A
从聚水潭开放平台官方文档站重新抓取全部 API 文档并更新本地快照(约 175 个接口,需要网络,耗时约 10-30 秒)。首次使用或文档可能已更新时调用。
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does well: it discloses network dependency, expected duration (10-30 秒), and the side effect of updating the local snapshot. It does not mention error handling or the exact nature of the local write, but the main behavioral traits are transparent enough for an agent to anticipate cost and effect.
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 a single, well-structured sentence that front-loads the action and scope, then adds key operational details (network, duration, invocation timing). Every clause contributes useful information without redundancy.
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 zero-parameter refresh command, the description is complete: it explains what is refreshed, how many interfaces are affected, practical constraints (network/time), and when to invoke it. No output schema exists, but nothing about the return value is essential for deciding whether to call this tool.
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 tool has zero parameters, so there is no parameter semantic burden on the description. The description implicitly confirms that the call takes no input and only performs a refresh action, matching the baseline for a no-parameter tool.
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 uses a specific verb-resource pair ('重新抓取全部 API 文档并更新本地快照') and gives a concrete scope (约 175 个接口). It clearly differentiates itself from the sibling query/lookup tools, since this is a snapshot refresh operation rather than a read/query tool.
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 when to call it: '首次使用或文档可能已更新时调用' (first use or when docs may have been updated). It provides clear context and a decision rule, though it does not explicitly name alternatives or state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_apis全局搜索接口A
按关键词搜索接口(匹配接口名称、路由、分类名),找到要调用的接口。
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | 最多返回条数,默认 20 | |
| keyword | Yes | 关键词,例如「订单上传」「shops/query」「退货」 |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
没有任何 annotations,描述承担全部行为披露责任。然而它只说明了匹配字段,未披露搜索是否大小写敏感、是否模糊匹配、返回结果的排序或分页行为、以及 limit 参数的作用。行为信息严重不足。
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?
描述只有一句话,直接说明工具用途和匹配范围,没有任何冗余。句子结构清晰,关键信息前置,符合简洁要求。
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?
对于仅有 2 个简单参数的搜索工具,描述给出了核心功能和匹配范围。但没有输出 schema,也未说明返回内容的具体形式,且未提及 limit 参数的行为。虽然基本可用,仍有明显信息缺口。
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 覆盖率为 100%,keyword 和 limit 均有明确描述和示例,因此 baseline 为 3。描述中没有额外补充参数语义,但也没有遗漏关键信息,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?
描述使用明确的动词「搜索」和资源「接口」,并具体说明匹配范围(接口名称、路由、分类名)。这与兄弟工具 list_apis(列出接口)、list_categories(分类)、get_api_doc(获取文档)能清晰区分,agent 不会被误导。
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?
描述隐含了使用场景:当用户需要按关键词查找接口时使用。但没有明确说明何时不使用,也未提及替代方案(例如浏览全部接口用 list_apis、按分类浏览用 list_categories)。缺乏明确的排除条件。
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
5 tool updates
v0.1.0- First observed
get_api_doc - First observed
list_apis - First observed
list_categories - First observed
refresh_data - First observed
search_apis
TDQS
Scored across 5 tools
Each tool serves a clear, distinct purpose: browsing categories, listing APIs within a category, searching across APIs, fetching individual docs, and refreshing the local snapshot. There is no meaningful overlap between tools.
All tool names follow the same snake_case verb_noun pattern (list_, search_, get_, refresh_). The naming convention is uniform and predictable.
Five tools is a well-scoped set for an API documentation browsing and caching server. Each tool earns its place without redundancy or bloat.
The tool surface covers the full workflow for browsing documentation: explore categories, list APIs, search for APIs, retrieve detailed docs, and refresh the underlying data. No essential operation is missing.
Maintenance
Related MCP Connectors
Tailor Platform for AI assistants: search, list and read the platform documentation.
The documentation, as a tool your agent can call: 950+ AI-dev guides. Search + fetch tools.
Discover, compare, and monitor 1,400+ APIs directly from your AI coding agent.
Directory of APIs, merchants, and tools AI agents can actually use.
Related MCP Servers
- AlicenseAqualityNot gradedmaintenanceEnables AI assistants to access and search RAP2 API documentation, allowing users to query interface details, search APIs by keywords, and retrieve repository interfaces through natural language.77 npm-
- AlicenseNot gradedqualityDmaintenanceProvides AI assistants with access to comprehensive Safaricom Daraja API documentation for all 22 M-Pesa APIs through searchable tools, enabling developers to query payment processing, transaction management, and business operations documentation.16MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI tools to search and explore API documentation from Apidog projects or OpenAPI/Swagger specifications, providing endpoint details, schemas, and project statistics through natural language queries.603 npm1ISC
- AlicenseBqualityFmaintenanceEnables searching and retrieving detailed document content from the Yuque platform through its API. It allows AI models to search for documentation and knowledge bases by keywords and access specific document details.2396 npm2MIT