内容
# iikoServer MCP 服务器
MCP（模型上下文协议）服务器，暴露 [iiko](https://iiko.ru) 餐厅管理系统 REST API，作为 42+ 个 LLM 可调用的工具，通过 stdio。
## 功能特点
- **42+ 个工具** — 产品、员工、订单、支付、OLAP 报表、组装图表
- **自动认证** — SHA1 密码哈希 + 会话 cookie，401 时重新认证
- **优雅关闭** — 发送注销以释放 iiko 许可槽
- **自签名证书支持** — 默认 `IIKO_VERIFY_SSL=false`
- **场地映射** — 可选 `IIKO_VENUE_MAP`，将收银机编号标记为名称
- **业务级助手** — `get_checks`、`get_venues_revenue`、`get_staff_meals`、`get_top_dishes`、`compare_revenue`
- **Docker 就绪** — Python 3.12-slim，stdio 协议
## 快速开始
### 本地（pip）
```bash
git clone https://github.com/your-org/iiko-server-mcp.git
cd iiko-server-mcp
pip install -r requirements.txt
```
```bash
IIKO_URL=https://your-restaurant.iiko.it:443 \
IIKO_LOGIN=your_login \
IIKO_PASS=your_password \
python3 server.py
```
### Docker
```bash
docker build -t iiko-server-mcp .
docker run -i --rm \
-e IIKO_URL=https://your-restaurant.iiko.it:443 \
-e IIKO_LOGIN=your_login \
-e IIKO_PASS=your_password \
iiko-server-mcp
```
**重要：** MCP 服务器使用 **stdio**（不是 HTTP）。容器必须使用 `-i`（交互式）运行，以便 MCP 客户端可以通过 stdin/stdout 进行通信。不要使用 `-d`（分离）。
## 配置
复制 `.env.example` 到 `.env` 并填写真实值：
| 变量 | 必需 | 默认值 | 描述 |
|---|---|---|---|
| `IIKO_URL` | **是** | — | iikoServer 基本 URL，例如 `https://my-restaurant.iiko.it:443` |
| `IIKO_LOGIN` | **是** | — | 登录用户名 |
| `IIKO_PASS` | **是** | — | 明文密码（发送前进行 SHA1 哈希） |
| `IIKO_VENUE_MAP` | 否 | — | `"Venue A=4,Venue B=5"` — 收银机编号的名称 |
| `IIKO_VERIFY_SSL` | 否 | `false` | 如果使用 CA 签名证书，则设置为 `true` |
## MCP 客户端配置
### Hermes Agent
```yaml
# ~/.hermes/config.yaml
mcp_servers:
iiko-server:
command: python3
args: ["/path/to/iiko-server-mcp/server.py"]
env:
IIKO_URL: "https://your-restaurant.iiko.it:443"
IIKO_LOGIN: "your_login"
IIKO_PASS: "your_password"
IIKO_VENUE_MAP: "Cafe A=4,Cafe B=5"
```
对于 Docker：
```yaml
mcp_servers:
iiko-server:
command: docker
args: ["run", "-i", "--rm",
"-e", "IIKO_URL=https://your-restaurant.iiko.it:443",
"-e", "IIKO_LOGIN=your_login",
"-e", "IIKO_PASS=your_password",
"iiko-server-mcp"]
```
### Claude Desktop
```json
{
"mcpServers": {
"iiko-server": {
"command": "python3",
"args": ["/path/to/iiko-server-mcp/server.py"],
"env": {
"IIKO_URL": "https://your-restaurant.iiko.it:443",
"IIKO_LOGIN": "your_login",
"IIKO_PASS": "your_password"
}
}
}
}
```
### Cursor
```json
{
"mcpServers": {
"iiko-server": {
"command": "python3",
"args": ["/path/to/iiko-server-mcp/server.py"],
"env": {
"IIKO_URL": "https://your-restaurant.iiko.it:443",
"IIKO_LOGIN": "your_login",
"IIKO_PASS": "your_password"
}
}
}
}
```
## 可用工具
### 系统
- **ping** — 健康检查，服务器 URL + 认证状态
- **list_endpoints** — 所有 42 个工具及其描述
### 产品 / 命名法
- **get_products** / **get_nomenclature** — 所有产品
- **get_product_groups** — 具有层次结构的商品类别
- **get_product_sizes** — 尺寸/单位
- **get_corporate_structure** — 部门结构
- **get_corporate_groups** — 企业集团
- **search_products** — 按名称的子字符串搜索
### 员工
- **get_employees** / **get_employee** / **get_employee_roles** / **get_persons**
### 实体
- **get_entity_types** / **get_entities** / **get_entity_by_id**
- **get_stores** — 仓库
- **get_contractors** — 供应商
### 文档
- **get_incoming_invoices** / **get_outgoing_invoices** — 按日期范围（DD.MM.YYYY）
- **get_incoming_invoice_by_id** / **get_outgoing_invoice_by_id**
- **get_waste_documents** — 报废单
- **get_menu_changes** / **get_menu_change_by_id**
### 食谱（组装图表）
- **get_assembly_charts** — 所有技术卡
- **get_assembly_chart_by_id** — 单张图表
- **save_assembly_chart** — 创建/更新（⚠️ 修改生产数据）
### 现金和支付
- **get_payment_types**
- **get_cash_shifts** / **get_cash_shift** — 按会话 UUID
- **get_payments** / **get_payment** — 每会话
- **create_encashment** — 现金出入（⚠️ 修改生产数据）
### 价格
- **get_price_categories** / **get_price_category**
### 报告和 OLAP
- **get_olap_columns** — 报表类型的架构（例如 `SALES`）
- **run_olap_report** — 带有自定义列/筛选器的原始 OLAP（DD.MM.YYYY）
- **get_olap_presets** / **run_olap_by_preset** — 已保存的预设
- **run_custom_report** — 命名自定义报告（DD.MM.YYYY）
- **get_venues_revenue** — 按场地划分的每日收入（YYYY-MM-DD）
- **get_staff_meals** — 按场地划分的免费员工餐（YYYY-MM-DD）
- **get_top_dishes** — 按收入排名前 N 的菜肴（YYYY-MM-DD）
- **compare_revenue** — 日环比收入比较
- **get_checks** — 带有支付类型和屏蔽卡的个人订单（YYYY-MM-DD）
### 原始
- **raw_request** — 对任何 iikoServer 端点的直接身份验证 HTTP 调用
## 日期格式
| 工具组 | 格式 | 示例 |
|---|---|---|
| 业务助手（`get_venues_revenue`、`get_checks` 等） | **YYYY-MM-DD** | `2026-07-17` |
| 传统 OLAP（`run_olap_report`、`run_olap_by_preset`） | **DD.MM.YYYY** | `17.07.2026` |
所有业务工具默认使用 **莫斯科时间**（UTC+3），如果未提供日期。
## 已知限制
- **`get_cash_shifts`** — 需要日期参数；目前如果不调用则返回 409
- **`get_payment_types`** — 在某些 iikoServer 版本上返回 404（端点可能不存在）
- **员工餐检测** — 按 `" (无支付)"` 支付类型标签过滤；请验证此项与您的 iiko 配置是否匹配
- **`CardTypeName`** — 根据收购商集成的不同，可能返回 `" (无卡)"`
- **自签名证书** — 默认 `verify=False`；对于 CA 签名证书，请设置 `IIKO_VERIFY_SSL=true`
## 开发
```bash
# 语法检查
python3 -m py_compile server.py
# 在测试环境中本地运行
IIKO_URL=... IIKO_LOGIN=... IIKO_PASS=... python3 server.py
# 构建 Docker
docker build -t iiko-server-mcp .
```
### 添加工具
1. 编写具有 `@tool("name", "description", input_schema)` 装饰器的处理程序
2. 在 `ENDPOINT_CATALOG` 中将 `"name"` 添加到相应的类别中
3. Python 将自动注册它 — 无需其他连接
## 许可证
MIT — 请参阅 [LICENSE](LICENSE)
