内容
# arx
`arx` 是一个本地 arXiv 缓存，拥有两个可单独运行的界面：
- `arx`：一个独立的核心命令行界面，用于获取、定位和检查缓存的 arXiv 论文，无需任何代理或 MCP 运行时。
- `arx-mcp`：一个_stdio MCP 服务器，暴露相同的核心获取器给代理。
共享的核心下载 arXiv 元数据、PDF 和 TeX/源文件到 XDG 缓存，并记录在源中发现的 arXiv-to-arXiv 引用为 JSONL。
该缓存可安全地在单台机器上供多个代理使用：arXiv 网络请求通过共享的文件系统锁和共享的速率限制状态文件序列化，因此单独的命令行界面和 MCP 服务器进程遵循相同的延迟。
## 工作空间布局
```text
crates/
arx-core/ # arXiv 获取、缓存路径、源提取、引用、速率限制
arx-cli/ # 独立的 `arx` 二进制；无 MCP 依赖
arx-mcp/ # stdio `arx-mcp` MCP 服务器和 MCP 设置助手
```
## 功能
- 独立的命令行界面：
- `arx fetch <ID>`
- `arx locate <ID>`
- `arx cache-dir`
- MCP stdio 服务器，包含两个工具：
- `fetch_arxiv_paper`：下载/缓存论文并返回路径。
- `locate_cached_arxiv_paper`：在无网络访问的情况下返回缓存路径。
- 下载 arXiv 元数据、PDF 和源/e-打印包。
- 在可能的情况下提取源存档。
- 将在源/BibTeX 文件中发现的 arXiv-to-arXiv 引用写入 `citations.jsonl`。
- 在 XDG 缓存目录下缓存，以备将来访问。
- 在跨进程之间强制执行 3 秒的 arXiv 请求延迟。
- 在 `arx-mcp` 中包含 MCP 设置助手，以便 harness 可以直接从配置启动服务器。
## 安装
推荐从最新的 GitHub 发布版本安装：
```bash
curl -fsSL https://raw.githubusercontent.com/eric-tramel/arx/main/install.sh | sh
```
Windows PowerShell：
```powershell
irm https://raw.githubusercontent.com/eric-tramel/arx/main/install.ps1 | iex
```
安装程序下载匹配的发布存档并安装两个二进制文件：`arx` 和 `arx-mcp`。
覆盖默认值：
```bash
ARX_VERSION=v0.1.0 ARX_INSTALL_DIR=$HOME/bin sh install.sh
```
```powershell
$env:ARX_VERSION = "v0.1.0"
$env:ARX_INSTALL_DIR = "$HOME\\bin"
.\\install.ps1
```
从检出中安装两个二进制文件：
```bash
cargo install --path crates/arx-cli
cargo install --path crates/arx-mcp
```
或从工作空间运行：
```bash
cargo run -p arx -- fetch 0704.0001
cargo run -p arx-mcp -- serve
```
`arx-mcp serve` 是默认的 MCP 命令，因此 MCP 客户端可以启动 `arx-mcp` 时不带参数或带 `serve`。
## 独立命令行界面用法
在 MCP 外获取论文：
```bash
arx fetch 0704.0001
```
定位缓存文件，无需网络访问：
```bash
arx locate 0704.0001
```
打印缓存目录：
```bash
arx cache-dir
```
刷新现有的缓存文件：
```bash
arx fetch 0704.0001 --refresh
```
跳过 PDF 或源下载：
```bash
arx fetch 0704.0001 --include-pdf=false
arx fetch 0704.0001 --include-source=false
```
获取输出为结构化 JSON：
```json
{
"arxiv_id": "0704.0001",
"cache_dir": "/home/user/.cache/arx/papers/0704.0001",
"metadata_path": "/home/user/.cache/arx/papers/0704.0001/metadata.json",
"pdf_path": "/home/user/.cache/arx/papers/0704.0001/paper.pdf",
"source_archive_path": "/home/user/.cache/arx/papers/0704.0001/source/e-print.tar.gz",
"source_extracted_dir": "/home/user/.cache/arx/papers/0704.0001/source/extracted",
"citations_jsonl_path": "/home/user/.cache/arx/papers/0704.0001/citations.jsonl",
"cache_hit": false,
"network_requests": 3,
"rate_limit_delay_seconds": 3
}
```
## MCP 用法
直接运行 MCP 服务器：
```bash
arx-mcp serve
```
打印一个可以直接复制的 MCP 配置片段：
```bash
arx-mcp print-config
```
示例格式：
```json
{
"mcpServers": {
"arx": {
"command": "/path/to/arx-mcp",
"args": ["serve"]
}
}
}
```
对于 Claude Desktop，安装或更新 `arx` MCP 条目：
```bash
arx-mcp install-claude-desktop
```
写入特定的配置文件而不是平台默认值：
```bash
arx-mcp install-claude-desktop --config-path /path/to/claude_desktop_config.json
```
## 缓存布局
缓存根目录解析：
1. `$ARX_CACHE_DIR`（如果设置）。
2. `$XDG_CACHE_HOME/arx`（如果设置）。
3. `~/.cache/arx`。
论文文件存储在：
```text
<cache-root>/papers/<safe-arxiv-id>/
metadata.json
paper.pdf
citations.jsonl
source/
manifest.json
e-print.tar.gz
extracted/
```
旧式 arXiv ID（如 `hep-th/9901001`）会进行路径净化，例如 `hep-th_9901001`。
## 速率限制
arXiv 要求 API 客户端每 3 秒钟内最多发出一个请求。`arx-core` 通过缓存根目录中的共享文件强制执行此操作：
```text
<cache-root>/arxiv-rate-limit.lock
<cache-root>/arxiv-rate-limit.json
```
每个元数据、PDF 或源请求都必须获取相同的锁并更新相同的下一个允许时间戳。这保持了跨多个代理、独立命令行界面运行和同一系统上的多个 MCP 服务器进程的延迟一致性。
## 引用 JSONL
当获取源文件时，`arx-core` 会扫描文本源文件中的 arXiv 引用，例如：
- `arXiv:2401.12345`
- `https://arxiv.org/abs/2401.12345`
- `https://arxiv.org/pdf/hep-th/9901001`
- BibTeX `archivePrefix = {arXiv}` 及 `eprint = {...}`
每个发现的非自引用 arXiv 引用都会被写入 `citations.jsonl`：
```jsonl
{"citing_arxiv_id":"2401.12345v2","cited_arxiv_id":"2101.00001v2","source_file":".../main.tex","line":12,"context":"See arXiv:2101.00001v2."}
```
## 发布 CI 和分发
GitHub Actions 在每次推送到 `main` 分支和每个 `v*` 版本标签时都会构建发布二进制文件：
- Linux x86_64：`arx-x86_64-unknown-linux-gnu.tar.gz`
- macOS arm64：`arx-aarch64-apple-darwin.tar.gz`
- Windows x86_64：`arx-x86_64-pc-windows-msvc.zip`
推送到 `main` 分支会产生工作流产物以供验证。版本标签会发布相同的存档和 `.sha256` 文件到 GitHub Releases。
分发策略：GitHub Releases 加上 tiny `install.sh` 和 `install.ps1` 引导安装程序。这在 Linux/macOS/Windows 上保持低安装摩擦，无需添加包管理器基础设施即可满足需求。稍后可以使用相同的发布存档分发 Homebrew/Scoop/cargo-dist。
创建发布：
```bash
git tag v0.1.0
git push origin v0.1.0
```
## 开发
```bash
cargo fmt
cargo test --workspace
cargo run -p arx -- locate 0704.0001
cargo run -p arx-mcp -- print-config
```
MCP 烟雾测试可以使用任何支持 stdio 服务器的 MCP 客户端完成，或者使用 `arx-mcp print-config` 生成的配置。
## arXiv 使用
此工具存储 arXiv 内容以供个人/研究使用。在使用或重新分发下载内容时，请尊重 arXiv 的 API 条款和版权限制。
相关的 arXiv API 条款：<https://info.arxiv.org/help/api/tou.html>
## 许可证
MIT
