内容
# mcp-arca-afip
[](https://www.npmjs.com/package/mcp-arca-afip)
[](https://www.npmjs.com/package/mcp-arca-afip)
[](https://nodejs.org)
[](./LICENSE)
[](https://modelcontextprotocol.io)
**MCP**（模型上下文协议）服务器，公开 **ARCA/AFIP** 网络服务的官方文档，适用于 **Claude Code**（以及其他 MCP 客户端，如 Cursor、Windsurf、Claude Desktop 等），并支持 **BM25 + 语义**混合搜索。
**可在 npm 上获取**：[`mcp-arca-afip`](https://www.npmjs.com/package/mcp-arca-afip) · 无需 API 密钥，无需托管基础设施，全部本地运行。
> ⚠️ **本项目与 AFIP/ARCA 无关。** 它索引了在 [afip.gob.ar](https://www.afip.gob.ar/ws/documentacion/default.asp) 上发布的公共文档。手册、WSDL 和文本归原作者所有。
---
## 内容
- **51 个索引的网络服务**（`afip.gob.ar/ws/documentacion` 中所有已文档化的服务）
- **3,832 个区块**，带有本地嵌入（无需 API 密钥，无需付费服务调用）
- **4 个 MCP 工具**：`search_docs`、`list_web_services`、`get_web_service`、`get_document`
- **混合搜索**，结合 BM25 + 语义 + RRF（互惠排名融合）
- **WSDL + PDF 手册 + HTML 页面**（包括 WSASS 同步环境的手册）
### 涵盖的服务
身份验证、证书、电子发票（WSFEv1、WSMTXCA、WSBFEv1、WSFEX、WSCT、WSSEG）、A4/A5/A10/A13/A100 注册、注册证明、WSCDCV1、电子运单、谷物初级清算、畜牧业、甘蔗、烟草、乳制品、固定资产、通关（WSSV、WGESINV、WDEPMOVIMIENTOS、WSCES 等）、SIRE-IVA 扣缴、工作 F931 等。
---
## 快速入门
```bash
claude mcp add arca-afip --scope user -- npx -y mcp-arca-afip
```
重启 Claude Code 并询问类似的问题，例如 *"WSFEv1 中的错误 10015 是什么意思？"*。完成。
---
## 详细安装
在任意终端中：
```bash
claude mcp add arca-afip --scope user -- npx -y mcp-arca-afip
```
`npx -y` 始终解析并运行 [npm](https://www.npmjs.com/package/mcp-arca-afip) 上发布的最新版本，而无需事先安装。软件包大小约为 7.7 MB。
验证连接：
```bash
claude mcp list
# arca-afip: npx -y mcp-arca-afip - ✓ Connected
```
### 范围
| 标志 | 适用范围 |
|------|------------------------|
| `--scope user`（推荐） | 当前机器上的所有项目 |
| `--scope project` | 仅限当前仓库 — 创建可提交的 `.mcp.json` 以供团队使用 |
| `--scope local` | 仅限当前仓库，不提交 |
### 首次运行
来自 Claude Code 的第一个查询会下载一个 ~130 MB 的嵌入模型到 `~/.cache/mcp-arca-afip/models/`。**每台机器和每个用户只需一次**；缓存会在 `npx -y ...@latest`（软件包的新版本**不会**重新下载模型）后仍然存在。在第一次查询之后，网络请求为零，查询时间为 ~100 毫秒。
### 更新到最新版本
安装命令中的 `npx -y mcp-arca-afip@latest` 始终会获取最新版本。如果您已经安装：
```bash
claude mcp remove arca-afip --scope user
claude mcp add arca-afip --scope user -- npx -y mcp-arca-afip@latest
```
### 其他 MCP 客户端
它适用于任何与 MCP 兼容的客户端（Cursor、Windsurf、Claude Desktop 等），使用 `npx -y mcp-arca-afip` 作为服务器命令。请参阅[官方协议文档](https://modelcontextprotocol.io)，了解每种客户端特有的格式。
---
## 可用工具
### `search_docs`
对所有文档进行混合搜索。
返回最相关的区块和源 URL。当匹配到字面错误代码（`10015`）、操作名称（`FECAESolicitar`）或字段（`CAECodigo`）时，BM25 优先选择确切的区块；对于自然语言查询，语义排名接管。
### `list_web_services`
列出所有索引的网络服务及其 ID 和描述。作为传递给其他工具的 `wsId` 的第一步非常有用。
### `get_web_service`
特定网络服务的元数据和目录表。
```
wsId: "wsfev1"
```
### `get_document`
从区块中重建完整的文档（最多 ~60k 字符）。当 `search_docs` 返回一个片段但您需要完整上下文或整个 XML 模式时，请使用它。
```
source: "https://www.afip.gob.ar/ws/documentacion/manuales/manual-desarrollador-ARCA-COMPG-v4-1.pdf"
maxChars: 60000 // 可选
```
---
## 贡献
欢迎提交问题和拉取请求。要添加新的网络服务：
1. 编辑 `ingest/sources.json` 并添加带有 URL 的条目。
2. 运行 `npm run ingest:build` — 现有嵌入缓存，新的区块将被嵌入。
3. 运行 `npm test` 进行验证。
4. 提交拉取请求。
要更新 AFIP 更改后的文档：运行 `npm run ingest:coverage`，它会与 AFIP live 进行比较并显示差异。
---
## 许可证
MIT © [faeralan](https://github.com/faeralan)
