# HAL MCP Publisher

MCP local (stdio) pour rechercher dans HAL, préparer un dépôt, le tester puis l'envoyer via SWORD. Dérivé de [Arpany-Tech/hal-mcp](https://github.com/Arpany-Tech/hal-mcp), sous licence MIT conservée dans `LICENSE`.

## Installation

Python 3.10 ou plus récent :

```powershell
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e .
.\.venv\Scripts\python.exe -m unittest discover -s tests -v
.\.venv\Scripts\python.exe tests/smoke_mcp.py
```

`requirements-lock.txt` enregistre les versions qualifiées ici (Windows/Python 3.12).

## Compte HAL

Dans un terminal **interactif**, depuis ce dossier :

```powershell
.\.venv\Scripts\python.exe -m hal_mcp.credentials --environment production
```

Le login et le mot de passe sont saisis localement ; le mot de passe est masqué et enregistré par `keyring` dans le coffre du système (Gestionnaire d'identifiants sous Windows). Aucun secret ne passe par un outil MCP. Pour le bac à sable, utiliser `--environment preprod` avec les identifiants de cet environnement.

Le script teste maintenant l'accès SWORD **avant** d'enregistrer les identifiants : résultat explicite HTTP 200/401 ou erreur réseau, sans dépôt. En cas d'échec, les anciens identifiants sont conservés. Pendant la saisie du mot de passe, aucun caractère ni astérisque ne s'affiche ; valider avec Entrée. Pour retester les identifiants configurés sans les modifier, ajouter `--check` à la commande.

En alternative, le processus accepte `HAL_USERNAME` / `HAL_PASSWORD` et, séparément, `HAL_PREPROD_USERNAME` / `HAL_PREPROD_PASSWORD`. Ne pas les inscrire dans Git. Le serveur ne fournit aucun outil pour lire les secrets.

## Connexion au client MCP

Utiliser le chemin **absolu** de `.venv/Scripts/python.exe`, les arguments `-m hal_mcp.server` et le transport stdio. `codex-config.toml` et `mcp-config.json` sont des exemples : remplacer `C:\path\to\hal-mcp-publisher` par le chemin du clone. Pour Codex, `python -m pip install tomlkit` puis `python install_codex.py` adapte les chemins automatiquement et sauvegarde la configuration existante.

La configuration démarre avec `HAL_ALLOW_PRODUCTION=0`. Pour autoriser les envois réels, passer cette variable à `1`, puis redémarrer le serveur MCP/client. Cela ne déclenche aucun dépôt : `submit_deposit` exige toujours un brouillon testé, son empreinte et une instruction d'envoi explicite. La préparation et le test d'un brouillon de production restent disponibles avec la valeur `0`.

`HAL_MCP_STATE_DIR` définit le dossier local des brouillons et journaux. À défaut : `%LOCALAPPDATA%/hal-mcp` sous Windows ou `~/hal-mcp`. Les configurations fournies utilisent `.hal-mcp` dans ce projet, exclu de Git ; choisir un dossier hors des services de synchronisation si les documents sont confidentiels. Les brouillons contiennent les métadonnées et une copie du PDF, jamais le mot de passe du compte.

## Outils et parcours

1. `get_doi_metadata` : proposition Crossref depuis un DOI ; l'agent peut aussi reprendre les informations d'un BibTeX ou PDF fourni, sans parseur dédié dans ce serveur.
2. `search_references` / `search_structures` : retrouver les auteurs, domaines, revues et identifiants de structures AuréHAL. Vérifier les affiliations à la date de publication.
3. `check_duplicates` : chercher le DOI ou le titre exact dans HAL. Recherche indicative : l'index peut avoir un délai et des variantes de titre.
4. `prepare_deposit` : métadonnées structurées `publication`, chemin absolu `pdf_path` facultatif, environnement `preprod` (défaut) ou `production`. Retourne l'empreinte et les chemins du brouillon. Aucun appel réseau.
5. `inspect_deposit` : présenter les auteurs, affiliations, fichier/version, licence et embargo. `meta.xml` permet la lecture du XML effectivement préparé.
6. `validate_deposit` : authentification et envoi du paquet à l'environnement choisi avec **`X-test: 1`**, sans création. Le PDF quitte donc la machine pendant ce test.
7. `submit_deposit` : après instruction explicite d'envoi, donner `draft_id`, `expected_sha256` et `confirm=true`. Un test réussi est requis. Le serveur conserve les protections HAL contre les doublons de titre.
8. `get_deposit_status` : distingue dépôt soumis, validation (`verify`), corrections (`update`), refus (`delete`) et mise en ligne (`accept`). Choisir le même environnement que le dépôt.

Les six outils de recherche Arpany sont conservés : recherche, fiche, exports, statistiques, production d'auteur, structures. `search_publications` expose aussi `start` et `portal` ; la casse des collections est préservée. Les résultats sont paginés, pas automatiquement exhaustifs.

### Métadonnées et fichiers

`examples/article.json` est un **exemple fictif à remplacer intégralement**, en particulier `structure_ids`. Le schéma MCP décrit les champs obligatoires. Types de dépôt pris en charge : **ART (article)** et **COMM (communication)**. Pour COMM, remplacer `journal` par :

```json
{"conference": {"title": "Nom du congrès", "start": "2026-09-25", "end": "2026-09-27", "city": "Lyon", "country": "FR", "proceedings": true, "invited": false}}
```

Les indicateurs `peer_reviewed`, `popular`, `audience`, `proceedings`, `invited` doivent être renseignés explicitement. Le PDF est limité à 50 Mio, avec contrôle de signature `%PDF-` (ce n'est pas une validation du contenu scientifique ni un antivirus). Pour un PDF, `license_url` est obligatoire ; ne choisir une licence qu'après vérification des droits. `file_version` vaut `author` par défaut ou `publisher`. `embargo_until` est une date ISO facultative. Le générateur échappe le XML et contrôle les champs structurés ; la validation métier définitive appartient à HAL via SWORD.

### Modification d'un dépôt

- `operation="create"` : nouveau dépôt (sans `target`).
- `operation="new_version", target="hal-12345678"` : nouvelle version, PDF requis, requête PUT.
- `operation="metadata_update", target="hal-12345678v1"` : remplacement des **métadonnées complètes**, sans PDF. Ce n'est pas une modification partielle ; repartir de la fiche actuelle et préserver toutes les informations utiles. Les champs non représentables par le modèle ART/COMM empêchent une reprise fidèle : utiliser l'interface HAL dans ce cas.

Aucune suppression, création automatique de structure, export arXiv/PMC ou dépôt en masse. Pas de scraping des pages HAL, pas de serveur HTTP exposé.

### Échec ou délai réseau

L'empreinte couvre le paquet exact, les métadonnées, l'environnement, l'opération et la cible. Le serveur prend une réservation exclusive sur disque avant l'envoi. Il ne rejoue pas une tentative déjà enregistrée, même après redémarrage. Après une erreur ambiguë, consulter le journal via `inspect_deposit` puis HAL ; ne pas recréer un brouillon légèrement différent pour contourner cette protection.

Après vérification humaine que HAL n'a rien reçu, un administrateur peut archiver le fichier `submission.json` du brouillon pour autoriser une nouvelle tentative. Aucun outil MCP ne fait cette réinitialisation. Une suppression manuelle du dossier d'état efface cette protection.

Les requêtes authentifiées vont exclusivement aux hôtes officiels prédéfinis, sans redirection ni proxy hérité. Pas de retry automatique. Les réponses exposent des champs sélectionnés ; les attributs et éléments de mot de passe HAL sont exclus.

## Provenance et projets examinés

- [Arpany-Tech/hal-mcp](https://github.com/Arpany-Tech/hal-mcp), commit `7b0adbb04f6c6bd4a9b668cd87a57ee7d822401f` : reprise de `client.py`, `fields.py`, `server.py`, avec adaptations locales ; licence MIT conservée. Les extensions de dépôt SWORD sont développées dans ce dépôt ; la licence originale est conservée.
- [CCSDForge/HAL/Sword](https://github.com/CCSDForge/HAL/tree/master/Sword) et [documentation SWORD](https://api.archives-ouvertes.fr/docs/sword) : références du XML et du transport ; exemples consultés, non incorporés à la bibliothèque.
- [monperrus/halccli.py](https://github.com/monperrus/halccli.py) : client de modification HAL en Python/CLI ; pas de code repris, la couche SWORD requise ici reste courte.
- [orcid-mcp](https://zenodo.org/records/20024303) : intéressant pour la désambiguïsation ; pas nécessaire pour le dépôt et non ajouté comme dépendance.
- Le paquet npm `hal-mcp` / DeanWard HAL est un autre projet (HTTP API Layer), sans rapport avec l'archive HAL.

## Validation

Les tests hors ligne couvrent XML/ZIP, validation des entrées, instantanés, empreintes, POST/PUT, mode test, production désactivée, filtrage des secrets, concurrence et non-répétition des envois. `tests/smoke_mcp.py` lance réellement le serveur et effectue le handshake stdio, la découverte des outils et la préparation d'un brouillon.

Un dépôt COMM avec PDF a été testé puis soumis avec succès en production le 25 septembre 2026 (HTTP 201, statut de modération `verify`). Les modifications de métadonnées et nouvelles versions ne sont pas encore qualifiées sur un dépôt réel. Aucun dépôt réel n'est effectué par les tests.

Qualification exécutée le 25 septembre 2026 : **14 tests hors ligne réussis**, dialogue MCP stdio réel avec **14 outils**, quatre variantes ART/COMM validées contre le XSD officiel (avec/sans PDF), appels publics HAL et Crossref réussis. Dépendances vérifiées par `pip check`.

Pour reproduire les vérifications externes en lecture seule :

```powershell
.\.venv\Scripts\python.exe -m pip install -e ".[validation]"
.\.venv\Scripts\python.exe tests/validate_schema.py
.\.venv\Scripts\python.exe tests/smoke_network.py
```

`validate_schema.py` conserve les schémas dans `.schema-cache` ; retirer ce cache pour contrôler une nouvelle version du schéma. Le serveur ne télécharge pas de schéma à chaque dépôt.

## Sécurité

Ne jamais committer des identifiants, la configuration personnelle du client MCP ou le dossier d’état. Le coffre système reste local ; aucune clé n’est distribuée avec ce projet. Un programme exécuté sous votre compte peut accéder à vos fichiers et, selon le système, à votre coffre : utiliser uniquement un client MCP et des dépendances de confiance. Les contrôles de confirmation ne constituent pas une isolation contre un client malveillant. Ne pas activer les journaux HTTP détaillés sur des sessions authentifiées.