内容
# drebedengi-mcp
Drebedengi SOAP API 的 MCP 服务器。
该服务器提供了用于余额、参考列表、交易、变更和写操作（支出、收入、转账、标签）的 MCP 工具。写工具默认禁用，必须显式启用。
货币字段（`sum`、`difference`）以小单位的原始整数字符串（戈比、提因、美分）返回。 除以 100 以获取主单位金额。
## 安全
读工具始终可用。写工具在 `DREBEDENGI_ALLOW_WRITES=true` 环境变量后面，并且除非显式启用，否则不会注册。
凭证仅从进程环境中读取。它们不作为 MCP 工具参数接受。
## 配置
必需的环境变量：
- `DREBEDENGI_API_ID`
- `DREBEDENGI_LOGIN`
- `DREBEDENGI_PASSWORD`
可选环境变量：
- `DREBEDENGI_WSDL_URL`，默认为 `https://www.drebedengi.ru/soap/dd.wsdl`
- `DREBEDENGI_TIMEOUT_SECONDS`，默认为 `30`
- `DREBEDENGI_ALLOW_WRITES`，默认为 `false` — 设置为 `true` 以启用写工具
对于本地手动运行，请复制 `.env.example` 到 `.env` 并填写您的凭证。对于 MCP 客户端使用，请通过客户端的 `mcpServers` 配置传递这些变量。
## MCP 客户端配置
示例：
```json
{
"mcpServers": {
"drebedengi": {
"command": "uv",
"args": [
"--directory",
"/home/koktut/projects/drebedengi_mcp",
"run",
"drebedengi-mcp"
],
"env": {
"DREBEDENGI_API_ID": "...",
"DREBEDENGI_LOGIN": "...",
"DREBEDENGI_PASSWORD": "..."
}
}
}
}
```
## 开发
安装依赖：
```bash
uv sync --extra dev
```
运行测试：
```bash
uv run --extra dev python -m pytest
```
运行 MCP 服务器：
```bash
uv run drebedengi-mcp
```
服务器代码中不要打印到 stdout。Stdio MCP 使用 stdout 进行 JSON-RPC 协议消息。
## 工具
### 读工具（始终可用）
- `drebedengi_healthcheck` — 验证凭证并返回当前服务器修订版。
- `drebedengi_get_current_revision` — 返回当前 Drebedengi 服务器修订版。
- `drebedengi_get_balance` — 返回按地点/账户的余额。可选过滤器：`rest_date`、`is_with_accum`、`is_with_duty`。
- `drebedengi_list_currencies` — 返回货币。可选过滤器：`ids`。
- `drebedengi_list_categories` — 返回支出/收入类别。可选过滤器：`ids`。
- `drebedengi_list_sources` — 返回收入来源。可选过滤器：`ids`。
- `drebedengi_list_places` — 返回地点/账户。可选过滤器：`ids`。
- `drebedengi_list_tags` — 返回标签。可选过滤器：`ids`。
- `drebedengi_list_transactions` — 返回按 `ids` 或报告/导出过滤器的记录。
常见的导出过滤器：`r_period`、`is_report`、`is_show_duty`、`r_how`、`r_what`、
`r_currency`、`r_is_place`、`r_is_tag`。
- `drebedengi_get_changes` — 返回已知 `revision` 之后的更改。
### 写工具（需要 `DREBEDENGI_ALLOW_WRITES=true`）
- `drebedengi_add_expense` — 记录支出交易。
- `drebedengi_add_income` — 记录收入交易。
- `drebedengi_add_transfer` — 记录账户之间的转账（创建两个关联记录）。
- `drebedengi_set_record` — 更新现有的交易记录。
- `drebedengi_delete_record` — 按 ID 删除交易记录。
- `drebedengi_create_tag` — 创建新标签。
对于简单的交易导出，请使用与 Drebedengi 的 SOAP 示例相同的过滤器形状：
```json
{
"r_period": 8,
"is_report": false,
"is_show_duty": true,
"r_how": 1,
"r_what": 6,
"r_currency": 0,
"r_is_place": 0,
"r_is_tag": 0
}
```
## WSDL 覆盖
Drebedengi WSDL (`dd.wsdl`) 暴露了 34 个操作。该服务器实现了 12 个操作。
### 已实现
| WSDL 操作 | MCP 工具 |
|---|---|
| `getCurrentRevision` | `drebedengi_get_current_revision` |
| `getBalance` | `drebedengi_get_balance` |
| `getCurrencyList` | `drebedengi_list_currencies` |
| `getCategoryList` | `drebedengi_list_categories` |
| `getSourceList` | `drebedengi_list_sources` |
| `getPlaceList` | `drebedengi_list_places` |
| `getTagList` | `drebedengi_list_tags` |
| `getRecordList` | `drebedengi_list_transactions` |
| `getChangeList` | `drebedengi_get_changes` |
| `setRecordList` | `drebedengi_add_expense`、`drebedengi_add_income`、`drebedengi_add_transfer`、`drebedengi_set_record` |
| `setTagList` | `drebedengi_create_tag` |
| `deleteObject` | `drebedengi_delete_record` |
### 未实现
**参考列表管理（写）：** `setCategoryList`、`setSourceList`、`setPlaceList`、`setCurrencyList`、`setAccumList`
**累积和订单（读）：** `getAccumList`、`getOrderList`
**检查（收据）：** `getCheckList`、`setCheckList`、`getCheckToRecordList`、`setCheckToRecordList`
**数据解析：** `parseTextData`、`parsePushData`
**账户/服务：** `getAccessStatus`、`getRightAccess`、`getExpireDate`、`getSubscriptionStatus`、`getServerSubs`、`getUserIdByLogin`、`setPaymentTransaction`、`userRegister`
**危险：** `deleteAll`
## SOAP 兼容性
Drebedengi 的 WSDL 声明了几个参数和响应为 `xsd:anyType`，但服务期望 SOAP 编码数组和 `xml-soap:Map` 值。客户端在发送请求之前规范化 `params` 和 `idList`，并在返回 MCP 工具结果之前将 XML 响应项转换为 JSON 兼容的 Python 字典。
## 真实 API 烟雾测试
默认测试不会调用真实的 Drebedengi API。任何真实的网络烟雾测试都必须选择加入并标记为 `@pytest.mark.smoke`。
手动真实数据烟雾检查应使用 `.env` 或进程环境中的凭证。保持输出摘要高级别，不要打印原始财务记录：
```bash
uv run --extra dev python -m pytest
uv run --extra dev drebedengi-mcp
```
