ner-mcp-fr

Reconnaissance d'entités nommées (NER) en français, exposée comme serveur MCP — avec un CLI pour vérifier ce que le modèle fait réellement. Inférence ONNX, sans torch.

Quatre labels : PER (personne), LOC (lieu), ORG (organisation), MISC (divers).

Le modèle est CATIE-AQ/NERmembert-base-4entities (CamemBERT-base, 110 M de paramètres, fine-tuné sur frenchNER_4entities, licence MIT), exporté en ONNX fp16 et hébergé séparément des poids PyTorch.

⚠️ Ne pas utiliser NERmemberta-* ni NERmembert2-*. Ces modèles, pourtant marqués new_version par leurs auteurs, publient un tokenizer byte-level sans règles de fusion : chaque mot est découpé en lettres (Ġ S y l v a i n) et les prédictions sont du bruit. Constat vérifié et documenté dans SPECS.md §2.

Installation

Rien à installer globalement : uvx construit un environnement jetable à la volée.

uvx ner-mcp-fr info      # ne charge pas le modèle, sert de test de fumée
uvx ner-mcp-fr extract article.txt --format highlight

Empreinte : ~150 MB installés (onnxruntime, tokenizers, numpy, mcp), contre ~780 MB avec une pile PyTorch. Le premier appel télécharge les poids fp16 (210 MB) depuis Hugging Face, puis les garde en cache. Compromis assumé : ~70 ms par paragraphe sur CPU (contre ~16 ms avec torch + MPS sur Mac), pour un cinquième de la taille.

Tant que le paquet n'est pas publié sur PyPI, la même chose depuis GitHub :

uvx --from git+https://github.com/athoune/ner-mcp-fr ner-mcp-fr info

Pour développer :

git clone https://github.com/athoune/ner-mcp-fr
cd ner-mcp-fr
uv sync
uv run pytest

Le CLI : vérifier une analyse

# un fichier, rendu lisible avec les entités colorées
ner-mcp-fr extract article.txt --format highlight

# depuis STDIN
cat article.txt | ner-mcp-fr extract

# un paragraphe collé directement
pbpaste | ner-mcp-fr extract --format highlight --stats

Exemple de sortie --format text :

LABEL  SCORE   SPAN        TEXT
-----  ------  ----------  -------------------
MISC   0.9456  [36,38)     'JO'
LOC    0.9993  [75,84)     'Grand Rex'
PER    0.9989  [165,178)   'Sylvain Boyer'

Formats disponibles :

Options utiles :

ner-mcp-fr extract article.txt --labels PER,LOC      # filtre les labels
ner-mcp-fr extract article.txt --min-score 0.9       # exige de la confiance
ner-mcp-fr extract article.txt --keep-punctuation    # spans bruts du modèle
ner-mcp-fr extract article.txt --onnx ./model.onnx   # poids locaux, sans téléchargement
ner-mcp-fr extract article.txt --stats               # chunks/timing sur stderr
ner-mcp-fr extract article.txt --fail-on-empty       # code 3 si aucune entité

Codes de sortie : 0 succès, 1 erreur d'exécution, 2 erreur d'usage, 3 --fail-on-empty sans entité.

Serveur MCP

ner-mcp-fr sans argument (ou ner-mcp-fr mcp) démarre le serveur sur stdio. Configuration d'un hôte :

{
  "mcpServers": {
    "ner-fr": {
      "command": "uvx",
      "args": ["ner-mcp-fr"]
    }
  }
}

Quatre outils :

Pourquoi ner_extract_file existe : un texte de 200 kB collé dans ner_extract traverse le contexte du modèle deux fois (lecture + historique). Avec un chemin, il ne traverse jamais rien : le serveur lit le fichier en local. source dans la réponse est le chemin absolu résolu, pour tracer l'origine sans renvoyer le texte. NER_ALLOWED_DIRS restreint les chemins lisibles si le serveur ingère du contenu non fiable.

Réponse de ner_extract :

{
  "model": "CATIE-AQ/NERmembert-base-4entities",
  "precision": "fp16",
  "device": "CPUExecutionProvider",
  "entities": [
    { "text": "Paris", "label": "LOC", "start": 334, "end": 339, "score": 0.9991 }
  ],
  "source": "/Users/moi/article.txt",
  "text_length": 617,
  "chunks": 1,
  "truncated": false,
  "dropped_by_min_score": 0,
  "elapsed_ms": 214
}

Invariant : pour chaque entité, text[start:end] == entity.text. Les offsets sont des index de code points Unicode (sémantique Python). Si un client JavaScript manipule des offsets sur du texte contenant des emoji, préférer le champ text.

Configuration

Limites connues

• Français uniquement. Aucune détection de langue : sur de l'anglais, le modèle produit des entités plausibles mais non fiables.
• Contexte 512 tokens (~350 mots). Au-delà, le texte est découpé en fenêtres avec chevauchement d'une phrase ; chunks l'indique. Rien n'est tronqué silencieusement.
• CPU uniquement, sauf onnxruntime-gpu installé et NER_DEVICE=cuda. Le provider CoreML a été mesuré plus lent que le CPU sur ce graphe (29 nœuds accélérés sur 597).
• fp16 : sortie identique au fp32 sur le corpus de référence, mais la quantization int8, elle, détruit le modèle (F1 0,53 en dynamique, 0,00 en statique). Ne pas la réintroduire sans mesure.
• MISC est le label le plus faiblement performant (F1 ≈ 0,81) : attendez-vous à du bruit.
• La ponctuation et le balisage Markdown de bord sont retirés des entités (Grand Rex. → Grand Rex, Ebenezer** → Ebenezer) ; --keep-punctuation rend les spans bruts.

Développement

uv run pytest        # tests unitaires (aucun modèle téléchargé)
uv run ruff check .

Re-exporter les poids (seule étape qui demande torch) :

uv run --group export python scripts/export_onnx.py
# écrit dist/onnx/model-fp16.onnx et affiche son SHA-256

Architecture : backend.py (session ONNX + tokenizer), artifacts.py (téléchargement, cache, vérification du SHA-256), engine.py (chunking, agrégation — sans MCP), cli.py + render.py (CLI), server.py (quatre outils MCP). Le contrat complet est dans SPECS.md.

Attribution

Modèles fine-tunés par CATIE-AQ sur le jeu frenchNER_4entities, publiés sous licence MIT. Le graphe ONNX est un export de NERmembert-base-4entities, distribué sous la même licence.