内容
# SOLVE-IT MCP 服务器
**摘要**: 该项目是一个 [MCP（模型上下文协议）](https://modelcontextprotocol.io/) 服务器，用于封装数字取证知识库及其内置库，以便为 LLMs 提供对 SOLVE-IT 内容的程序化访问。相关仓库包括：
- **SOLVE-IT**: 提供数字取证技术的结构化分类、影响证据可靠性的弱点以及缓解这些弱点的措施的知识库。该服务器为查询、导航和搜索该知识库提供了工具。可以从这里找到：[SOLVE-IT](https://github.com/SOLVE-IT-DF/solve-it)
- **MCP 服务器底盘**: 该 MCP 服务器是在 MCP 服务器底盘项目上构建的，该项目提供了一个可扩展的通用 MCP 服务器，旨在轻松分叉并用于各种用途。可以从这里找到：[MCP 服务器底盘](https://github.com/CKE-Proto/mcp_server-chassis/)
## 快速开始
### 1. 安装依赖项
**选项 1：**
```bash
pip install "mcp>=1.6.0,<2.0" pydantic pybtex
```
**选项 2：**
从当前文件夹的根目录开始。
```bash
pip install -e ".[dev]"
```
### 2. 下载此仓库。
### 3. 下载主要的 SOLVE-IT 仓库。
**参考**: https://github.com/SOLVE-IT-DF/solve-it
### 4. 配置 `config/default.toml`
此仓库中的 `default.toml` 文件必须指向您下载的主 SOLVE-IT 仓库实例。
**示例：**
```
solveit_data_path = "<完整路径到您的>/solve-it-main"
```
### 5. 运行 MCP 服务器
**注意**: 如果您的 MCP 客户端在连接到它时运行服务器，例如下面的步骤 6 中的示例，您将不需要手动运行服务器。
**示例 1：**
```bash
python3 run.py --config config/default.toml
```
**示例 2：**
```bash
python -m mcp_chassis
```
### 6. 配置您的 MCP 客户端
配置您的 MCP 客户端以连接到 MCP 服务器。在某些情况下（例如 Claude Desktop），客户端还将启动 MCP 服务器。
**示例 Claude Desktop 配置：**
**示例文件：** `claude_desktop_config.json` \
**示例路径（macOS）**: `~/Library/Application Support/Claude/claude_desktop_config.json`):
**示例配置**:
```json
{
"mcpServers": {
"solveit": {
"command": "python3",
"args": ["/path/to/mcp_server/run.py", "--config", "/path/to/mcp_server/config/default.toml"]
}
}
}
```
## 可用的 MCP 工具
### 查询（3 个工具）
| 工具 | 描述 |
|---|---|
| `solveit_get_technique` | 按 ID 检索单个技术的完整详细信息 |
| `solveit_get_weakness` | 按 ID 检索单个弱点的完整详细信息 |
| `solveit_get_mitigation` | 按 ID 检索单个缓解措施的完整详细信息 |
### 摘要列表（3 个工具）
| 工具 | 描述 |
|---|---|
| `solveit_list_techniques` | 列出所有技术的 ID 和名称 |
| `solveit_list_weaknesses` | 列出所有弱点的 ID 和名称 |
| `solveit_list_mitigations` | 列出所有缓解措施的 ID 和名称 |
### 目标（2 个工具）
| 工具 | 描述 |
|---|---|
| `solveit_list_objectives` | 列出在活动映射中定义的法医目标 |
| `solveit_get_techniques_for_objective` | 列出按给定目标分类的技术 |
### 关系（5 个工具）
| 工具 | 描述 |
|---|---|
| `solveit_get_weaknesses_for_technique` | 列出影响给定技术的弱点 |
| `solveit_get_mitigations_for_weakness` | 列出解决给定弱点的缓解措施 |
| `solveit_get_techniques_for_weakness` | 列出受给定弱点影响的技术 |
| `solveit_get_weaknesses_for_mitigation` | 列出给定缓解措施解决的弱点 |
| `solveit_get_techniques_for_mitigation` | 列出与给定缓解措施相关的技术 |
### 搜索（1 个工具）
| 工具 | 描述 |
|---|---|
| `solveit_search` | 跨技术、弱点和缓解措施的全文搜索 |
### 扩展信息（1 个工具）
| 工具 | 描述 |
|---|---|
| `solveit_list_loaded_extensions` | 列出当前加载的任何 SOLVE-IT-X 扩展数据集 |
### 引文（2 个工具）
| 工具 | 描述 |
|---|---|
| `solveit_get_citation` | 按 DFCite ID 检索引文 |
| `solveit_list_citations` | 列出知识库中的所有引文 ID |
### 状态（1 个工具）
| 工具 | 描述 |
|---|---|
| `solveit_status` | 报告数据加载状态、项目计数（包括引文）和活动配置 |
### 完整详细信息列表
**注意：** 这些工具默认情况下处于禁用状态，因为它们返回的数据量较大。它们可以在 `config/default.toml` 中启用。
| 工具 | 描述 |
|---|---|
| `solveit_list_techniques_full_detail` | 列出所有技术的完整字段数据 |
| `solveit_list_weaknesses_full_detail` | 列出所有弱点的完整字段数据 |
| `solveit_list_mitigations_full_detail` | 列出所有缓解措施的完整字段数据 |
## 配置
`config/default.toml` 中的 `[app]` 部分控制 SOLVE-IT 特定的设置。顶级 `[app]` 键也可以通过带有 `MCP_APP_` 前缀的环境变量覆盖（环境变量优先于 TOML 值）：
| 环境变量 | 配置键 | 类型 |
|---|---|---|
| `MCP_APP_SOLVEIT_DATA_PATH` | `solveit_data_path` | 字符串 |
| `MCP_APP_OBJECTIVE_MAPPING` | `objective_mapping` | 字符串 |
| `MCP_APP_ENABLE_EXTENSIONS` | `enable_extensions` | 布尔值（`true`/`false`/`1`/`0`/`yes`/`no`） |
| `MCP_APP_INIT_REQUIRED` | `init_required` | 布尔值 |
| `MCP_APP_ENABLE_FULL_DETAIL_TOOLS` | `enable_full_detail_tools` | 布尔值 |
```toml
[app]
# SOLVE-IT 仓库根目录的路径（绝对或相对于 CWD）。
solveit_data_path = "/<路径>/<到>/<您的>/solve-it-main"
# 目标映射文件（必须存在于 SOLVE-IT 数据目录中）。
# 默认值： "solve-it.json"（标准的 SOLVE-IT 分类）。
# 自定义映射文件可以放在数据目录中，以提供
# 技术的替代分类。
# 参见： https://custom-viewer.solveit-df.org
objective_mapping = "solve-it.json"
# 是否加载 SOLVE-IT-X 扩展数据。
enable_extensions = true
# 如果为 true（默认值），知识库加载失败时服务器立即退出。
# 如果为 false，服务器以降级模式启动，仅有 solveit_status 可用。
init_required = true
# 启用完整详细信息列表工具（大 payload，默认禁用）。
# 警告：这些工具返回给定类型的数据集，可能
# 消耗大量 LLM 上下文。你可能还需要增加
# [security.io_limits] max_response_size 在启用此功能时。
enable_full_detail_tools = false
[app.search]
# 每个标志控制 solveit_search 工具架构中是否包含相应的参数。
# 当禁用时，使用默认值：item_types=all，substring_match=false，search_logic="AND"
enable_item_types_filter = true
enable_substring_match = true
enable_search_logic = true
```
**`solveit_data_path`** — 克隆的 SOLVE-IT 仓库的路径。接受绝对路径或相对于服务器启动时的工作目录的路径。
**`objective_mapping`** — 将技术分类为法医目标的 JSON 映射文件的名称。必须存在于 SOLVE-IT `data/` 目录中。默认 `solve-it.json` 反映官方分类。
**`enable_extensions`** — 当为 `true` 时，服务器加载 SOLVE-IT-X 扩展数据集。
**`init_required`** — 当为 `true`（默认值）时，如果知识库加载失败，服务器会退出并显示清晰的错误信息。当为 `false` 时，服务器以降级模式启动，仅有 `solveit_status` 可用，该状态报告加载失败。开发过程中，如果您需要测试服务器行为而没有有效的知识库数据，请设置为 `false`。
**`enable_full_detail_tools`** — 控制是否注册三个完整详细信息列表工具。参见下面的章节，然后再启用。
**搜索参数标志** — 三个 `[app.search]` 标志分别控制 `solveit_search` 工具架构中是否包含相应的参数。当标志为 `false` 时，参数被隐藏，其默认值被静默应用：`item_types` 默认值为所有类型，`substring_match` 默认值为 `false`（单词边界匹配），`search_logic` 默认值为 `"AND"`。
## 启用完整详细信息工具
在 `config/default.toml` 中设置 `enable_full_detail_tools = true` 以注册三个完整详细信息列表工具。
**警告：** 这些工具返回整个数据集的完整信息。根据 SOLVE-IT 数据的大小和已加载的扩展，响应可能非常大，可能会占用大量 LLM 上下文窗口。如果您启用这些工具，您可能还需要提高响应大小限制：
```toml
[security.io_limits]
max_response_size = 20971520 # 20 MB；默认值是 5 MB
```
## 安全
安全行为继承自构建此 MCP 服务器的 MCP 服务器底盘。每个工具请求都通过中间件管道，顺序如下：
```
I/O 限制 → 身份验证 → 速率限制 → 净化 → 验证
```
通过此管道，可以在输入到达工具处理程序之前应用净化尝试。默认安全配置文件为 `moderate`。
**重要信息：** 这些保护是提供默认安全性的基本尝试。如果您决定在生产环境中使用此服务器，我们建议您仍然进行安全测试，并根据您的威胁环境和风险承受能力修改此项目的代码以实施适当的安全缓解措施。
| 配置文件 | 速率限制 | I/O 限制 | 净化 | 错误详细信息 |
|---|---|---|---|---|
| `strict` | 60 rpm 全局，30 rpm/工具 | 1 MB 请求，5 MB 响应 | 完整（路径遍历、shell 元字符、控制字符） | 通用 |
| `moderate` | 120 rpm 全局，60 rpm/工具 | 5 MB 请求，20 MB 响应 | 路径遍历 + 控制字符 | 详细 |
| `permissive` | 禁用 | 50 MB 请求/响应 | 空字节 | 详细 |
活动配置文件通过 `config/default.toml` 中的 `[security]` 配置文件设置，其中可以使用单个设置覆盖指定配置文件的元素。此外，`MCP_SECURITY_PROFILE` 环境变量可以覆盖 `default.toml` 中的配置文件。
## 测试
```bash
python -m pytest tests/ # 所有测试
python -m pytest tests/unit/ # 单元测试
python -m pytest tests/integration/ # 集成测试
```
## 项目结构
```
src/mcp_chassis/
server.py — ChassisServer：中央编排器
config.py — 配置数据类和 TOML 加载
__main__.py — CLI 入口点
extensions/
solveit_init.py — 在启动时初始化 SOLVE-IT 数据加载器
tools/
solveit_tools.py — 所有 21 个 SOLVE-IT 工具注册和处理程序
middleware/
pipeline.py — 安全中间件管道
security/ — 速率限制、净化、验证、配置文件
transport/ — 标准输入/输出传输（生产）
config/
default.toml — 服务器和应用程序配置
tests/
unit/ — 单元测试
integration/ — 集成测试（stdio 子进程）
docs/
ARCHITECTURE.md — 组件设计和数据流
TROUBLESHOOTING.md — 常见问题和修复
```
## 与 MCP 客户端一起使用
该项目包括一个 `run.py` 启动器，它会自动处理 Python 路径设置。为 `run.py` 和 `--config` 使用绝对路径，以便服务器无论客户端的工作目录如何都能正常工作。
**前提条件：** 运行服务器的机器上必须安装 Python 依赖项：
```bash
cd /path/to/mcp_server
pip install "mcp>=1.2.0,<2.0" pydantic pybtex # 最小依赖项
```
在配置客户端之前，在 `config/default.toml` 中将 `solveit_data_path` 设置为绝对路径：
```toml
[app]
solveit_data_path = "/绝对路径/to/solve-it/solve-it-main"
```
### 克劳德代码
将以下内容添加到您的项目的 `.mcp.json` 中：
```json
{
"mcpServers": {
"solveit": {
"type": "stdio",
"command": "python3",
"args": ["/path/to/mcp_server/run.py", "--config", "/path/to/mcp_server/config/default.toml"]
}
}
}
```
### 克劳德桌面
将以下内容添加到 `claude_desktop_config.json`（macOS：`~/Library/Application Support/Claude/claude_desktop_config.json`）：
```json
{
"mcpServers": {
"solveit": {
"command": "python3",
"args": ["/path/to/mcp_server/run.py", "--config", "/path/to/mcp_server/config/default.toml"]
}
}
}
```
### 替代方案：使用 `pip install`
如果您不想使用 `run.py`，请安装软件包并直接使用 `-m`：
```bash
pip install -e .
```
```json
{
"mcpServers": {
"solveit": {
"command": "python3",
"args": ["-m", "mcp_chassis", "--config", "/path/to/mcp_server/config/default.toml"]
}
}
}
```
