nguyenthdat/filescan-mcp
GitHub: nguyenthdat/filescan-mcp
用 Rust 实现的 Filescan.io MCP 服务器，将恶意软件扫描、URL 检测和威胁情报 API 暴露为大语言模型可调用的工具。
Stars: 1 | Forks: 0
# Filescan MCP 服务器
一个使用 Rust 编写的 [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server，将 [Filescan.io](https://www.filescan.io) API endpoint 暴露为 MCP 工具。
## 工具
| 工具 | Endpoint | 描述 |
|---|---|---|
| `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` | 获取 report ID 的 IOC 匹配项 |
| `filescan_list_public_reports` | `GET /api/reports` | 列出公开报告 |
## 设置
### 前置条件
- Rust 1.80+ (stable)
- 一个 [Filescan.io](https://www.filescan.io) API key
### 环境变量
| 变量 | 必需 | 默认值 | 描述 |
|---|---|---|---|
| `FILESCAN_API_KEY` | **是** | — | 你的 Filescan.io API key |
| `FILESCAN_BASE_URL` | 否 | `https://www.filescan.io` | Filescan API 的 base URL |
| `FILESCAN_TIMEOUT_SECS` | 否 | `60` | HTTP 请求超时时间（以秒为单位） |
### 构建与运行
```
cargo build --release
```
二进制文件位于 `target/release/filescan-mcp`。运行方式：
```
export FILESCAN_API_KEY="your-api-key-here"
./target/release/filescan-mcp
```
## Claude Desktop 配置
添加到你的 `claude_desktop_config.json` 中：
```
{
"mcpServers": {
"filescan": {
"command": "/path/to/target/release/filescan-mcp",
"env": {
"FILESCAN_API_KEY": "your-api-key-here"
}
}
}
}
```
## 开发
```
cargo check
cargo test
cargo clippy --all-targets -- -D warnings
```
## 覆盖说明 (MVP)
### 已实现
- 所有 7 个阶段 1 的工具均已完全按照 OpenAPI 分析实现。
- 带有 `schemars` JSON schema 的类型化输入 struct，用于 MCP 工具注册。
- 类型化的 `ScanResponse`、`ScanPriorityResponse`、`AllUploadRelatedReportsResponse`、`ReportSearchResponse`、`MatchesResponseItem` 模型。
- 支持所有 39 个报告搜索查询参数。
- `ReportSearchQuery` 在搜索和 matches endpoint 之间共享。
- 带有本地文件路径验证的 Multipart 文件上传。
- 用于 URL 扫描的 URL 编码表单提交。
- 针对 400/401/403/404/413/422/429 的错误处理，并附带可操作的错误信息。
- 针对 429 速率限制的 `Retry-After` header 处理。
- 在 `Debug` 输出和日志中对 API key 进行脱敏处理。
### 故意推迟
- 阶段 2 工具：`filescan_check_file_availability`、`filescan_get_hash_reputation`、`filescan_get_ioc_reputation`。
- 阶段 3 工具：`filescan_get_ioc_prevalence`、`filescan_get_similar_reports`、`filescan_similarity_search`。
- 阶段 4 元数据工具：`filescan_system_info`、`filescan_system_version`、`filescan_system_config` 等。
- 管理/变更 endpoint（新闻创建/删除）。
- UI endpoint（logo、翻译、语言、国家/地区等）。
### 注意事项
- `ScanPriorityResponse` 中的 `max_posibble` 拼写错误已通过 `#[serde(rename)]` 处理。该 schema 也会显示为 `max_possible`。
- 对于 `POST /api/reports/search/matches`，`unique_files` 作为一个可选的查询参数与 `reports_ids` 及共享的搜索查询过滤器一起暴露。
- 大型响应 payload（报告正文）使用 `serde_json::Value` 而非完全类型化的 struct —— 这是为了处理 `additionalProperties: true` schema 而有意为之。
- `propagate_tags` 在 OpenAPI 规范中默认为 `true`，但如果未设置则不会发送 —— 让 API 处理默认值。
- `scan_file` 工具使用 `file_path`（本地路径），而不是 base64 内容。这是 MCP stdio 的约定。
标签：MCP服务, Rust, 可视化界面, 威胁情报, 开发者工具, 文件扫描, 网络流量审计, 通知系统