Metadata-Version: 2.4
Name: paperflow-mcp
Version: 0.1.0
Summary: PaperFlow MCP Server — 让 agent 调用论文分析能力
Author-email: LiangKaggle <liangkaggle@outlook.com>
Project-URL: Homepage, https://liangkaggle.com
Keywords: mcp,model-context-protocol,paperflow,arxiv,paper-analysis,research
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: mcp>=1.0.0
Requires-Dist: httpx>=0.28.0

# PaperFlow MCP Server

把 PaperFlow 的论文分析能力封装成 [MCP](https://modelcontextprotocol.io) Server，供外部 agent（Claude Desktop / Claude Code / Cursor / OpenClaw 等）调用。

## 状态

- **P0 ✅**：stdio 传输，工具 `analyze_paper` / `get_paper`，临时 JWT 鉴权。
- **P1 ✅**：API Key 鉴权（`X-API-Key`）+ 管理端点 `/api/v1/api-keys`。
- **P2 ✅**：综述工具 `create_survey` / `get_survey` + MCP Resources（`paperflow://papers/{id}`、`paperflow://surveys/{id}`）+ 打包（console 入口 `paperflow-mcp`）。
- P3：正式发布（MCP registry / ClawHub / 官网文档）。

## 安装

方式一（源码，开发）：

```bash
cd mcp_server
python -m venv .venv
.venv/bin/pip install -e .
```

方式二（一键运行，分发给外部用户）：

```bash
# 已发布到 PyPI 后
uvx paperflow-mcp        # 或 pipx run paperflow-mcp
```

## 运行配置

环境变量：

| 变量 | 说明 | 默认 |
|---|---|---|
| `PAPERFLOW_BASE_URL` | PaperFlow 后端地址 | `http://localhost:8000` |
| `PAPERFLOW_TOKEN` | 临时 JWT（P0 用） | 必填 |
| `PAPERFLOW_API_KEY` | API Key（推荐，P1 已完成） | - |
| `PAPERFLOW_API_KEY_FILE` | 从文件读取 API Key（用于不把密钥写进配置） | - |

> 凭证绝不写入仓库；通过运行 MCP 的客户端注入环境变量。
>
> 已配置 `PAPERFLOW_API_KEY` 时优先用 `X-API-Key` 认证，否则回落到 `PAPERFLOW_TOKEN`（JWT）。
> API Key 通过 `POST /api/v1/api-keys`（携带网页登录凭证）生成，明文仅返回一次。

## MCP 客户端接入示例（Claude Desktop / OpenClaw）

```json
{
  "mcpServers": {
    "paperflow": {
      "command": "/absolute/path/to/mcp_server/.venv/bin/python",
      "args": ["-m", "paperflow_mcp.server"],
      "env": {
        "PAPERFLOW_BASE_URL": "http://localhost:8000",
        "PAPERFLOW_TOKEN": "<jwt>"
      }
    }
  }
}
```

## 工具

- `analyze_paper(arxiv_url | text, route=quick, wait_seconds=300)` — 提交并等待论文分析
- `get_paper(paper_id, include_agents=False)` — 查询论文状态 / 结果
- `create_survey(topic, max_papers=50, date_start=0, date_end=0, wait_seconds=600)` — 生成研究综述
- `get_survey(survey_id)` — 查询综述报告

## 资源（Resources）

- `paperflow://papers/{paper_id}` — 论文完整分析（markdown）
- `paperflow://surveys/{survey_id}` — 综述完整报告（markdown）

## 说明

- MCP Server 是独立进程，**由使用者（MCP 客户端）启动**，不影响后端服务。
- 每次调用等同一次普通分析，按现有计费规则扣费（quick ¥0.10 / deep ¥0.30 / full ¥0.50）。
