内容
# 工具列表
> [English version](README.en.md)
>
> **如果你正在使用MySklad进行核算，给AI一个直接访问你的账户的权限。** 一个
> MCP服务器覆盖JSON API 1.2 MySklad：库存，商品，订单，客户，
> 报告（利润，营业额，资金）和**记录文档**（收货，发货，
> 订单，发票，退货）- 直接通过API，不通过浏览器。数字来自
> **真实的API**，而不是由模型编造。 **两个写入关口**不会
> 随机创建或执行文档在战斗核算。自动分页，多账户，俄语搜索。对于
> Claude Code，Cursor，Codex，Cowork和Claude Desktop。
> ⚠️ **alpha.** 帮助核算操作，但这是一个工具，而不是会计师的替代品。
> 核心和记录切片已经在测试账户中验证；
> 从文档中导入的方法是侦察地图（路径可靠，写入请求正文请参考文档或调用`ms_call_raw`）。
> 详细信息请参见“注意事项”部分。
## 为什么需要这个
核算生活在MySklad，但AI助手通常无能为力：要么通过浏览器访问，
要么编造数字，而这些数字听起来很有说服力。 `moysklad-mcp-ru`
给代理人**直接访问您账户的JSON API 1.2**：
- **来自真实API的数字，而不是模型编造的。** 库存，订单，利润，
营业额-这是MySklad的答案，来源和字段。
- **两个写入关口。** 创建文档会创建一个**草稿**；
执行（移动核算）是一个单独的破坏性步骤，需要确认。 记录被显式启用之前是禁用的。
- **无需浏览器。** 直接HTTPS调用令牌。
## 内部结构
**不是“一个工具对应一个端点”，而是8个通用元工具覆盖目录** -
完整的API覆盖，小表面。
```
你的AI代理
│
▼
8个元工具 ──► 目录（endpoints.yaml） ──► 通用核心
search / describe / 客户端 · 安全 · 错误
call / call_raw / 分页 · 注册
fetch_all / map / ... │
+ 类型化的工具（ms_get_stock, ms_create_document, …） ▼
MySklad JSON API 1.2（HTTPS）
```
**元工具**（`ms_search_methods`, `ms_describe_method`, `ms_call_method`,
`ms_call_raw`, `ms_fetch_all`, `ms_map`, + 账户工具）。
**类型化的读取工具：** `ms_get_stock`, `ms_get_products`, `ms_get_orders`,
`ms_get_profit`, `ms_get_money`, `ms_get_turnover`, `ms_get_counterparties`,
`ms_get_stores`, `ms_get_documents`（7种），`ms_ping`. 自动将美分转换为卢布。
**写入工具（两个关口）：**
| 工具 | 级别 | 用途 |
|---|---|---|
| `ms_build_document` | 读取 | 预览任意类型：解析链接 + 精确主体，不记录。 |
| `ms_create_document` | 写入 | 创建任意角色类型的**草稿**（`applicable:false`）。 |
| `ms_build_purchaseorder` / `ms_create_purchaseorder` | 读取/写入 | 供应商订单（兼容性）。 |
| `ms_post_document` | 破坏性 | 执行文档（`applicable:true`）- 移动核算。 |
| `ms_delete_document` | 破坏性 | 删除文档（清理）。 |
7种角色类型：`purchaseorder`, `supply`, `demand`, `invoicein`, `invoiceout`,
`salesreturn`, `purchasereturn`.
**目录 - 来自MySklad官方文档的schema驱动：** 892种方法（核心经过验证；
其余从文档导入）。 `ms_call_raw`获取目录中尚未涵盖的所有内容。
## 可以问什么
```
显示库存和需要补充的商品
提取上个月商品的利润
哪些客户欠我们钱
创建一个收货单：10个“Roga”来自“LLC供应商”按250₽ （在测试账户中）
执行此收货单并显示库存如何变化
```
不确定从哪里开始 - 说**“您能对我的账户做什么”** 或调用`ms_map`.
## 安全模型
账户令牌移动库存和资金。每个方法都分类：
- **读取** → 立即执行；
- **写入**（创建草稿）→ 需要`confirm_write=true` **和** 已启用写入`MOYSKLAD_ALLOW_WRITE=1`；
- **破坏性**（执行/删除）→ 还需要`i_understand_this_modifies_data=true`.
**两个独立层：** （1）进程防护（`MOYSKLAD_ALLOW_WRITE`，默认关闭，
带有`MOYSKLAD_WRITE_CABINETS`选项）；（2）每个调用防护。防护涵盖原始`ms_call_method`/
`ms_call_raw`，不仅是类型化的工具。 **0个突变标记为读取** -
通过CI中的`test_safety_catalog`测试。 创建始终创建**草稿**；
执行是一个单独的步骤。
## 安装
详细指南见 **[QUICKSTART.md](QUICKSTART.md)**. 三种方法，效果相同：
1. **最简单 - 请求您的AI（无需终端）。** 打开Claude / Cowork并
说：*“安装MySklad MCP”* - 代理将引导您完成内置的`install-skill/`。
2. **下载并点击。** 获取release-zip，解压， 双击
`install.command`（macOS）/ `install.bat`（Windows），输入令牌。
3. **技术方法。** `python3 install.py --client <您的客户端>`（claude-desktop /
claude-code / codex / opencode）。
4. **对于开发人员。** PyPI上的软件包 - 无需安装即可运行：`uvx moysklad-mcp-ru`.
对于Claude Desktop - 一个现成的`.mcpb`包来自
[发布](https://github.com/ilyautov/moysklad-mcp-ru/releases)（双击，
在设置窗口中输入令牌）。完整的分发列表和发布剪辑方法见
**[docs/DISTRIBUTION.md](docs/DISTRIBUTION.md)**.
对于方法1-3，不需要`pip install`或JSON编辑: 依赖项在首次启动时自动安装（本地venv），您只需提供令牌。
**从哪里获取令牌：** MySklad → 设置 → 用户 → 访问令牌。令牌
存储在`~/.moysklad-mcp/cabinets.json`（本地，chmod 600，绝不进入存储库
或聊天）。支持**多账户** - 带有聊天切换的多个账户（`ms_add_cabinet` / `ms_use_cabinet`）。
**安装后检查:** `python3 serve.py ms --selfcheck` → “OK: ms ready, N tools”.
## 资金
API中的所有金额均以美分表示。 读取工具返回卢布。 在写入
`convert_money_to_kopecks`将价格/金额从卢布转换为美分（`price`位置，
`sum`，价格对象）。原始元工具以美分工作。
## 验证战斗
- 主机`api.moysklad.ru/api/remap/1.2`，列表在`rows`，offset+limit（最大1000）。
- 限制：**45/3秒**，窗口3000毫秒，重型库存报告消耗5单位。
- 严格：`Accept: application/json;charset=utf-8`恰好（否则返回400代码1062），
`Accept-Encoding: gzip`（否则415）。
## 注意事项（与实时文档核对）
- **从文档导入的方法：路径可靠，正文写入不可靠。** 将它们视为
侦察地图：根据文档或通过`ms_call_raw`确认。 核心和记录切片已验证。
- **账户遮蔽环境变量：** 活动账户中的`cabinets.json`优先于
环境变量。 未解释的401 - 首先检查存储库。
- **仅在测试账户上记录。** 不要将`MOYSKLAD_ALLOW_WRITE=1`发送到
战斗核算，直到您自己在测试中检查。
## 结构
```
core/ ← 供应商引擎 ilyautov/marketplaces-mcp-ru（MIT，未更改）
moysklad_mcp/ ← MySklad特定：server.py, build.py, money.py, refs.py,
write_guard.py, endpoints.yaml(+curated), workflows.yaml, entities.yaml
tests/ ← 70个离线测试
scripts/ ← ingest_moysklad.py（文档解析器），package_release.py
serve.py ← 启动器（自动venv）：python3 serve.py ms [--selfcheck]
install.py + .command/.bat/.sh + install-skill/ ← 4个客户端的安装
.mcp.json + .claude-plugin/ .codex-plugin/ .cursor-plugin/ ← 插件清单
docs/ ← 研究，审计，RUNBOOK，恢复点（开发文档）
```
## 许可证
MIT. 供应商`core/` - 在MIT下由Ilya Uotov提供，参见 [`NOTICE`](NOTICE). 架构
（schema驱动的目录，安全关口，统一错误，自动分页）重用
[marketplaces-mcp-ru](https://github.com/ilyautov/marketplaces-mcp-ru)的最佳创意。
发现问题 - 创建问题。这是一个alpha和开源代码：安装，检查您的数据，实验。
