内容
<!-- mcp-name: io.github.atomno-mcp/mcp-fns-check -->
# atomno-mcp-fns-check
> 用于通过公开的税务局数据检查俄罗斯交易对手（法人和个人）的MCP服务器：统一国家法人登记册/统一国家个体经营者登记册、统一破产信息公示系统、“透明商业”、联邦执行局、法院。
可与Claude Desktop、Cursor、Claude Code、Cline等任何兼容Model Context Protocol（MCP）的客户端连接。
---
## 目的
AI代理（Claude、Cursor等）通常不了解俄罗斯交易对手：统一国家法人登记册不被搜索引擎索引、税务局的“透明商业”数据需要POST请求和验证码、统一破产信息公示系统返回HTML。这个MCP服务器为代理提供**七种工具**，通过一次调用获取完整信息：
- 识别信息：名称、地址、行业代码、负责人。
- 状态：活跃、注销、破产、清算、重组。
- 交易安全性：地址是否集中、负责人是否集中、是否被限制、破产、税务债务、未提供报告、执行程序、仲裁案件。
主要工具是`check_contractor(identifier)`，接受税号或注册号，返回**聚合报告和结论**（`safe_to_proceed` / `manual_review_required` / `high_risk_do_not_proceed` / `impossible_contractor_defunct`）和具体建议列表。
---
## 快速开始
### 安装
```bash
pip install atomno-mcp-fns-check
```
或使用`uv` / `pipx`：
```bash
uv pip install atomno-mcp-fns-check
# 或
pipx install atomno-mcp-fns-check
```
### 检查运行
```bash
atomno-mcp-fns-check --version
# → atomno-mcp-fns-check 0.1.1
atomno-mcp-fns-check --help
# → 完整参数列表：--transport / --host / --port / --log-level
```
默认情况下，包作为stdio-MCP服务器运行：代理通过stdin/stdout JSON-RPC与其通信。直接从shell调用是不可能的 - 需要连接到MCP客户端。对于网络场景，可以使用`--transport {http,sse,streamable-http}`和`--host` / `--port`。
---
## 连接到MCP客户端
### Cursor
编辑`mcp.json`（Cursor → 设置 → Cursor 设置 → MCP）：
```json
{
"mcpServers": {
"fns-check": {
"command": "atomno-mcp-fns-check"
}
}
}
```
重启Cursor。在聊天窗口中输入：“检查交易对手税号 7707083893” - 代理将自动调用`check_contractor`。
### Claude Desktop
编辑`claude_desktop_config.json`（macOS: `~/Library/Application Support/Claude/`，Windows: `%APPDATA%\Claude\`）：
```json
{
"mcpServers": {
"fns-check": {
"command": "atomno-mcp-fns-check"
}
}
}
```
重启Claude Desktop。
### Claude Code (CLI)
```bash
claude mcp add fns-check atomno-mcp-fns-check
```
### Cline (VS Code)
在`cline_mcp_settings.json`中：
```json
{
"mcpServers": {
"fns-check": {
"command": "atomno-mcp-fns-check",
"disabled": false,
"autoApprove": []
}
}
}
```
---
## 工具
| 工具 | 用途 | 输入 | 来源 |
|---|---|---|---|
| **`check_contractor`** | 主要工具。完整检查单个标识符 + 确定性结论和建议 | `identifier: str` (税号 10/12 位或注册号 13/15 位) | 所有 5 个 |
| `check_inn` | 基本的统一国家法人登记册卡片 | `inn: str` | egrul.nalog.ru |
| `check_ogrn` | 基于注册号/个体经营者注册号的基本卡片 | `ogrn: str` | egrul.nalog.ru |
| `get_legal_status` | 具有丰富信息的法律状态 | `inn` 或 `ogrn` | 统一国家法人登记册 + 统一破产信息公示系统 |
| `get_okveds` | 行业代码及说明 | `inn` 或 `ogrn` | 统一国家法人登记册 + 行业代码词典 |
| `get_directors_history` | 当前负责人（+ 历史记录） | `inn: str` | 统一国家法人登记册 |
| `check_for_red_flags` | 8 项风险检查（4 项基本 + 4 项扩展） | `inn: str` | 所有 5 个 |
使用的公开来源：
- **egrul.nalog.ru** — 统一国家法人登记册/统一国家个体经营者登记册，交易对手卡片。
- **bankrot.fedresurs.ru** — 统一破产信息公示系统（统一的破产信息公示系统）。
- **pb.nalog.ru** — 税务局的“透明商业”（税务债务，未提供报告）。
- **fssp.gov.ru** — 联邦执行局的执行程序数据库。
- **kad.arbitr.ru** — 仲裁案件档案。
- 俄罗斯联邦税务局的本地寄存器 - 集中地址、集中负责人、被限制人员（由`atomno-mcp-fns-etl`脚本从俄罗斯联邦税务局的公开数据加载）。
### `check_contractor` 示例响应
```json
{
"identifier": "7707083893",
"identifier_type": "inn",
"inn": "7707083893",
"ogrn": "1027700132195",
"card": {
"name": {"full": "ПАО СБЕРБАНК", "short": "СБЕРБАНК"},
"status": "active",
"address": {"full": "117997, Г.Москва, УЛ. ВАВИЛОВА, Д. 19", "is_mass_address": false},
"director": {"full_name": "Греф Г. О.", "position": "Президент"},
"okved_main": {"code": "64.19", "name": "Денежное посредничество прочее"}
},
"legal_status": {"status": "active", "status_label_ru": "Действующее", "sources_checked": ["egrul", "efrsb"]},
"risks": {"overall_risk_level": "low", "overall_risk_score": 0, "flags": [], "errors": []},
"verdict_action": "safe_to_proceed",
"verdict_reason_ru": "Статус «Действующее», уровень риска — low (score 0/100). Препятствий к заключению сделки по открытым источникам не найдено.",
"recommendations": [
"По открытым источникам препятствий к заключению сделки не обнаружено. Соблюдайте стандартные меры должной осмотрительности (ст. 54.1 НК РФ): копия устава, приказ на руководителя, договор."
],
"sources": {"sources_queried": ["efrsb", "egrul", "fssp", "kad", "pb_fns", "registries"]},
"tier": "open",
"checked_at": "2026-04-24T20:15:00Z"
}
```
### 源故障行为
- 统一国家法人登记册是唯一的**阻塞**源。如果它不可用，`check_contractor` 会引发 `SourceUnavailableError`（代理将收到人类可读的消息）。
- 其他源被**尽力而为**：FSSP 的验证码，KAD 的 antibot，pb.nalog.ru 上的 5xx 错误都会被汇总到 `risks.errors[]` 中，而不会影响报告。顶级结论变为 `manual_review_required`。
---
## 配置
所有设置均通过环境变量进行。无需凭证（源是公开的）。
| 变量 | 描述 | 默认值 |
|---|---|---|
| `MCP_FNS_CACHE_DB` | 证书缓存的 SQLite 文件路径 | `./atomno_mcp_fns_check_cache.sqlite` |
| `MCP_FNS_REGISTRIES_DB` | 注册表（集中地址/负责人/被限制人员）的 SQLite 文件路径 | `<cache>.registries.sqlite` |
| `MCP_FNS_CACHE_TTL_HOURS` | 缓存证书的 TTL，小时 | `168` （7 天） |
| `MCP_FNS_HTTP_TIMEOUT` | HTTP 超时，秒 | `15` |
| `MCP_FNS_USER_AGENT` | HTTP 客户端的用户代理 | `atomno-mcp-fns-check/0.1 (+https://github.com/atomno-mcp/mcp-fns-check)` |
| `MCP_FNS_LOG_LEVEL` | 日志级别（DEBUG/INFO/WARNING/ERROR） | `INFO` |
模板 - `.env.example`。
---
## 本地税务局注册表
集中地址/负责人/被限制人员的注册表是俄罗斯联邦税务局的公开数据导出。软件包附带一个内置的最小种子（`registries_seed.json`，综合测试记录） - 足以使工具在开箱后工作并在测试税号上显示标志。
对于生产检查，请使用 CLI `atomno-mcp-fns-etl` 更新完整的寄存器：
```bash
atomno-mcp-fns-etl --registry mass_addresses --source ./fns_open_data/ulm.csv --commit
atomno-mcp-fns-etl --registry mass_directors --source ./fns_open_data/uchredt.csv --commit
atomno-mcp-fns-etl --registry disqualified --source ./fns_open_data/disqualified.csv --commit
```
公开数据源：
- `mass_addresses` → [nalog.gov.ru/opendata/7707329152-massreg/](https://www.nalog.gov.ru/opendata/7707329152-massreg/)
- `mass_directors` → [nalog.gov.ru/opendata/7707329152-massuchredt/](https://www.nalog.gov.ru/opendata/7707329152-massuchredt/)
- `disqualified` → [service.nalog.ru/disqualified.do](https://service.nalog.ru/disqualified.do)
默认情况下，CLI 在 `--dry-run` 模式下运行（解析并打印样本）；要写入数据，需要明确 `--commit` 参数。元字段 `<registry>.last_etl`，`<registry>.last_etl_source`，`<registry>.last_etl_count` 会自动保存 - 将它们用于数据新鲜度的 cron 监控。
---
## 开发
```bash
git clone https://github.com/atomno-mcp/mcp-fns-check
cd mcp-fns-check
python -m venv .venv
source .venv/bin/activate # Linux/macOS
# .venv/Scripts/activate # Windows
pip install -e ".[dev]"
pytest -v --cov=src/atomno_mcp_fns_check
```
测试中的外部 API **从不直接调用** - 仅通过 `respx` （模拟 httpx）+ `tests/fixtures/` 中的本地 fixtures。
---
## 限制
- **负责人没有历史记录** - 俄罗斯联邦税务局不通过 search-API 提供变更历史；完整历史记录将在 v0.5+ 中出现，在加载统一国家法人登记册的公开数据片段后。
- **FSSP / KAD 有时会阻止** CAPTCHA / antibot。在这种情况下，检查会失败并显示 `errors[]`，而总体结论变为 `manual_review_required`。
- **“透明商业”** 只提供事实（“存在债务” / “无报告”），而没有金额。金额需要向税务局查询。
Pro-tier（托管后端在 `atomno-mcp-fns-check-server` 中 - 私有后端）通过以下方式消除了这些限制：24 小时的 Redis 缓存，CAPTCHA 轮换代理，统一国家法人登记册的完整切片，批量检查最多 100 个税号，通过 LLM 进行 AI 摘要。后台服务未公开。
---
## 安全性和法律状态
- 所有源都是 **俄罗斯联邦税务局的公开数据** 及相关注册表。根据 149-ФЗ《关于信息》，其使用是合法的。
- 法人和个体经营者 **不属于** 152-ФЗ（关于个人数据）。
- 作为法人代表的物理人员的姓名在统一国家法人登记册中公开；输出响应中法人代表的税号被屏蔽（格式 `XXX*****YY`）。
- 没有对任何外部 API 进行写入操作。
- 无需凭证/令牌 - 源完全公开。
---
## 免责声明
该服务是 **俄罗斯联邦税务局公开数据的聚合器和便捷界面**。不隶属于俄罗斯联邦税务局、统一破产信息公示系统、仲裁案件档案或联邦执行局。使用风险自负。
服务响应中的信息 **不取代** 全面的法律或财务评估。您做出与交易对手签订合同的决定。
---
## 许可证
MIT - 参见 `LICENSE`。
---
## 链接
- GitHub：[atomno-mcp/mcp-fns-check](https://github.com/atomno-mcp/mcp-fns-check)
- 更多 atomno 品牌下的 MCP 服务器：[atomno-labs.ru 目录](https://atomno-labs.ru/) （即将推出）
- MCP 规范：[modelcontextprotocol.io](https://modelcontextprotocol.io)
