hal-mcp

一个用于 HAL（法国国家开放存档库，Hyper Articles en Ligne）的 MCP（模型上下文协议）服务器。它让 AI 助手——Claude 或任何兼容 MCP 的客户端——能够查询 HAL：搜索出版物、计算统计数据、导出引文，以及追踪研究者的成果。

无需 API 密钥。它超越了简单的搜索，提供 facets（聚合统计）、按 IdHAL 追踪作者，以及原生 书目导出 功能。

功能（6 个工具）

Related MCP server: Crossref Academic MCP Server

环境要求

• Python 3.10 或更高版本

• mcp SDK，版本 1.x（请参阅下方重要说明）

⚠️ 重要 — mcp SDK 版本 此服务器使用 FastMCP，而它在 mcp v2.0.0 中已被移除。 因此项目将版本锁定为 mcp>=1.2.0,<2.0.0。如果在启动时看到 FastMCP 导入错误，说明误装了 v2：请使用 pip install "mcp<2.0.0" 重新安装。

安装

git clone https://github.com/Arpany-Tech/hal-mcp
cd hal-mcp
pip install -e .

验证是否正常工作

1. 检查服务器能否启动

python -m hal_mcp.server

光标悬停且无输出：这是预期行为。服务器正在运行，并在标准输入上等待 MCP 消息。按 Ctrl+C 停止它。 （如果出现错误，请参阅上方 mcp SDK 说明。）

2. 使用 MCP Inspector 进行交互式测试

无需完整客户端即可探索 MCP 服务器的官方工具：

npx @modelcontextprotocol/inspector python -m hal_mcp.server

打开打印的 URL，点击 Connect，然后点击 List Tools：6 个工具会显示出来。你可以逐个手动调用并检查响应。

3. 直接测试 API 层（不经过 MCP）

python3 - << 'PY'
import asyncio
from hal_mcp import client

async def main():
    res = await client.search_publications(
        "artificial intelligence", year_from=2023,
        open_access_only=True, rows=3,
    )
    print("Total:", res["total"])
    for d in res["documents"]:
        print("-", d.get("label_s"))

asyncio.run(main())
PY

连接到 Claude Desktop

在 claude_desktop_config.json 中（设置 → 开发者 → 编辑配置）：

{
  "mcpServers": {
    "hal": {
      "command": "python",
      "args": ["-m", "hal_mcp.server"]
    }
  }
}

完全重启 Claude Desktop。HAL 工具会出现在消息框的工具指示器中。

提示：如果 Claude Desktop 找不到 python，请在 command 中使用解释器的完整路径（例如 Windows 上的 C:\\Python313\\python.exe），而不是 "python"。

示例问题

• "查找 2023 年以来关于联邦学习的开放获取文章。"

• "给我 IdHAL 为 dominique-lesselier 的研究者的成果，包含合作者。"

• "深度学习出版物的逐年分布是怎样的？"

• "将关于 transformers 的最新 10 篇出版物导出为 BibTeX。"

• "哪些实验室在研究量子物理？"

工作原理

HAL 提供了一个基于 Apache Solr 构建的搜索 API，可通过 HTTP 查询，无需身份验证。此服务器将人性化参数（year_from、doc_type、open_access_only...）转换为 Solr 语法（fq、facet、wt...），使代理获得简单接口的同时仍能利用 Solr 的强大功能（过滤器、facets、导出）。

• HAL API 文档：https://api.archives-ouvertes.fr/docs/search

• 结构参考：https://api.archives-ouvertes.fr/docs/ref/resource/structure

架构

src/hal_mcp/
├── server.py    # declares the 6 MCP tools (FastMCP)
├── client.py    # calls to HAL's Solr API (httpx)
└── fields.py    # constants: Solr fields, document types

client.py 层不依赖 MCP：可以独立测试。

开发

运行测试：

pip install pytest pytest-asyncio
pytest                    # all tests
pytest -m "not network"   # unit tests only (offline, fast)
pytest -m network         # integration tests that call HAL

路线图

• get_structure_output — 指定实验室的成果。

• 透视 facets（类型 × 全文、年份 × 类型）。

• 范围 facets（facet.range），用于时间序列/演变图表。

• 集合 / 门户过滤作为参数公开。

• 为 Claude.ai（连接器）和 ChatGPT（开发者模式）提供 HTTP 传输。

许可证

MIT — 请参阅 LICENSE 文件。

免责声明

独立项目，与运营 HAL 的 CCSD 无关联。元数据来自 HAL 的公共 API。请遵守 HAL 的使用条款以及每篇出版物的许可证。