内容
# mcp-sri
[](https://github.com/smooth-coder/sri-mcp/releases)
[](https://github.com/smooth-coder/sri-mcp/commits/main)
[](LICENSE)
[](https://github.com/smooth-coder)
一个用于检索厄瓜多尔 SRI（Servicio de Rentas Internas）接收文档和授权文档 XML 的 MCP（Model Context Protocol）服务器。
## 功能
- 使用灵活的日期过滤（年、月、日）从 SRI 门户列表中检索接收的文档
- 通过 SRI SOAP 网络服务使用 `claveAcceso` 下载授权文档 XML
- 通过 Playwright Firefox 进行无头浏览器自动化（可选可见模式）
- 验证码检测 - 返回一个包含错误信息的类型错误，而不尝试解决它
- 无状态 - 跨调用时不保留任何文档、报告或凭证
- 标准输入输出传输 - 与任何 MCP 客户端兼容
## 工具
| 工具 | 需要凭证 | 描述 |
| --- | --- | --- |
| `list_received_documents` | 是（`SRI_USER` + `SRI_PASSWORD`） | 列出给定年份的接收文档，可选月份和日期过滤器 |
| `get_received_document_xml` | 否 | 使用 49 位 `claveAcceso` 检索单个文档的授权 XML |
## 工具详情
### `list_received_documents`
列出给定 RUC 和日期范围的 SRI 门户接收文档。
**输入**
| 字段 | 类型 | 必需 | 备注 |
| --- | --- | --- | --- |
| `year` | 字符串 | 是 | SRI 门户公开的 5 年中的一个，年份最新者优先（动态生成于服务器启动时）。示例：`"2026"`、`"2025"`、`"2024"`、`"2023"`、`"2022"` |
| `month` | 字符串 | 否 | 西班牙语月份名称，首字母大写：`"Enero"` .. `"Diciembre"`。省略以查询所有 12 个月 |
| `day` | 数字 | 否 | 整数，1-31。与 `month` 结合使用时，在该月份内限定；不与 `month` 结合使用时，在所有 12 个月份中限定该日期（例如 `{ year: "2026", day: 15 }` 查询 2026 年每个月的第 15 天） |
**执行操作**
1. 将日期范围扩展为一个或多个月度周期（给定 `year` 时为 12 个周期）。
2. 通过 Playwright（默认为无头；如果要查看，请设置 `SRI_HEADLESS=false`）启动 Firefox 浏览器。
3. 使用配置的 SRI 凭证登录 SRI recibidos 门户。
4. 对于每个周期：搜索日期范围，下载“Descargar reporte”TXT，并将其解析为文档记录。
5. 返回一个合并的 `DocumentRecord` 对象列表，每个对象包含一个 49 位的 `claveAcceso`。
**CAPTCHA_DETECTED 行为：** 如果 SRI 门户在登录或搜索期间呈现验证码，工具将返回一个包含验证码消息的错误结果（工具从不尝试解决验证码）。
**无持久性：** 浏览器总是在 `finally` 块中关闭。不会在任何地方存储文档、报告或凭证。
### `get_received_document_xml`
检索单个接收文档的授权 XML。
**输入**
| 字段 | 类型 | 必需 | 备注 |
| --- | --- | --- | --- |
| `claveAcceso` | 字符串 | 是 | 49 位文档访问密钥 |
**执行操作**
1. 调用 SRI `AutorizacionComprobantesOffline` SOAP 网络服务。
2. 返回 `AUTORIZADO` comprobante XML 和文件名（`{claveAcceso}.xml`）。
**端点：** 默认使用 SRI 生产环境 URL `https://cel.sri.gob.ec/comprobantes-electronicos-ws/AutorizacionComprobantesOffline`。可使用环境变量 `SRI_WS_ENDPOINT` 重写。
**错误：** `WEBSERVICE_ERROR` 结果包括 SRI `estado` 和 `mensajes`。无效（非 49 位）的 `claveAcceso` 在调用服务之前被输入验证拒绝。
## 安装
两种运行服务器的方式：
| | 二进制文件 | Bun |
| --- | --- | --- |
| 所需运行时 | 无 | [Bun](https://bun.sh) ≥ 1.3 |
| 最适合 | 使用服务器 | 贡献/开发 |
| Firefox 浏览器¹ | 是 | 是 |
¹ 仅 `list_received_documents` 需要 Firefox。`get_received_document_xml` 无需 Firefox。
### 选项 A - 下载二进制文件
从 [最新版本](https://github.com/smooth-coder/sri-mcp/releases/latest) 下载适用于您平台的二进制文件：
| 平台 | 文件 |
| --- | --- |
| macOS Apple Silicon | `mcp-sri-darwin-arm64` |
| macOS Intel | `mcp-sri-darwin-x64` |
| Linux x64 | `mcp-sri-linux-x64` |
| Linux arm64 | `mcp-sri-linux-arm64` |
| Windows x64 | `mcp-sri-windows-x64.exe` |
```bash
# macOS / Linux: 使其可执行
chmod +x mcp-sri-darwin-arm64
# 安装 Playwright Firefox - 仅需一次（用于 list_received_documents）
npx playwright install firefox
```
> **macOS Gatekeeper**：二进制文件未签名。首次运行时，macOS 可能会阻止它。前往系统设置 → 隐私和安全 → 允许它，或运行：
>
> ```bash
> xattr -d com.apple.quarantine ./mcp-sri-darwin-arm64
> ```
在下面的客户端配置中，将 `<binary>` 替换为下载文件的绝对路径。
### 选项 B - 使用 Bun 从源代码运行
```bash
git clone https://github.com/smooth-coder/sri-mcp.git
cd mcp-sri
bun install
bun run playwright:install
```
---
### Claude Desktop
配置文件：
| 操作系统 | 路径 |
| --- | --- |
| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
**二进制文件** - 合并到 `mcpServers` 对象：
```json
{
"mcpServers": {
"mcp-sri": {
"command": "/absolute/path/to/mcp-sri-darwin-arm64",
"env": {
"SRI_USER": "your-cedula-or-ruc",
"SRI_PASSWORD": "your-password"
}
}
}
}
```
**Bun** - 合并到 `mcpServers` 对象：
```json
{
"mcpServers": {
"mcp-sri": {
"command": "bun",
"args": ["run", "src/index.ts"],
"cwd": "/absolute/path/to/mcp-sri",
"env": {
"SRI_USER": "your-cedula-or-ruc",
"SRI_PASSWORD": "your-password"
}
}
}
}
```
### Claude Code
**二进制文件** - 通过 CLI 添加（运行一次）：
```bash
claude mcp add mcp-sri \
--command /absolute/path/to/mcp-sri-darwin-arm64 \
--env SRI_USER=your-cedula-or-ruc \
--env SRI_PASSWORD=your-password
```
或手动添加到 `~/.claude/settings.json`（全局）或 `.claude/settings.json`（项目范围）：
```json
{
"mcpServers": {
"mcp-sri": {
"command": "/absolute/path/to/mcp-sri-darwin-arm64",
"env": {
"SRI_USER": "your-cedula-or-ruc",
"SRI_PASSWORD": "your-password"
}
}
}
}
```
**Bun** - 通过 CLI 添加（运行一次）：
```bash
claude mcp add mcp-sri \
--command bun \
--args "run /absolute/path/to/mcp-sri/src/index.ts" \
--env SRI_USER=your-cedula-or-ruc \
--env SRI_PASSWORD=your-password
```
或手动添加到 `~/.claude/settings.json`:
```json
{
"mcpServers": {
"mcp-sri": {
"command": "bun",
"args": ["run", "src/index.ts"],
"cwd": "/absolute/path/to/mcp-sri",
"env": {
"SRI_USER": "your-cedula-or-ruc",
"SRI_PASSWORD": "your-password"
}
}
}
}
```
### Cursor
配置文件：`.cursor/mcp.json`（项目范围）或 `~/.cursor/mcp.json`（全局）。
**二进制文件：**
```json
{
"mcpServers": {
"mcp-sri": {
"type": "stdio",
"command": "/absolute/path/to/mcp-sri-darwin-arm64",
"env": {
"SRI_USER": "your-cedula-or-ruc",
"SRI_PASSWORD": "your-password"
}
}
}
}
```
**Bun** - Cursor 的 stdio 配置没有 `cwd` 字段，因此仓库路径放在 `args` 中：
```json
{
"mcpServers": {
"mcp-sri": {
"type": "stdio",
"command": "bun",
"args": ["run", "/absolute/path/to/mcp-sri/src/index.ts"],
"env": {
"SRI_USER": "your-cedula-or-ruc",
"SRI_PASSWORD": "your-password"
}
}
}
}
```
如果 `.cursor/mcp.json` 位于仓库内，则 `${workspaceFolder}` 替换硬编码路径：`"args": ["run", "${workspaceFolder}/src/index.ts"]`。
### OpenClaw
**二进制文件：**
```json
{
"mcpServers": {
"mcp-sri": {
"command": "/absolute/path/to/mcp-sri-darwin-arm64",
"env": {
"SRI_USER": "your-cedula-or-ruc",
"SRI_PASSWORD": "your-password"
}
}
}
}
```
**Bun:**
```json
{
"mcpServers": {
"mcp-sri": {
"command": "bun",
"args": ["run", "src/index.ts"],
"cwd": "/absolute/path/to/mcp-sri",
"env": {
"SRI_USER": "your-cedula-or-ruc",
"SRI_PASSWORD": "your-password"
}
}
}
}
```
### 验证
重启客户端并确认两个工具均已列出：`list_received_documents` 和 `get_received_document_xml`。要测试而无需完整客户端，请运行 MCP 检查器：
```bash
# 二进制文件：
npx @modelcontextprotocol/inspector /absolute/path/to/mcp-sri-darwin-arm64
# Bun:
npx @modelcontextprotocol/inspector bun run src/index.ts
```
## 配置
### 环境变量
| 变量 | 必需 | 使用者 | 描述 |
| --- | --- | --- | --- |
| `SRI_USER` | 是\* | `list_received_documents` | SRI 门户用户（cédula, RUC 或 pasaporte）。仅需使用 `list_received_documents`。 |
| `SRI_PASSWORD` | 是\* | `list_received_documents` | SRI 门户密码。仅需使用 `list_received_documents`。 |
| `SRI_HEADLESS` | 否 | `list_received_documents` | 设置为 `false` 以查看 Playwright Firefox 浏览器。默认为 `true`（无头）。仅支持 `true` / `false`；任何其他值均无效。 |
| `SRI_WS_ENDPOINT` | 否 | `get_received_document_xml` | 重写 `get_received_document_xml` 的 SOAP 端点（默认为 SRI 生产环境 URL）。 |
\* 仅 `list_received_documents` 需要。服务器在没有它们的情况下启动，`get_received_document_xml` 无论如何都有效。如果未设置 `list_received_documents` 和两者，返回错误结果而不是尝试登录。
> 将凭证保存在客户端配置或环境中 - 永远不要将其粘贴到聊天中。服务器永远不会记录它们。
## 传输
此服务器仅使用 **stdio** 传输。MCP 客户端生成进程并通过 stdin/stdout 进行通信。没有 HTTP 服务器，没有要绑定的端口，也没有要管理的持久进程 - 客户端拥有生命周期。
要手动启动服务器（用于检查或调试）：
```bash
# 二进制文件：
./mcp-sri-darwin-arm64
# Bun:
bun run dev
```
## 开发
### 先决条件
- [Bun](https://bun.sh) 1.3+
- Playwright Firefox 浏览器（通过以下命令安装）
### 安装
```bash
bun install
bunx playwright install firefox
```
### 类型检查
```bash
bun run typecheck
```
### 校验
```bash
bun run lint
```
### 格式化
```bash
bun run format:check
# 或修复所有内容：
bun run format
```
### 测试
```bash
bun run test
```
## 手动验证检查清单
1. **启动服务器并连接。** 运行 `bun run dev`（或直接执行二进制文件）并使用 [`@modelcontextprotocol/inspector`](https://github.com/modelcontextprotocol/inspector)（或任何 MCP 客户端）连接。确保双方都已连接。
2. **列表文档。** 确保 `SRI_USER` 和 `SRI_PASSWORD` 已设置在您的环境中，然后调用 `list_received_documents` 并带年份。确认响应包含具有 49 位 `claveAcceso` 值的行。
3. **获取文档 XML。** 取自步骤 2 的 `claveAcceso` 并调用 `get_received_document_xml`。确认响应是有效的 `AUTORIZADO` XML。
4. **错误情况。** 测试验证码场景（期望 `CAPTCHA_DETECTED` 错误）并调用 `get_received_document_xml` 并使用无效的 clave（期望 web 服务错误）。
## 注意事项
- **无状态：** 没有文档或凭证持久性。每个调用都从头开始并自行清理。
- **凭证永远不会被记录。** 错误信息永远不会包含 RUC、用户名或密码。
## 免责声明
本项目是一个独立的、非官方的工具，与厄瓜多尔的 **Servicio de Rentas Internas（SRI）** 无任何关联、认可或关联。
该工具仅与公开的 SRI 系统交互，以检索属于已认证用户的文档。它仅用于个人、合法和负责任的使用。
**作者不承担以下责任：
- 滥用此工具或其输出的任何行为。
- 对 SRI 系统的任何中断、降级或意外影响。
- 因使用违反 SRI 服务条款或厄瓜多尔适用法律而产生的任何后果。
用户全权负责确保其使用此工具的行为符合所有适用法律和法规。该工具旨在进行最少数量的请求以满足其预期用途 - 它不会进行批量抓取、压力测试或任何旨在降低 SRI 基础设施的措施。
