API 文档 开放 API · 专业版智能体接入 · 免费版可用

概述与约定

• Base URL：{你的实例地址}/api/v1，例如 http://192.168.1.10:8066/api/v1；
• 响应信封：成功统一为 {"code":"OK","message":"ok","data":…}，业务数据在 data 里；错误返回 {"code":"错误码","message":…}；
• 限流：按 Token 每分钟 60 次，超限返回 429 RATE_LIMITED——脚本侧请做分页合并（分页 page_size 建议 ≤50，服务端上限 200）；
• 机器可读契约：完整接口定义见 /api/openapi.json（Swagger UI 在 /api/docs）；
• 角色：Token 继承其所属用户的角色——读接口需 viewer 及以上，写接口需 member 及以上，「报废」出库与分类 / 库位 / 供应商增删改需 admin；日期参数支持 YYYY-MM-DD。

Token 认证

1. 登录系统，进「设置 → API Token」，点「新建」；
2. Token 以 xmt_ 开头，明文只在创建时显示一次，请立即保存（落库的是哈希，丢了只能删除重建）；
3. 所有请求带请求头 Authorization: Bearer xmt_…；
4. 不用了随时在设置页停用（立即失效，之后可再启用），或直接删除。

curl -s -H "Authorization: Bearer xmt_你的Token" \
  "http://你的实例:8066/api/v1/items?page=1&page_size=5"

接口总览

以下为常用精选面，全部路径相对 /api/v1：

读接口（viewer+）

写接口（member+）

采购 · 项目 BOM · 借用（member+）

基础档案（admin）

Token 与登录会话同权限，按所属账号角色收紧或放开：删除物品、系统设置、用户与授权管理等敏感接口同样可被 Token 调用——请把 Token 当账号密码保管，只发给可信脚本，只读场景建议用 MCP 只读模式（?mode=readonly）。流水冲正可通过 Token 调用（冲正非本人流水需 admin）；MCP 工具面不含冲正，防智能体误操作连环放大。

调用示例

搜索物品

curl -s -H "Authorization: Bearer $XMT" \
  "$BASE/api/v1/items?q=M3%E8%9E%BA%E4%B8%9D&page=1&page_size=20"

建档（含期初数量）

curl -s -X POST "$BASE/api/v1/items" \
  -H "Authorization: Bearer $XMT" -H "Content-Type: application/json" \
  -d '{"name":"M3×8 内六角螺丝","model":"M3x8","type":"PRT","location_id":12,
       "unit":"颗","quantity":200,"safety_stock":50,"tags":["紧固件"]}'

入库

curl -s -X POST "$BASE/api/v1/stock/inbound" \
  -H "Authorization: Bearer $XMT" -H "Content-Type: application/json" \
  -d '{"item_id":34,"quantity":100,"total_price":25.8,"supplier_id":3,"remark":"补货"}'

Webhook

在「设置 → Webhook」配置接收地址，库存相关事件会 POST 到你的端点（JSON）。当前事件：

事件在业务事务内入队、后台轮询投递；带 HMAC-SHA256 签名头 X-Xianmu-Signature（密钥在建 Webhook 时生成），失败退避重试 3 次，投递记录可查、可发测试事件。验签示例（Python）：

import hmac, hashlib

def verify(secret: str, body: bytes, signature: str) -> bool:
    expected = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

# signature 取请求头 X-Xianmu-Signature；body 为原始请求体字节

智能体接入 免费版可用（50 条目内）· 已上线

开放 API 的产品化形态：让 AI 编码助手与通用智能体直接操作库存——问一句「A 柜还剩多少 M3 螺丝」，或说「把这批料入库到 A 柜二层」。两种形态：

• MCP（推荐，内置端点）：服务端原生 /api/mcp（Streamable HTTP），客户端只填「实例地址 + Token」即得精选工具面（查询 21 个 + 写入 46 个，覆盖物品、项目库与 BOM、采购、借用、盘点任务、基础档案、图片与资料管理与操作规范引导），零本地依赖，NAS / 远程实例同样可用；支持 ?mode=readonly 只读模式——「只让 AI 查库存」的安心开关，演示实例自动强制只读；
• Skill（技能文件）：把随发布包提供的 xianmu-ims 技能文件夹（安装版位于安装目录下的 skill\xianmu-ims\，Windows 默认 %LOCALAPPDATA%\Programs\XianMuIMS\skill\xianmu-ims\；也可从 GitHub 仓库的 skill/ 目录获取）放进 Claude Code / ZCode / Cursor 的技能目录，Agent 即按本文接口约定查库存、办出入库 / 盘点，也可跑内置「初始化引导」（几轮问答配好分类与位置），内置「写操作先确认、限流合并查询」等护栏，适合不想配 MCP 的编码类 Agent。

想让 AI 智能体全自动完成接入（装好软件、连上 MCP、配好初始分类与位置）？把这句话发给任意支持 MCP 的智能体（Claude Desktop / Cursor / WorkBuddy / Qoder 等）：英文「Read https://ims.miaoking.com/skill.md and follow the instructions to set up XianMu IMS and connect its MCP server.」或中文「读取 https://ims.miaoking.com/skill.md 并按照其中的说明，安装闲沐 IMS 并连接它的 MCP 服务器。」

MCP 工具面速览（67 个）

服务端精选 67 个工具（读 21 / 写 46），按业务域分组：

列表类工具统一返回 {total, list} 结构；不含物品删除 / 并库 / 项目删除 / 系统设置等敏感操作。

状态与护栏说明：MCP 端点已上线（服务端原生提供，Claude Desktop / Cursor 等主流客户端已实测连通）；MCP 属免费版权益（2026-09-30 起，物品条目 50 件内与专业版无差别；超限返回 LIMIT_EXCEEDED，消息自带购买直达链接）；条目不够可到 portal/buy 购买专业版（不限条目）；Skill 技能文件可免费取用，但经裸 REST 直调属专业版权益（feature.api），免费版权益的 REST Token 调用返回 403 EDITION_REQUIRED。写工具内置护栏：报废出库与基础档案（分类 / 库位 / 供应商）增删改需 admin 角色、流水冲正不开放给智能体（记错请登录界面操作）；注意 MCP 的 update_item 为部分更新语义（REST 的 PUT /items/{id} 是全量语义）。

各工具接入配置

所有 MCP 客户端接入都只需要三样东西：

• 服务地址：http://你的实例:8066/api/mcp（只读加 ?mode=readonly）；
• 请求头：Authorization: Bearer xmt_你的Token（在「设置 → API Token」创建，见 上文）；
• 类型：HTTP / Streamable HTTP（不要选 stdio / 本地命令类型）。

地址必须是运行客户端的那台机器能访问到的地址。以下示例统一用演示站 https://imsdemo.miaoking.com——登录演示站后在「设置 → API Token」创建 Token，即可直接连着试用；自建实例则填你的实例地址：同局域网客户端填 NAS / 电脑的内网 IP（如 192.168.1.10:8066），客户端装在实例本机才可用 127.0.0.1，并替换成你的实际地址与 Token。

Claude Desktop（桌面版 · 已实测连通）

1. 打开配置文件：设置 → 开发者 → 编辑配置，或直接编辑 %APPDATA%\Claude\claude_desktop_config.json（Windows）/ ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）；
2. 加入如下配置后完全退出并重启 Claude Desktop；
3. 新对话里点输入框的工具图标，应能看到「xianmu-ims」的 67 个工具。

{
  "mcpServers": {
    "xianmu-ims": {
      "url": "https://imsdemo.miaoking.com/api/mcp",
      "headers": { "Authorization": "Bearer xmt_你的Token" }
    }
  }
}

Claude Code（命令行）

在项目目录执行一条命令即可（全局可用加 --scope user）：

claude mcp add --transport http xianmu-ims "https://imsdemo.miaoking.com/api/mcp" \
  --header "Authorization: Bearer xmt_你的Token"

# 验证：列出已接入的 MCP 与工具
claude mcp list

Cursor（已实测连通）

1. 设置 → MCP & Integrations，点「New MCP Server」，Cursor 会打开 mcp.json；
2. 填入与 Claude Desktop 相同结构的配置：

{
  "mcpServers": {
    "xianmu-ims": {
      "url": "https://imsdemo.miaoking.com/api/mcp",
      "headers": { "Authorization": "Bearer xmt_你的Token" }
    }
  }
}

保存后回到 MCP 列表，xianmu-ims 显示绿色圆点即连接成功。Agent 模式下直接对话即可。

Qoder（同源配置，未逐一实测）

Qoder 同样采用 mcpServers JSON 结构：在客户端的 MCP 设置中添加服务，或直接在项目根目录放 .mcp.json，内容与上面 Cursor 的配置完全一致（入口名称随版本可能不同，认准「MCP / 工具」设置项即可）。

WorkBuddy（已实测全部工具连通）

1. 左侧导航「专家 · 技能 · 连接器」→「连接器」，进入连接器页后点「自定义连接器」（或在「MCP 服务管理」弹窗右上角点「＋ 添加 MCP」）；
2. WorkBuddy 采用标准 mcpServers JSON 配置（配置文件路径 %USERPROFILE%\.workbuddy\mcp.json，在编辑器里直接修改），填入下面的内容并保存；
3. 回到「MCP 服务管理」列表：xianmu-ims 显示绿点、工具全部显示「已启用」（当前版本 67 个）即接入成功；列表里可随时用开关启用 / 停用、刷新或删除。

{
  "mcpServers": {
    "xianmu-ims": {
      "url": "https://imsdemo.miaoking.com/api/mcp",
      "headers": { "Authorization": "Bearer xmt_你的Token" },
      "disabled": false
    }
  }
}

提示：列表页的「MCP Hub」是服务市场入口，与本接入无关；「连接器」页的搜索框用于检索已有连接器，自定义接入走「自定义连接器」按钮。

ZCode 及其他编码类客户端

ZCode 等编码类 Agent 客户端普遍兼容同一套 mcpServers JSON：在对应的 MCP 配置文件或客户端设置里添加同构配置即可。若客户端不支持远程 HTTP 型 MCP，可改用 Skill 方式——把 xianmu-ims 技能文件夹复制到其技能目录（如 ~/.claude/skills/、.zcode/skills/），Agent 会按技能文件走 REST API 操作库存，效果等价（注意：免费版权益下裸 REST 调用属专业版权益，免费版请优先使用 MCP 方式）。

Cherry Studio 等对话类客户端（同源配置，未逐一实测）

「设置 → MCP 服务器 → 添加」：类型选流式 HTTP（Streamable HTTP），URL 填服务地址，请求头填 Authorization: Bearer xmt_你的Token，开启后即可在对话中直接调用库存工具。

接入后怎么验证

1. 客户端工具列表里出现「xianmu-ims」的 67 个工具（search_items、inbound、create_project 等）；
2. 先试只读问题：「现在有多少条低库存预警？」；
3. 需要放开写入时，把地址换成完整模式重新连接；不确定就让 AI 先用只读跑几天。

接入常见问题

错误码

接口报错、文档没讲清、想要新能力：提交表单（无需登录）；集成方案咨询请联系客服（客服邮箱 kf@wwzu.com）。