git clone https://github.com/neosun100/mineru-mcp-server.git
cd mineru-mcp-server
./install_mcp.sh

cp config/accounts.yaml.example config/accounts.yaml
vi config/accounts.yaml  # 填入账号信息

.venv/bin/python3 src/batch_login.py

"帮我处理 ~/Documents/report.pdf"
"处理 ~/Documents 目录下所有 PDF"
"查看 MinerU 的 Token 状态"

# 批量异步并行
.venv/bin/python3 src/mineru_batch_async.py ~/Documents '*.pdf'

# 1. 克隆仓库
git clone https://github.com/neosun100/mineru-mcp-server.git
cd mineru-mcp-server

# 2. 创建虚拟环境（必须用 uv，避免环境冲突）
uv venv
source .venv/bin/activate

# 3. 安装运行时依赖（必须用 uv pip）
uv pip install -r requirements.txt
.venv/bin/playwright install chromium

# 4. 安装开发依赖（可选，跑测试时需要）
uv pip install -r requirements-dev.txt

# 5. 配置账户
cp config/accounts.yaml.example config/accounts.yaml
vi config/accounts.yaml

# 6. 批量登录
.venv/bin/python3 src/batch_login.py

{
  "mcpServers": {
    "mineru": {
      "command": "/path/to/mineru-mcp-server/.venv/bin/python3",
      "args": ["/path/to/mineru-mcp-server/src/mineru_mcp_server.py"],
      "env": {
        "PYTHONPATH": "/path/to/mineru-mcp-server/src"
      }
    }
  }
}

cp -r skills/mineru-token-manager ~/.kiro/skills/

# 默认（不调网络）
.venv/bin/python3 -m pytest

# 全量含 e2e（真调 API）
RUN_E2E=1 .venv/bin/python3 -m pytest

# 按 marker
.venv/bin/python3 -m pytest -m unit
.venv/bin/python3 -m pytest -m regression

mineru-mcp-server/
├── src/                                # 核心代码（10 个模块）
│   ├── mineru_mcp_server.py            # ① MCP 接入层
│   ├── auto_split.py                   # ② 拆分协调
│   ├── mineru_batch_async.py           # ② 批量协调
│   ├── mineru_async.py                 # ② 单文件协调 + ③ 精准 API 客户端
│   ├── agent_api.py                    # ③ Agent 轻量 API 客户端
│   ├── progress.py                     # ② 进度回调
│   ├── api_errors.py                   # ④ 错误码表 + 重试策略
│   ├── token_manager.py                # ④ Token 管理
│   ├── path_fixer.py                   # ④ Markdown 路径修复
│   ├── split_large_file.py             # ④ PDF 物理拆分
│   └── batch_login.py                  # ⑤ headless 自动登录
│
├── tests/                              # 87 个测试
│   ├── unit/                           # 30 单元测试
│   ├── integration/                    # 31 集成测试
│   ├── regression/                     # 24 回归测试（防 bug 复发）
│   ├── e2e/                            # 2 端到端测试（真调 API）
│   └── README.md                       # 测试运行手册
│
├── docs/                               # 完整文档
│   ├── CHANGELOG.md                    # 详细变更日志
│   ├── API_V4_REFERENCE.md             # 官方 API 参数完整参考
│   ├── images/                         # 4 张架构 / 流程图
│   └── ...
│
├── config/
│   └── accounts.yaml.example           # 账号配置模板
│
├── skills/
│   └── mineru-token-manager/           # Kiro Skill
│
├── requirements.txt                    # 运行时依赖
├── requirements-dev.txt                # 开发依赖
├── install_mcp.sh                      # 一键安装脚本
└── README.md                           # 本文档