<!-- 🇬🇧 English | [🇫🇷 Français](README.fr.md) -->

# hal-mcp

An **MCP** (Model Context Protocol) server for **HAL**, the French national
open archive (Hyper Articles en Ligne). It lets an AI assistant — Claude, or any
MCP-compatible client — query HAL: search publications, compute statistics,
export citations, and track a researcher's output.

No API key required. It goes beyond simple search with **facets** (aggregate
statistics), **author tracking by IdHAL**, and native **bibliographic export**.

## Features (6 tools)

| Tool | Description |
|------|-------------|
| `search_publications` | Search with human-friendly filters: year range, document type, open access, full-text availability, sorting. |
| `get_publication` | Full record for a single document by its HAL identifier. |
| `export_citations` | Export to BibTeX / EndNote / CSV / TEI (via HAL's native `wt` parameter). |
| `get_publication_stats` | Aggregate counts (by year, type, keyword, author) using Solr facets. |
| `get_author_production` | Complete output of a researcher by IdHAL, with most frequent co-authors optionally. |
| `search_structures` | Search for laboratories / research structures. |

## Requirements

- Python 3.10 or newer
- The `mcp` SDK, version **1.x** (see the important note below)

> **⚠️ Important — `mcp` SDK version**
> This server uses `FastMCP`, which was **removed in `mcp` v2.0.0**.
> The project therefore pins `mcp>=1.2.0,<2.0.0`. If you see a `FastMCP`
> import error at startup, v2 was installed by mistake: reinstall with
> `pip install "mcp<2.0.0"`.

## Installation

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

## Verify it works

### 1. Check the server starts

```bash
python -m hal_mcp.server
```

The cursor hangs with no output: this is **expected**. The server is running
and waiting for MCP messages on standard input. Press `Ctrl+C` to stop it.
(If you get an error instead, see the `mcp` SDK note above.)

### 2. Interactive testing with MCP Inspector

The official tool to explore an MCP server without a full client:

```bash
npx @modelcontextprotocol/inspector python -m hal_mcp.server
```

Open the printed URL, click **Connect**, then **List Tools**: the 6 tools
appear. You can call each one by hand and inspect the responses.

### 3. Test the API layer directly (no MCP)

```bash
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
```

## Connect to Claude Desktop

In `claude_desktop_config.json` (Settings → Developer → Edit Config):

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

Fully restart Claude Desktop. The HAL tools appear in the tools indicator of the
message box.

> Tip: if Claude Desktop can't find `python`, use the full path to your
> interpreter (e.g. `C:\\Python313\\python.exe` on Windows) instead of
> `"python"` in `command`.

## Example questions

- "Find open-access articles on federated learning since 2023."
- "Give me the output of the researcher with IdHAL `dominique-lesselier`, with co-authors."
- "What is the year-by-year breakdown of deep learning publications?"
- "Export the 10 most recent publications on transformers to BibTeX."
- "Which laboratories work on quantum physics?"

## How it works

HAL exposes a search API built on **Apache Solr**, queryable over HTTP with no
authentication. This server translates human-friendly parameters (`year_from`,
`doc_type`, `open_access_only`...) into Solr syntax (`fq`, `facet`, `wt`...), so
the agent gets a simple interface while still benefiting from Solr's power
(filters, facets, exports).

- HAL API documentation: https://api.archives-ouvertes.fr/docs/search
- Structure reference: https://api.archives-ouvertes.fr/docs/ref/resource/structure

## Architecture

```
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
```

The `client.py` layer has no MCP dependency: it can be tested in isolation.

## Development

Run the tests:

```bash
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
```

## Roadmap

- `get_structure_output` — output of a given laboratory.
- Pivot facets (cross type × full-text, year × type).
- Range facets (`facet.range`) for time-series/evolution charts.
- Collection / portal filtering exposed as a parameter.
- HTTP transport for Claude.ai (connector) and ChatGPT (developer mode).

## License

MIT — see the [LICENSE](LICENSE) file.

## Disclaimer

Independent project, not affiliated with the CCSD (which operates HAL).
Metadata comes from HAL's public API. Please respect HAL's terms of use and the
license of each individual publication.