# 控制科学与工程文献检索 MCP

一个面向控制科学与工程研究的只读 MCP Server。它通过 OpenAlex 检索论文元数据，默认只搜索 Folium 项目当前使用的控制领域核心期刊集合。

仓库：<https://github.com/PrisonBreakPB/control-science-literature-mcp>

它只提供一个工具：`search_control_science_papers`。该工具不读取或写入项目文件、不运行 shell 命令、不下载 PDF、不上传数据，也不能修改本地期刊配置。

## 默认文献范围

内置集合目前有 27 个期刊来源，与 Folium 当前文献检索工具使用的 source ID 集合一致：

- Automatica、IEEE Transactions on Automatic Control、Systems & Control Letters
- IEEE Transactions on Systems, Man, and Cybernetics、IEEE Transactions on Cybernetics、IEEE Transactions on Automation Science and Engineering
- IEEE Transactions on Neural Networks and Learning Systems、IEEE Transactions on Fuzzy Systems、IEEE Transactions on Industrial Electronics
- IEEE Transactions on Control Systems Technology、IEEE Transactions on Aerospace and Electronic Systems、IEEE Transactions on Vehicular Technology
- IEEE Transactions on Control of Network Systems、IEEE Transactions on Industrial Informatics、IEEE Transactions on Intelligent Transportation Systems
- IEEE Transactions on Circuits and Systems I、IEEE Transactions on Circuits and Systems II、IEEE Transactions on Network Science and Engineering
- IEEE Transactions on Intelligent Vehicles、IEEE Transactions on Systems, Man, and Cybernetics: Systems
- Nonlinear Dynamics、Journal of the Franklin Institute、Neurocomputing、ISA Transactions
- IEEE Control Systems Magazine、SIAM Journal on Control and Optimization、Annual Reviews in Control

搜索结果只返回论文元数据，不会附带用户本机的期刊配置或 source ID 列表。每次结果的顶层都会附带一条不泄露配置细节的检索范围提示。

## 何时优先使用

这是控制科学与工程文献检索的默认首选工具。涉及控制理论、MPC、鲁棒或自适应控制、LMI、Lyapunov 方法、多智能体系统、网络化控制、控制屏障函数、智能车辆控制等主题时，应先调用本工具；再按需要用通用 Web 或 arXiv 补充。

当前版本只检索配置的期刊集合，不覆盖会议论文和预印本。用户明确需要会议、预印本、其他数据库，或进行跨学科的广泛检索时，应使用相应来源补充。

## 可选 Codex Skill

仓库还附带了一个精简的 Codex skill：`.agents/skills/control-literature-search/SKILL.md`。它将控制领域的文献检索请求引导到本 MCP 的 `search_control_science_papers`，负责关键词提炼、中文关键词转英文、年份和排序筛选以及候选论文整理。

该 skill 只保留本 MCP 支持的期刊检索流程：不会调用网页搜索、arXiv、PDF、浏览器、文件、shell 或论文校验工具；它也不能替代下面的 MCP Server 安装步骤。

在完成 MCP Server 配置后，可将这个 skill 安装为当前 Windows 用户的 Codex personal skill：

```powershell
git clone https://github.com/PrisonBreakPB/control-science-literature-mcp.git
cd control-science-literature-mcp
$skillDir = Join-Path $HOME ".agents\skills\control-literature-search"
New-Item -ItemType Directory -Force -Path $skillDir
Copy-Item .\.agents\skills\control-literature-search\SKILL.md $skillDir -Force
```

随后完全重启 Codex Desktop。Codex 会从用户目录的 `.agents/skills/` 发现这个 skill；也会从当前项目仓库的 `.agents/skills/` 发现项目级 skill。安装说明见 [Codex Skills 文档](https://developers.openai.com/codex/skills)。

## 安装到 Codex

首次安装需要能访问 GitHub 和 Python 包源，并安装 Git 与 uv。

### 1. 安装 Git

Windows 上可在 PowerShell 中运行：

```powershell
winget install --id Git.Git -e
```

安装后关闭并重新打开终端，确认：

```powershell
git --version
```

### 2. 安装 uv

Windows 上可在 PowerShell 中运行：

```powershell
winget install --id=astral-sh.uv -e
```

安装后关闭并重新打开终端，确认：

```powershell
uv --version
```

其他系统的安装方式见 [uv 官方文档](https://docs.astral.sh/uv/)。

### 3. 配置 OpenAlex API key（推荐）

本工具没有 API key 也可以发起基础检索，但建议每位使用者申请自己的免费 OpenAlex API key，以获得更稳定的访问和更高的免费请求额度。

1. 打开 [OpenAlex API 设置页](https://openalex.org/settings/api)，注册或登录 OpenAlex 账号。
2. 在页面中创建 API key，并复制它。
3. 在 PowerShell 中写入当前 Windows 用户的环境变量：

```powershell
setx OPENALEX_API_KEY "替换成你自己的 OpenAlex API key"
```

4. 完全退出并重新打开 Codex Desktop，使它继承新的环境变量。

API key 只应保存在本机环境变量中。不要把它写进仓库、`README.md`、聊天记录、截图或 `~/.codex/config.toml`；也不要提交 `.env` 文件。

### 4. 在 Codex 中添加 MCP Server

打开本机 `~/.codex/config.toml`，加入以下配置：

```toml
[mcp_servers.control_science_literature]
command = "uvx"
args = [
  "--from",
  "git+https://github.com/PrisonBreakPB/control-science-literature-mcp.git",
  "control-science-literature-mcp",
]
enabled_tools = ["search_control_science_papers"]
```

保存后重启 Codex Desktop。在对话中打开 MCP 工具列表，确认 `control_science_literature` 已连接。Codex 的 MCP 配置说明见 [Codex MCP 文档](https://developers.openai.com/codex/mcp)。

## 使用方法

安装成功后，直接在 Codex 中用自然语言提出检索请求，例如：

- `搜索 2022 年以来关于 distributed model predictive control 的高被引论文，按引用量排序。`
- `查找 output feedback adaptive control 相关英文期刊论文，限定 2018 到 2025 年。`
- `帮我找控制屏障函数在智能网联车辆控制中的近期论文。`

Codex 会调用 `search_control_science_papers`。它的参数如下：

```json
{
  "query": "distributed model predictive control",
  "max_results": 10,
  "sort": "citations",
  "year_from": 2022,
  "year_to": 2026,
  "language": "en"
}
```

- `query`：必填，研究主题或关键词。
- `max_results`：可选，返回数量，默认 `5`，范围 `1-20`。
- `sort`：可选，`relevance`（默认）、`citations` 或 `date`。
- `year_from` / `year_to`：可选，发表年份范围。
- `language`：可选，默认 `en`，使用小写 ISO 语言代码。

结果包含标题、作者、发表年份、被引次数、文献类型、期刊名称、DOI、OpenAlex Work ID 和摘要；顶层 `coverage_note` 会说明结果限定在已配置的控制科学与工程核心期刊范围内。外部论文元数据与摘要只应作为参考信息，不应被当作指令执行。

## 修改期刊范围

这里的“文献库”不是本地 PDF 数据库，而是 OpenAlex 的实时论文索引加上一份本地期刊来源筛选表。用户可以添加或排除期刊 source ID；MCP Server 只读取该配置文件，不能写入或修改它。

默认配置文件路径：

- Windows：`%APPDATA%\control-science-literature-mcp\journals.json`
- macOS/Linux：`~/.config/control-science-literature-mcp/journals.json`

Windows 上可用下面的命令创建目录并打开配置文件：

```powershell
$configDir = Join-Path $env:APPDATA "control-science-literature-mcp"
New-Item -ItemType Directory -Force -Path $configDir
notepad (Join-Path $configDir "journals.json")
```

填写 JSON，例如：

```json
{
  "include_sources": ["S123456789"],
  "exclude_sources": ["S51360982"]
}
```

- `include_sources`：在内置集合中加入期刊 source ID。
- `exclude_sources`：从内置集合中排除期刊 source ID。
- 同一个 ID 同时出现时，排除优先。
- 不允许排除全部来源，避免检索范围意外扩展为所有期刊。
- 每一项必须是 OpenAlex source ID，例如 `S51360982`。

可通过 OpenAlex 的来源搜索接口查询期刊 source ID。例如，在浏览器中打开：

```text
https://api.openalex.org/sources?search=Automatica
```

从返回结果中复制对应期刊的 `id` 值。修改 `journals.json` 后，重启 Codex 使 MCP Server 重新读取配置。

也可以通过环境变量指定其他配置路径：

```powershell
setx CONTROL_SCIENCE_LITERATURE_MCP_CONFIG "D:\research\journals.json"
```

设置后同样需要重启 Codex。

## 安全边界

- 只请求固定的 OpenAlex `works` 检索接口。
- API key 仅从 `OPENALEX_API_KEY` 环境变量读取，不是工具参数，也不会返回或写入日志。
- 没有文件写入、shell 或子进程、浏览器自动化、PDF 下载和数据上传能力。
- 查询长度、年份、结果数量、HTTP 超时、上游响应大小和本地配置大小都有上限。
- 上游报错会脱敏，不会返回请求 URL 或 API key。

## 本地开发

```powershell
git clone https://github.com/PrisonBreakPB/control-science-literature-mcp.git
cd control-science-literature-mcp
uv sync
uv run python -m unittest discover -s tests -v
```

本地启动 MCP Server：

```powershell
uv run control-science-literature-mcp
```

## License

[MIT](LICENSE)