hal-mcp

프랑스 국립 오픈 아카이브인 HAL(Hyper Articles en Ligne)용 MCP(Model Context Protocol) 서버입니다. AI 어시스턴트(Claude 또는 MCP 호환 클라이언트)가 HAL을 조회해 출판물 검색, 통계 계산, 인용 내보내기, 연구자의 성과 추적을 할 수 있습니다.

API 키가 필요 없습니다. 패싯(집계 통계), IdHAL 저자 추적, 자체 바이블리오그래픽 내보내기까지 단순 검색을 넘어서는 기능을 제공합니다.

주요 기능(6가지 도구)

Related MCP server: Crossref Academic MCP Server

요구 사항

• Python 3.10 이상

• mcp SDK, 버전 1.x(아래 오류 참고)

⚠️ 중요 — mcp SDK 버전 이 서버는 mcp v2.0.0에서 제거된 FastMCP를 사용합니다. 따라서 프로젝트에서는 버전을 mcp>=1.2.0,<2.0.0로 고정합니다. 시작 시 FastMCP 관련 import 오류가 발생하면 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의 "python" 대신 인터프리터의 전체 경로(예: Windows의 C:\\Python313\\python.exe)를 사용하세요.

예시 질문

• "2023년 이후 연합 학습에 관련 오픈 액세스 논문을 찾아줘."

• "IdHAL dominique-lesselier 연구자의 전체 성과를 공동 저자와 함께 보여줘."

• "딥러닝 출발물의 연도별 분류를 알려줘."

• "트랜스포머에 관한 논문 최근 10개를 BibTeX로 내보내줘."

• "양자 물리학을 다루는 연구실은 어떤 곳들?"

동작 원리

HAL은 Apache Solr 기반의 검색 API를 인증 없이 HTTP로 조회할 수 있게 제공합니다. 이 서버는 사용자 친화적인 매개변수(year_from, doc_type, open_access_only...)를 Solr 구문(fq, facet, wt...)으로 변환해 주므로, 에이전트는 Solr의 강력한 기능(필터, 패싯, 내보내기)을 그대로 활용하면서도 단순한 인터페이스를 이용할 수 있습니다.

• 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 — 특정 연구소의 성과 출력.

• Pivot facets(교차 유형 × 전체 텍스트, 연도 × 유형).

• 시계열·추이 그래프를 위한 범위 패싯(facet.range).

• 컬렉션/포털 필터링 매개변수.

• Claude.ai(커넥터) 및 ChatGPT(개발자 모드)용 HTTP 전송 계층.

라이선스

MIT — 자세한 내용은 LICENSE 파일을 참고하세요.

면책 조항

독립 프로젝트이며, HAL을 운영하는 CCSD와 제휴나 아래 관계가 없습니다. 메타데이터는 HAL의 공개 API에서 가져옵니다. HAL의 이용 약관과 각 개별 출판물의 라이선스를 준수하시기 바랍니다.