内容
# 文件扫描MCP服务器
一个用Rust编写的[模型上下文协议](https://modelcontextprotocol.io)（MCP）服务器，作为MCP工具公开[Filescan.io](https://www.filescan.io) API端点。
## 工具列表
| 工具 | 端点 | 描述 |
|---|---|---|
| `filescan_scan_file` | `POST /api/scan/file` | 上传本地文件进行恶意软件扫描 |
| `filescan_scan_url` | `POST /api/scan/url` | 提交URL进行扫描 |
| `filescan_get_scan_reports` | `GET /api/scan/{flow_id}/report` | 获取扫描流程的报告 |
| `filescan_get_report` | `GET /api/reports/{report_id}/{file_hash}` | 获取特定报告 |
| `filescan_search_reports` | `GET /api/reports/search` | 使用多个过滤器搜索报告 |
| `filescan_get_search_matches` | `POST /api/reports/search/matches` | 获取报告ID的IOC匹配 |
| `filescan_list_public_reports` | `GET /api/reports` | 列出公共报告 |
| `filescan_check_file_availability` | `POST /api/files/availability` | 检查文件哈希在Filescan中是否可用 |
| `filescan_get_hash_reputation` | `GET/POST /api/reputation/hash` | 查询SHA256哈希的声誉（单个或批量） |
| `filescan_get_ioc_reputation` | `GET/POST /api/reputation/{ioc_type}` | 查询IOC的声誉 — 域名/IP/URL（单个或批量） |
| `filescan_get_ioc_prevalence` | `POST /api/threatintel/get-prevalence` | 获取报告中IOC的流行度统计 |
| `filescan_get_similar_reports` | `GET /api/threatintel/get-similars` | 查找具有相同特殊哈希的报告 |
| `filescan_similarity_search` | `GET /api/similarity-search/similarity` | **[废弃]** 通过SHA256、标签、阈值、判决查找相似报告 |
### 第二阶段工具说明
- `filescan_get_hash_reputation`：提供确切的`hash`（单个 → GET）或`hashes`（批量 → POST，1-100项）。
- `filescan_get_ioc_reputation`：提供确切的`ioc_value`（单个 → GET）或`ioc_values`（批量 → POST，1-100项）。`ioc_type`必须是`domain`、`ip`或`url`。
- 批量查找限制为100项以确保安全；这是MCP约定，不是API限制。
- 声誉结果使用标记输出：`{ "mode": "single", "result": {...} }` 或 `{ "mode": "bulk", "results": [...] }`。
### 第三阶段工具说明
- `filescan_get_ioc_prevalence`：需要至少一个IOC数组填充（支持16种IOC类型）。`days`必须是1-30（默认为30）。`exclude_report_ids`是查询参数（不是JSON正文）。
- `filescan_get_similar_reports`：需要至少一个`imphash`、`ssdeep`、`fuzzyfsiohash`或`authentihash`。`days = -1`表示无时间限制。响应包括每个报告的文件名和SHA256。
- `filescan_similarity_search`：**废弃** 由Filescan OpenAPI规范废弃 — 公开是因为请求。`min_similarity`是0-100。需要至少一个选择器（`hash`、`tags`、`verdict`或`min_similarity`）。返回顶部10个最相似和顶部10个最新发现。
- 所有第三阶段工具都是只读的。
- 列表上限：所有IOC数组、`exclude_report_ids`和`tags`限制为100项。
## 设置
### 先决条件
- Rust 1.80+（稳定版）
- 一个[Filescan.io](https://www.filescan.io) API密钥
### 环境变量
| 变量 | 必需 | 默认值 | 描述 |
|---|---|---|---|
| `FILESCAN_API_KEY` | **是** | — | 您的Filescan.io API密钥 |
| `FILESCAN_BASE_URL` | 否 | `https://www.filescan.io` | Filescan API的基本URL |
| `FILESCAN_TIMEOUT_SECS` | 否 | `60` | HTTP请求超时（秒） |
### 构建和运行
```bash
cargo build --release
```
二进制文件位于`target/release/filescan-mcp`。运行：
```bash
export FILESCAN_API_KEY="your-api-key-here"
./target/release/filescan-mcp
```
## Claude桌面配置
添加到您的`claude_desktop_config.json`：
```json
{
"mcpServers": {
"filescan": {
"command": "/path/to/target/release/filescan-mcp",
"env": {
"FILESCAN_API_KEY": "your-api-key-here"
}
}
}
}
```
## 开发
```bash
cargo check
cargo test
cargo clippy --all-targets -- -D warnings
```
## 覆盖范围说明（MVP）
### 已实现
- 所有7个第一阶段工具按照OpenAPI分析确切实现。
- 第二阶段工具：`filescan_check_file_availability`、`filescan_get_hash_reputation`、`filescan_get_ioc_reputation` — 所有3个实现。
- 带有`schemars` JSON模式的输入结构体用于MCP工具注册。
- 带有`ScanResponse`、`ScanPriorityResponse`、`AllUploadRelatedReportsResponse`、`ReportSearchResponse`、`MatchesResponseItem`模型的输入结构体。
- 第二阶段模型：`ReputationResultHash`、`ReputationResultIoc`、`FuzzyhashVerdict`、`ResultMultiscan`、`ResultLookup`、`ReportForReputationCalculation`、`FileAvailabilityResponse`。
- 标记响应包装器（`HashReputationResponse`、`IocReputationResponse`）用于稳定的单项和批量输出。
- 第三阶段工具：`filescan_get_ioc_prevalence`、`filescan_get_similar_reports`、`filescan_similarity_search` — 所有3个实现，带有类型模型、验证和契约测试。
- `IocsPrevalenceMap`三重嵌套响应反序列化，用于流行度和相似端点。
- `SimilaritiesResponse`、`SimilaritiesResultSimilarity`（32个可选类别分数）、`DetailsResultSimilarity`、`ResultSimilarity`模型。
- 第三阶段输入验证：天数边界、至少一个选择器强制执行、列表上限、空字符串拒绝。
- 所有39个报告搜索查询参数支持。
- `ReportSearchQuery`在搜索和匹配端点之间共享。
- 本地文件路径验证的多部分文件上传。
- URL编码表单提交用于URL扫描。
- 处理400/401/403/404/413/415/422/429的错误处理，带有可操作的错误信息。
- 429速率限制的`Retry-After`标头处理。
- 声誉工具的XOR输入验证（必须提供单个或批量中的一个）。
- 批量请求安全上限（最多100项）并在运行时强制执行。
- `Debug`输出和日志中的API密钥删除。
### 故意推迟
- 第四阶段元数据工具：`filescan_system_info`、`filescan_system_version`、`filescan_system_config`等。
- 管理/变异端点（新闻创建/删除）。
- UI端点（徽标、翻译、语言、国家等）。
### 注意事项
- `ScanPriorityResponse`中的`max_posibble`拼写错误使用`#[serde(rename)]`处理。模式也显示为`max_possible`。
- 对于`POST /api/reports/search/matches`，`unique_files`作为可选查询参数与`reports_ids`和共享搜索查询筛选器一起公开。
- 大型响应负载（报告正文）使用`serde_json::Value`而不是完全类型化的结构体 — 这是故意的，以处理`additionalProperties: true`模式。
- `propagate_tags`在OpenAPI规范中默认为`true`，但如果未设置，则不会发送 — 让API处理默认值。
- `scan_file`工具使用`file_path`（本地路径），而不是base64内容。这是MCP标准输入/输出约定。
