内容
# anaf-efactura-mcp
**MCP 服务器用于 ANAF e-Factura 系统（罗马尼亚）** — 直接从 SPV 创建、上传、验证和管理电子发票。
兼容 [Model Context Protocol](https://modelcontextprotocol.io)：Claude Desktop, Cursor, Windsurf, VS Code, 任何 MCP 客户端。
[](https://www.npmjs.com/package/anaf-efactura-mcp)
[](LICENSE)
[🇷🇴 简体中文](#简体中文) · [🇬🇧 English](#english) · [📘 安装指南](docs/SETUP.md) · [💡 使用示例](docs/USAGE.md)
---
## 简体中文
### 为什么存在
罗马尼亚强制所有 B2B 交易通过 ANAF 的 SPV 进行电子发票开具。此 MCP 服务器允许 AI 助手（Claude、Cursor 等）处理整个发票生命周期 — 从生成符合要求的 UBL 2.1 CIUS-RO XML 到直接上传到 ANAF API。
### 安装前 - 必要条件
1. **合格的数字证书**（USB 令牌），已在 SPV 注册。
2. **在 ANAF 注册的 OAuth 应用程序** → [logincert.anaf.ro/anaf-oauth2/v1/manager](https://logincert.anaf.ro/anaf-oauth2/v1/manager)。获取 `client_id` + `client_secret` + 声明一个真实的 HTTPS `redirect_uri`（ANAF **不**接受 `urn:ietf:wg:oauth:2.0:oob`）。
3. 浏览器中安装数字证书（Firefox 或 Chrome/Edge with ProCert）。
4. Node.js ≥ 20（用于全局 `fetch`）。
👉 **[完整安装指南](docs/SETUP.md)** — 在首次运行前阅读。
### 快速安装
#### Claude Desktop（stdio）
编辑 `claude_desktop_config.json`:
```json
{
"mcpServers": {
"anaf-efactura": {
"command": "npx",
"args": ["-y", "anaf-efactura-mcp"],
"env": {
"ANAF_ENV": "test"
}
}
}
}
```
重启 Claude Desktop。工具 `anaf_*` 将出现在列表中。
#### 远程 / PM2（HTTP 流式传输）
```bash
git clone https://github.com/hegetiby/anaf-efactura-mcp
cd anaf-efactura-mcp
cp .env.example .env
# 编辑 .env
npm install
MCP_TRANSPORT=sse MCP_PORT=3800 node src/index.js
```
或使用 PM2：
```bash
pm2 start src/index.js --name anaf-efactura
```
可用端点：
- `GET /health` — 服务状态
- `GET /` — 身份
- `POST /mcp` — JSON-RPC 2.0（流式 HTTP）
- `GET /.well-known/mcp/server-card.json`
### 工具
| 工具 | 认证 | 描述 |
|---|:---:|---|
| `anaf_company_lookup` | ❌ | 查找任何罗马尼亚公司信息 |
| `anaf_auth_start` | ❌ | 生成 OAuth2 URL |
| `anaf_auth_callback` | ❌ | 将代码交换为令牌 |
| `anaf_auth_status` | ❌ | 检查当前令牌 |
| `anaf_generate_xml` | ❌ | 生成 UBL 而不上传 |
| `anaf_validate_xml` | ❌ | 离线结构验证 |
| `anaf_create_and_upload_invoice` | ✅ | 构建 UBL + 上传，一步到位 |
| `anaf_upload_invoice` | ✅ | 上传现有 XML |
| `anaf_upload_status` | ✅ | 检查上传状态 |
| `anaf_download` | ✅ | 下载 SPV 响应（ZIP） |
| `anaf_list_messages` | ✅ | 列出 SPV 消息 |
### 无身份验证的快速测试
任何人都可以调用 `anaf_company_lookup`（使用公共 ANAF TVA API v9）来验证服务器是否正常工作：
> *"查找 CIF 为 15193236 的公司"* → ANAF 注册的真实数据。
### 典型使用流程
1. `anaf_auth_start` → 获取授权 URL
2. 在浏览器中打开 URL（安装证书）并授权
3. 浏览器重定向到 `redirect_uri?code=XXX` → 复制代码
4. 使用代码调用 `anaf_auth_callback` → 本地保存令牌
5. `anaf_create_and_upload_invoice` → 生成并上传发票
6. 使用 `id_incarcare` 调用 `anaf_upload_status` → 跟踪处理
7. 使用消息 ID 调用 `anaf_download` → 下载官方响应
### 支持的发票类型
- `380` — 标准发票
- `381` — 信用额度
- `384` — 借记通知单
- `389` — 自动发票
### 税率和类别
| 类别 | 代码 | 典型用途 |
|---|:---:|---|
| 标准 | `S` | 正税率（19%，9%，5%） |
| 反向征税 | `AE` | 特定商品的 B2B 交易 |
| 免税 | `E` | 无抵扣权免税业务 |
| 零税率 | `Z` | 0% 税率业务 |
| 欧盟出口 | `G` | 欧盟以外交付 |
| 境内交付 | `K` | 境内交付 |
| 非税收目的 | `O` | 非税收目的业务 |
如果 `vat_category` 为空，则选择 `S` 表示税率 > 0，`Z` 表示税率 = 0。否则 **必须显式指定** 并附加 `vat_exemption_reason`。
### 环境变量
| 变量 | 默认值 | 描述 |
|---|---|---|
| `ANAF_ENV` | `test` | `test` = 沙盒，`production` = 线上 |
| `ANAF_CLIENT_ID` | — | OAuth 客户端 ID（可选；保存在回调中） |
| `ANAF_CLIENT_SECRET` | — | OAuth 客户端密钥 |
| `ANAF_CONFIG_DIR` | `~/.anaf-efactura-mcp` | 保存令牌的位置 |
| `MCP_TRANSPORT` | `stdio` | `stdio` 或 `sse` |
| `MCP_PORT` | `3800` | sse 模式下的端口 |
### 故障排除
- **“未认证”** → 运行 `anaf_auth_start` + `anaf_auth_callback`。
- **回调时 HTTP 400** → 代码已过期（有效期约 60 秒）。重新开始流程。
- **上传时 HTTP 401** → 令牌已过期且刷新失败。重新认证。
- **ANAF 拒绝 XML** → 运行 `anaf_validate_xml` 然后查看 ANAF 响应中的消息。
- **`urn:ietf:wg:oauth:2.0:oob` 不起作用** → 正确，ANAF 不接受。 使用真实的 HTTPS 重定向 URI。
### XML 合规性
UBL 2.1 · EN 16931:2017 · CIUS-RO 1.0.1 · 按税率分组的 TaxSubtotal（BG-23）。
---
## English
（略）
---
由 [@hegetiby](https://hegetiby.store) 构建。在 [GitHub](https://github.com/hegetiby/anaf-efactura-mcp/issues) 上报告问题。
