使用说明内容（Markdown格式）

项目简介

OpenAlex MCP Server 是一个面向 AI Agent 的后端服务，提供对 OpenAlex 数据的标准化访问接口。通过 7 套工具（简单搜索、高级查询、获取详情、随机采样、批量查询、自动补全、N-grams），以及对多种实体类型的支持，为 LLM 客户端提供可扩展、可控的学术研究上下文服务。

主要功能点

• search_openalex：简单关键词搜索某一实体（论文、作者、机构等）
• query_openalex：高级查询，支持自定义过滤、游标分页、字段选择与分组聚合
• fetch_openalex：获取单个实体的详细信息
• sample_openalex：随机采样，支持种子以实现可重复性
• batch_fetch_openalex：一次性批量查询多个标识符（最多50个）
• autocomplete_openalex：名称自动补全，快速获取实体ID
• ngrams_openalex：获取论文的 N-grams 数据用于文本分析
• 支持的实体类型：works, authors, sources, institutions, topics, publishers, funders, keywords, continents, countries
• 具备错误处理、分页游标、分组聚合等 MCP 服务器核心能力
• 运行模式：标准输入输出（stdio）模式与 HTTP 模式（需要传入 --http 参数启动，端口默认为 8000）

安装步骤

• 安装前提：Python 环境（建议使用 venv）
• 安装依赖：在项目根目录执行安装命令，以安装所需的 Python 包（如 fastmcp、httpx 等）
• 启动方式：
  • stdio 模式：在命令行执行 python openalex_mcp_server.py
  • HTTP 模式：在命令行执行 python openalex_mcp_server.py --http
  • HTTP 模式默认监听端口 8000，允许通过 MCP 客户端以 HTTP JSON-RPC 与服务器通信

服务器配置（MCP 客户端使用的配置JSON示例说明）

说明：MCP 客户端需要一个描述服务器启动信息的配置JSON，包含服务器名称、启动命令及参数等信息。以下为基于本仓库实现的准确描述（文本形式，非代码块展示）：

• server name（服务器名称，用于在客户端识别目标服务器）：openalex
• command（启动服务器所使用的命令）：python
• args（启动服务器时传入的参数，按顺序列出）：openalex_mcp_server.py
• 说明：默认以标准输入输出方式运行；若通过命令行传入 --http 即进入 HTTP 传输模式，端口为 8000。MCP 客户端无需额外配置其他参数，仅通过该项信息建立连接并发送请求。

注：

• 服务器依赖环境变量 OPENALEX_EMAIL，用于 OpenAlex API 请求的邮件标识，若未设置将使用默认值 [email protected]
• 实际部署中可以在环境变量中覆盖 OPENALEX_EMAIL
• 以上信息是用于 MCP 客户端创建对接连接的描述性配置，不需要在客户端执行代码

基本使用方法

• 连接方式：通过 MCP 客户端连接，选择 stdio 或 HTTP 传输模式
• 调用方式：使用客户端提供的工具名（如 search_openalex、query_openalex 等）及参数进行请求，服务器返回 JSON-RPC 的结果
• 运行测试：可使用仓库中的测试脚本 test_server.py 进行全集成测试（需在可访问 OpenAlex API 的环境中执行）

关键注意事项

• 若使用 HTTP 模式，确保端口 8000对外可达，且网络没有阻断
• 请求应遵循 OpenAlex 的过滤与语法要求，工具内已有输入校验与错误处理
• 生产环境可结合 OpenAlex 的速率限制策略进行重试与限流设计