# Licensed Academic Archive Gateway (Stealth MCP)

专为 AI 助手（Codex、Claude Desktop 等）设计的本地 MCP 插件，用于检索和下载电子书。

## 一键安装

**前提：** 需要 Python 3.12+，以及一个免费的 Z-Library 账号。

1. 把整个文件夹放到一个固定位置（不要放在临时目录）
2. macOS 双击 `一键安装.command`，Windows 双击 `一键安装.bat`
3. 按提示输入 Z-Library 邮箱和密码
4. 脚本会自动创建虚拟环境、安装依赖、配置 Codex

完成后打开 Codex 即可使用。

## 手动配置

如果不用一键安装脚本，按以下步骤操作：

### 1. 创建虚拟环境

```bash
cd academic-archive-gateway
python3.12 -m venv venv
venv/bin/pip install fastmcp httpx playwright beautifulsoup4 pydantic python-dotenv
venv/bin/playwright install chromium
```

### 2. 配置 MCP

**Codex CLI** — 编辑 `~/.codex/config.toml`：

```toml
[mcp_servers.academic-gateway]
command = "/你的路径/academic-archive-gateway/venv/bin/python3"
args = ["/你的路径/academic-archive-gateway/stealth_mcp.py"]
[mcp_servers.academic-gateway.env]
ARCHIVE_USER = "你的邮箱"
ARCHIVE_TOKEN = "你的密码"
ANNAS_BASE_URL = "https://annas-archive.gl"
```

**Codex GUI** — 在自定义 MCP 配置界面填写：

| 字段 | 内容 |
|---|---|
| 名称 | `academic-gateway` |
| 协议 | STDIO |
| 启动命令 | `/你的路径/academic-archive-gateway/venv/bin/python3` |
| 参数 | `/你的路径/academic-archive-gateway/stealth_mcp.py` |
| 环境变量 ARCHIVE_USER | 你的 Z-Library 邮箱 |
| 环境变量 ARCHIVE_TOKEN | 你的 Z-Library 密码 |
| 环境变量 ANNAS_BASE_URL | `https://annas-archive.gl` |

**QoderWork** — 编辑 `~/.qoderworkcn/mcp.json`：

```json
{
  "mcpServers": {
    "academic-gateway": {
      "command": "/你的路径/academic-archive-gateway/venv/bin/python3",
      "args": ["/你的路径/academic-archive-gateway/stealth_mcp.py"],
      "env": {
        "ARCHIVE_USER": "你的邮箱",
        "ARCHIVE_TOKEN": "你的密码",
        "ANNAS_BASE_URL": "https://annas-archive.gl"
      },
      "enabled": true
    }
  }
}
```

## 使用方式

对 AI 说：

> "用学术档案网关帮我搜索《Evicted》"

AI 会自动搜索并把书下载到桌面 `Archival_Documents` 文件夹。

## 可用工具

- `search_academic_literature` — 搜索书籍（返回书名、作者、格式、大小、download_path）
- `fetch_archival_document` — 下载书籍（传入 archival_id 和 download_path）
- `search_annas_archive` — 备用搜索（Anna's Archive）
- `fetch_annas_document` — 备用下载

## 注意事项

- Z-Library 免费账号每天限 10 次下载
- 下载路径固定为 `~/Desktop/Archival_Documents/`
- **代理**：安装脚本会询问是否需要代理。也可通过 `PROXY_URL` 环境变量手动设置（如 `http://127.0.0.1:7890`）。不设则直连。
- **浏览器路径**：默认自动检测。仅 macOS ARM64 遇到 "进程被杀" 问题时需手动通过 `CHROMIUM_PATH` 环境变量指定完整 Chrome 路径。
- Anna's Archive 镜像地址可通过 `ANNAS_BASE_URL` 环境变量切换