PaperQA MCP 服务器

使用说明（Markdown 格式）

• 项目简介

  • 该仓库实现了一个基于 Model Context Protocol（MCP）的服务器端，整合 PaperQA2，用于向大型语言模型（LLM）客户端提供跨论文的阅读、检索、综合分析和工具执行能力。服务器通过注册工具（Tools）和提示（Prompts）等能力，为 LLM 提供可编排的上下文信息和外部功能访问。当前实现采用 stdio 传输模式，支持与 Claude Desktop 等客户端通过 MCP 进行 JSON-RPC 交互。

• 主要功能点

  • 通过 MCP 工具暴露功能：如 paper_qa（跨论文的深度阅读与综合回答）、index_status（索引状态查询）等。
  • 集成 PaperQA2 的索引与嵌入能力：基于配置的论文目录进行分块、嵌入与检索，支持按需查询。
  • 会话与配置管理：通过环境变量控制 LLM、嵌入模型、索引参数等，提供可重复的执行设置。
  • 支持多种传输方式（当前实现为 stdio）：可接入 MCP 客户端（如 Claude Desktop）并通过配置启动。
  • 提供命令行索引构建入口：paperqa-mcp-server index，用于预构建论文索引，避免首次查询时的耗时与成本。
  • 兼容性与扩展性：服务器端定义的工具可以继续扩展，加入更多基于 PaperQA2 的分析能力。

• 安装步骤

  • 准备工作
    • 安装 Python 运行环境，并熟悉使用 uv（Python 包管理器）进行依赖管理与执行。
    • 获取 OpenAI API Key（用于嵌入与推理）。
  • 依赖与启动
    • 使用 uvx 安装并缓存依赖（首次运行会下载大量包，请耐心等待）。
    • 设置环境变量，例如 OPENAI_API_KEY、PAPER_DIRECTORY、PQA_LLM、PQA_SUMMARY_LLM、PQA_EMBEDDING 等，确保默认值与您的环境匹配。
  • 索引构建
    • 将论文放置在 PAPER_DIRECTORY 指定的目录（默认为 ~/Zotero/storage）。
    • 运行索引构建：在终端执行 uvx paperqa-mcp-server index（或按照 README 的步骤在合适的环境中执行）。
    • 索引完成后会缓存至 ~/.pqa/indexes/，后续更新只需重新索引变更的文件。
  • 启动服务器
    • 使用 MCP 客户端连接时，请在终端或集成环境中启动服务器：
      • uv run paperqa-mcp-server
    • 服务器以 stdio 方式对外，MCP 客户端通过命令与参数启动并建立连接。

• 服务器配置（给 MCP 客户端的启动项示例，实际路径请依据本地环境替换）

  • server_name: paperqa
  • command: /path/to/uvx
  • args: ["paperqa-mcp-server"]
  • env: OPENAI_API_KEY: "sk-your-key-here" PAPER_DIRECTORY: "/full/path/to/your/pdfs" (如需覆盖默认的 Zotero 存储目录，请修改为实际路径) 说明：该配置用于 MCP 客户端在启动时以指定的命令和参数启动 MCP 服务器，并通过环境变量注入所需的配置信息（如 API Key、论文目录等）。具体字段含义如上，实际使用中请将路径与密钥替换为自己的环境信息。

• 基本使用方法

  • 先确保已完成索引构建（若需对新添加的论文检索，请重新执行 index 进行增量索引）。
  • 在 MCP 客户端通过 paperqa 工具向服务器发起查询，例如请求跨论文深度阅读与综合回答。
  • 如遇“Index incomplete”等提示，请按照文档步骤完成索引构建后再查询。
  • 如需查看索引状态，可调用 index_status 工具获取当前索引健康信息与进度。