内容
<p align="center">
<img src="https://raw.githubusercontent.com/carlosplanchon/firmauy-mcp-inspect/main/assets/banner.jpg" alt="FirmaUY MCP Inspect, AI-assisted read-only inspection for Uruguayan digital signatures" width="800">
</p>
# firmauy-mcp-inspect
[](https://pypi.org/project/firmauy-mcp-inspect/)
[](https://pypi.org/project/firmauy-mcp-inspect/)
[](https://opensource.org/licenses/Apache-2.0)
[](https://deepwiki.com/carlosplanchon/firmauy-mcp-inspect)
**firmauy-mcp-inspect** 是一个小型、**只读**的 [MCP](https://modelcontextprotocol.io/) 服务器，允许 AI 助手检查使用 [FirmaUY](https://github.com/carlosplanchon/firmauy) 签署的乌拉圭身份证数字签名。它验证签名（PDF/PAdES，XAdES XML 或分离的 CMS `.p7s`）并验证身份证校验位。验证过程在离线进行，不需要智能卡。
它的存在是为了在纯命令行工具无法胜任的任务中提供帮助，即 **对一批已签署的文件进行分类**，并以易于理解的语言显示结果。将它指向一个文件夹，它会验证每个文件，按颁发机构分组，并标记所有非 VALID 或证书链不可信的文件，留给您一个摘要以便采取行动。
按照设计，它 **只进行检查**。它不能签署，从不看到 PIN，并且默认情况下会编辑签人的个人信息，因此身份信息不会进入模型的上下文中。
## 范围（仅检查，按设计）
FirmaUY 还可以 **签署** 国家身份证并 **读取持卡人数据**。该服务器故意不暴露这些功能。
- **没有签名**。使用国家身份证签署是一种具有法律意义的行为，需要物理卡和 PIN。模型永远不能触发它。签名仍然是人类手动操作。
- **没有身份或照片**。`fetch-identity` 和 `fetch-photo` 返回个人信息和生物特征数据。这些信息不应该流入模型的上下文中，因此这些命令未被暴露。
模型从验证中看到的内容 **默认情况下被编辑**。模型接收到指示、信任状态和颁发者（公共 CA），但不包括签署者的姓名或文件编号。
## 工具
| 工具 | 功能 |
|---|---|
| `verify(path, original=None, redact=True)` | 验证一个已签署的文件（PDF/PAdES，XAdES XML，分离的 CMS/.p7s）。返回指示、每个签名的信任和检查结果。 |
| `verify_batch(paths, redact=True)` | 验证多个文件。返回按指示汇总的计数和每个文件的紧凑结果（指示、受信任、颁发机构）。 |
| `validate_ci(number)` | 验证身份证的校验位（仅算术一致性，不进行身份检查）。 |
| `doctor()` | 报告本地设置状态（PC/SC，PKCS#11 模块，卡，捆绑 CA）。 |
`verify_batch` 处理自包含签名（PDF/PAdES，XAdES XML）。分离的 `.p7s` 需要其原始文件，因此请一一验证它们 `verify(path, original=...)`。
验证过程在离线进行，证书链验证最高可达乌拉圭国家根证书。`VALID` 结果是技术评估，而不是法律有效性声明。对于权威验证，请使用 [AGESIC 的官方验证器](https://firma.gub.uy/)。这是一个独立的非官方工具，与 AGESIC 无关或获得其认可。
## 要求
必须安装 `firmauy` 命令行工具并将其置于 `PATH` 中。
```bash
uv tool install firmauy
firmauy --version
```
（如果 `firmauy` 可执行文件位于其他位置，请使用 `FIRMAUY_BIN` 环境变量覆盖它。）
## 配置
所有配置项均为可选，并通过环境变量进行配置。
| 变量 | 默认值 | 用途 |
|---|---|---|
| `FIRMAUY_BIN` | （在 `PATH` 中找到） | `firmauy` 可执行文件路径，如果不在 `PATH` 中。 |
| `FIRMAUY_MCP_TIMEOUT` | `60` | 每个 `firmauy` 调用超时时间，单位为秒。 |
| `FIRMAUY_MCP_MAX_WORKERS` | `8` | `verify_batch` 中的最大并发验证数。设为 `1` 进行顺序验证。 |
| `FIRMAUY_MCP_ALLOWED_ROOTS` | 无（无限制） | 工具可以读取的目录，以操作系统的路径分隔符分隔（Linux/macOS 上为 `:`，Windows 上为 `;`）。设置后，任何目录外的路径（在解析符号链接和 `..` 之后）都会被拒绝。 |
| `FIRMAUY_MCP_ALLOWED_EXTENSIONS` | 无（无限制） | 允许的已签署文件类型，以逗号分隔，例如 `.pdf,.xml,.p7s`。不限制分离的 `.p7s` 的原始文件。 |
数字覆盖值如果格式不正确将被忽略（它会恢复为默认值），而不是导致启动失败。
### 沙盒（推荐）
该服务器将文件路径从模型传递给 `firmauy`，后者会打开它们。对于涉及国家身份证签名的工具，限制其读取内容至关重要，因此请设置这两个允许列表。它们是可选的，并且在失败时关闭。
```bash
export FIRMAUY_MCP_ALLOWED_ROOTS="/srv/inbox/signed"
export FIRMAUY_MCP_ALLOWED_EXTENSIONS=".pdf,.xml,.p7s"
```
容器检查已解析的规范路径（符号链接和 `..` 跟随），因此它不会被遍历、符号链接逃逸或具有相同前缀的 sibling 目录所欺骗。根目录允许列表也涵盖分离的 `.p7s` 的原始文件。扩展名允许列表不涵盖它，因为原始文件是任意内容。
## 安装
```bash
uv tool install firmauy-mcp-inspect
```
这将 `firmauy-mcp-inspect` 命令放入您的 `PATH` 中，该命令通过 stdio 启动服务器。您还可以直接从 PyPI 运行它，而无需安装，使用 `uvx firmauy-mcp-inspect`。
使用 MCP 检验工具进行交互式测试。
```bash
npx @modelcontextprotocol/inspector firmauy-mcp-inspect
```
如果要从克隆仓库开始，请运行 `uv sync`，然后运行 `uv run firmauy-mcp-inspect`。
## 配置客户端
以下两种形式都假设 `firmauy-mcp-inspect` 已通过 `uv tool install` 放入您的 `PATH` 中。如果 GUI 客户端无法找到它，请使用 `uvx` 作为命令（`"command": "uvx"`，`"args": ["firmauy-mcp-inspect"]`）或提供绝对路径。
**Claude 代码**
```bash
claude mcp add firmauy-inspect -- firmauy-mcp-inspect
```
**Claude 桌面版**（`claude_desktop_config.json`）
```json
{
"mcpServers": {
"firmauy-inspect": {
"command": "firmauy-mcp-inspect"
}
}
}
```
然后询问它诸如 *"验证此文件夹中的每个已签署 PDF，按颁发机构分组，并标记任何非 VALID 或证书链不可信的文件。"* 之类的问题。
## 测试
```bash
uv run pytest
```
测试模拟 `firmauy` 子进程，因此它们既不需要命令行工具也不需要卡。路径沙盒测试还创建临时文件和本地文件系统上的符号链接。
## 许可证
Apache-2.0。
