hal-mcp

Сервер MCP (Model Context Protocol) для HAL — французского национального открытого архива (Hyper Articles en Ligne). Он позволяет ИИ-ассистенту — Claude или любому MCP-совместимому клиенту — запрашивать HAL: искать публикации, вычислять статистику, экспортировать цитаты и отслеживать результаты исследователя.

Не требуется API-ключ. Он выходит за рамки простого поиска благодаря фасетам (агрегированная статистика), отслеживанию авторов по IdHAL и встроенному библиографическому экспорту.

Возможности (6 инструментов)

Related MCP server: Crossref Academic MCP Server

Требования

• Python 3.10 или новее

• SDK mcp версии 1.x (см. важное примечание ниже)

⚠️ Важно — версия SDK mcp Этот сервер использует 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, чтобы остановить его. (Если вместо этого вы получили ошибку, см. примечание о SDK mcp выше.)

2. Интерактивное тестирование с MCP Inspector

Официальный инструмент для изучения MCP-сервера без полного клиента:

npx @modelcontextprotocol/inspector python -m hal_mcp.server

Откройте напечатанный URL, нажмите Подключиться, затем Список инструментов: появятся 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, используйте полный путь к вашему интерпретатору (например, C:\\Python313\\python.exe в Windows) вместо "python" в command.

Примеры вопросов

• "Найдите статьи в открытом доступе по федеративному обучению с 2023 года."

• "Покажите публикации исследователя с IdHAL dominique-lesselier, с соавторами."

• "Какова разбивка публикаций по глубокому обучению по годам?"

• "Экспортируйте 10 самых свежих публикаций по трансформерам в BibTeX."

• "Какие лаборатории занимаются квантовой физикой?"

Как это работает

HAL предоставляет поисковый API на основе Apache Solr, доступный по HTTP без аутентификации. Этот сервер преобразует удобные для человека параметры (year_from, doc_type, open_access_only...) в синтаксис Solr (fq, facet, wt...), поэтому агент получает простой интерфейс, сохраняя при этом преимущества Solr (фильтры, фасеты, экспорт).

• Документация API HAL: 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 — публикации заданной лаборатории.

• Сводные фасеты (пересечение типа × полный текст, год × тип).

• Диапазонные фасеты (facet.range) для графиков временных рядов/эволюции.

• Фильтрация по коллекциям / порталам, доступная как параметр.

• HTTP-транспорт для Claude.ai (коннектор) и ChatGPT (режим разработчика).

Лицензия

MIT — см. файл LICENSE.

Отказ от ответственности

Независимый проект, не связан с CCSD (который управляет HAL). Метаданные получены из публичного API HAL. Пожалуйста, соблюдайте условия использования HAL и лицензию каждой отдельной публикации.