内容
# Agentovka
**通过MCP实现对捷克datové schránky（ISDS）的代理访问。**
Agentovka是一个MCP服务器，允许AI代理（如Claude Desktop、Claude Code或任何MCP客户端）通过官方ISDS应用程序接口安全地与捷克**datová schránka**（数据信箱）交互，同时确保系统的法律语义得到正确处理。
> **不是一个简单的SOAP封装。** ISDS具有法律含义，一个简单的客户端可能会无意中违反这些含义。读取您的收件箱**会触发法律交付**，并启动法定时效；消息在**90天后永久删除**；发送消息是一种**法律行为**。Agentovka将这些事实编码到工具中。请参阅 **[docs/delivery-semantics.md](https://github.com/matuspavliscak/agentovka/blob/main/docs/delivery-semantics.md)** - 项目的核心。
[](https://github.com/matuspavliscak/agentovka/actions/workflows/ci.yml)
许可证：MIT · Python ≥ 3.11
---
## 为什么存在
ISDS应用程序接口（SOAP Web服务）可由任何邮箱所有者使用其登录凭证使用，无需事先注册。但是，API反映了系统的法律机制，而一个将数据信箱视为IMAP收件箱的代理可能会引起法律后果：
1. **读取触发交付。** 列出收到的消息（无论是通过登录还是通过API（交付事件**EV13**））- 标记收件箱中的所有消息为已交付（doručeno）并启动法定时效（上诉等）。没有无后果的“偷窥”。
2. **交付的虚拟化。** 如果没有人登录，则消息在**第10天**被视为已交付（§ 17（4）法令No. 300/2008 Coll.）。如果该天是周末或公共假日，则交付日期为下一个工作日。
3. **90天删除。** 消息在**交付后90天**永久删除。公民门户的自动存档功能**无法处理通过虚拟交付的消息** - Agentovka的本地存档功能填补了这一空白。
4. **发送是法律行为**（向公共机构提交，私法行为）。
Agentovka的价值在于在干净的、可重用的客户端之上提供安全模型和法律语义层。
## 架构
一个仓库中的两个独立层：
| 层 | 包 | 描述 |
| --- | --- | --- |
| 客户端库 | [`isds_client`](https://github.com/matuspavliscak/agentovka/tree/main/src/isds_client) | 通过ISDS SOAP接口（通过[`zeep`](https://docs.python-zeep.org)，TLS上的HTTP基本身份验证）的纯Python客户端。类型化的[`pydantic`](https://docs.pydantic.dev)模型，ZFO/CMS解析器和小型CLI。可**独立使用**，无需MCP。 |
| MCP服务器 | [`agentovka_mcp`](https://github.com/matuspavliscak/agentovka/tree/main/src/agentovka_mcp) | MCP层，位于库之上，使用官方MCP Python SDK（FastMCP），stdio传输。实现安全模型和本地存档。 |
## 安全模型
工具分为三类，反映在它们的名字，描述和MCP注释中：
### A类 - 安全，无法律后果（`readOnlyHint`）
- `search_databox(query)` - 查找收件人的邮箱（ID，名称，类型）。
- `get_databox_info()` - 关于您自己的邮箱的信息。
- `list_archived_messages()`，`read_archived_message(id)`，`search_archive(q)` - 仅从**本地存档**读取（无ISDS调用）。
- `list_sent_messages()`，`get_delivery_receipt(id)` - 已发送的消息及其交付回执。这些**不**触及接收存储，因此**不**触发交付（参见[delivery-semantics](https://github.com/matuspavliscak/agentovka/blob/main/docs/delivery-semantics.md#4-which-operations-trigger-delivery--kter%C3%A9-operace-spou%C5%A1t%C4%9Bj%C3%AD-doru%C4%8Den%C3%AD))。
- `get_delivery_deadline(delivery_date)` - 使用捷克公共假日计算交付期限（D + 10，移至下一个工作日）。
### B类 - 触发交付（事件EV13）
- `list_received_messages(...)`，`download_message(id)`。
- 每个都需要一个强制性的`acknowledge_delivery_trigger: bool`参数。没有`true`，该工具将返回一个错误，解释法律后果而不是执行操作。
- `download_message`获取签名的消息（ZFO），将其存储在本地存档中，提取附件（ZFO是PKCS#7/CMS信封），并返回元数据和文本内容。
### C类 - 法律行为：发送（`destructiveHint`）
- `send_message(recipient_id, subject, attachments, dry_run=true)`。
- 默认`dry_run=true`（返回预览）。实际发送需要`dry_run=false` **和** `AGENTOVKA_ALLOW_SEND=true`在环境中。
**服务器从不主动轮询邮箱** - 没有后台作业，没有调度器。每个ISDS调用仅在显式工具调用时发生。
## 安装和配置
使用[`uv`](https://docs.astral.sh/uv）运行：
```bash
uvx agentovka # 一旦发布到PyPI
# 或从克隆：
uv run agentovka
```
所有配置均通过环境变量进行 - **凭证从不作为工具参数接受**（它们会泄漏到LLM上下文中）：
```bash
ISDS_USERNAME=...
ISDS_PASSWORD=...
ISDS_ENV=test # 测试 | 生产 （默认值：测试）
AGENTOVKA_ARCHIVE_DIR=~/.agentovka/archive
AGENTOVKA_ALLOW_SEND=false # 默认：禁用发送
```
`ISDS_ENV=test` 默认是为了安全 - 没有人应该意外地在生产环境中发送邮件。测试环境是免费的：在 **[datovka-test.gov.cz](https://www.datovka-test.gov.cz)** 创建一个测试邮箱（SOAP主机 `ws1.czebox.cz`）。
### Claude Desktop / Claude Code
将以下内容添加到您的MCP客户端配置（例如 `claude_desktop_config.json`）：
```json
{
"mcpServers": {
"agentovka": {
"command": "uvx",
"args": ["agentovka"],
"env": {
"ISDS_USERNAME": "your-test-username",
"ISDS_PASSWORD": "your-test-password",
"ISDS_ENV": "test",
"AGENTOVKA_ALLOW_SEND": "false"
}
}
}
}
```
参见 [`examples/`](https://github.com/matuspavliscak/agentovka/tree/main/examples) 获取可直接复制的配置。
## 独立使用库
```python
from isds_client import IsdsClient, IsdsEnvironment
client = IsdsClient(username="...", password="...", environment=IsdsEnvironment.TEST)
print(client.get_owner_info())
# 在没有网络访问的情况下解析ZFO文件：
from isds_client.zfo import parse_zfo
parsed = parse_zfo(open("message.zfo", "rb").read())
print(parsed.envelope, parsed.files)
```
命令行界面：
```bash
isds-client owner-info
isds-client find "Ministerstvo vnitra"
isds-client parse message.zfo # 离线
```
## 开发
```bash
uv sync --group dev
uv run pytest # 单元测试（模拟SOAP）
uv run ruff check .
uv run mypy
# 针对测试环境的集成测试（需选择加入）：
AGENTOVKA_RUN_INTEGRATION=1 ISDS_USERNAME=... ISDS_PASSWORD=... uv run pytest -m integration
```
参见 [CONTRIBUTING.md](https://github.com/matuspavliscak/agentovka/blob/main/CONTRIBUTING.md)。
## 先前作品和致谢
- WSDL/XSD模式文件是ISDS接口描述，由CZ.NIC的[dslib](https://github.com/yarda/dslib)（LGPL）分发。
- ZFO/CMS处理遵循[libdatovka](https://gitlab.nic.cz/datovka/libdatovka)和Datovka桌面应用程序（CZ.NIC）的维护参考实现，以及诸如[isds-unpack](https://github.com/adh/isds-unpack)之类的纯Python参考实现。
---
## ⚠️ 免责声明
**Agentovka是一个独立的开源项目。** 名称*Agentovka*是*datovka*（数据信箱）的衍生词。
**该项目不是一项法律服务。** 有关交付、交付虚拟化、截止日期和存档的信息仅供工程背景下参考，可能被简化或过时。这不是法律建议。对于具有约束力的信息，请咨询ISDS运营规则（Provozní řád ISDS）、相关法规或合格律师。
在理解每个工具的法律后果之前，请使用**测试环境**。您负责您发送的内容以及您的读取设置启动的截止日期。
---
## Česky
**Agentovka** 是MCP服务器，允许AI代理（Claude Desktop，Claude Code，任意MCP客户端）通过官方ISDS应用程序接口安全地与捷克**数据信箱**交互，同时确保系统的法律语义得到正确处理。
### 为什么它不是一个简单的SOAP封装
ISDS具有法律含义，一个简单的客户端可能会无意中违反这些含义：
1. **读取触发交付。** 读取收件箱（通过登录或API）会触发交付并启动法定时效。
2. **交付虚拟化。** 如果没有人登录，消息将在第10天被视为已交付。
3. **90天删除。** 消息在交付后90天永久删除。
4. **发送是法律行为。**
详细内容及来源： **[docs/delivery-semantics.md](https://github.com/matuspavliscak/agentovka/blob/main/docs/delivery-semantics.md)**。
### 安全模型
- **A类（安全）：** `search_databox`, `get_databox_info`, 读取本地存档, `list_sent_messages`, `get_delivery_receipt`, `get_delivery_deadline`.
- **B类（触发交付）：** `list_received_messages`, `download_message` - 需要 `acknowledge_delivery_trigger=true` 参数，否则将返回一个错误，解释法律后果。
- **C类（法律行为）：** `send_message` - 默认 `dry_run=true`; 实际发送需要 `dry_run=false` **和** `AGENTOVKA_ALLOW_SEND=true`.
服务器从不主动轮询邮箱。所有操作仅在显式工具调用时发生。
### 配置
仅通过环境变量进行配置（登录凭证从不作为工具参数流动到LLM上下文中）。默认 `ISDS_ENV=test` 是一个故意的安全功能。测试邮箱可免费在 [datovka-test.gov.cz](https://www.datovka-test.gov.cz) 获取。
### 注意事项
Agentovka是一个独立的开源项目。名称是*datovka*的派生词。
**该项目不是一项法律服务。** 提供的信息不是法律建议。使用**测试环境**直到您理解每个工具的法律后果。
