heurix-mcp-server 0.1.0__tar.gz

heurix_mcp_server-0.1.0/.gitignore

@@ -0,0 +1 @@
+REFERENCEMENT-ANNUAIRES.md

heurix_mcp_server-0.1.0/PKG-INFO

@@ -0,0 +1,129 @@
+Metadata-Version: 2.4
+Name: heurix-mcp-server
+Version: 0.1.0
+Summary: Serveur MCP pour Heurix — recherche et classement de catalogues produits techniques en langage naturel
+Project-URL: Homepage, https://heurix.fr
+Project-URL: Documentation, https://heurix.fr/docs.html#ep-mcp
+Project-URL: Repository, https://github.com/flahaut-alexis/heurix-mcp-server
+Author-email: Alexis Flahaut <contact@heurix.fr>
+License: MIT
+Keywords: catalog,ecommerce,mcp,model-context-protocol,product-search,search
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp>=1.2.0
+Description-Content-Type: text/markdown
+
+# Serveur MCP Heurix
+
+Permet à un agent IA (Claude Desktop, Cursor, ou tout autre client MCP)
+d'interroger directement un catalogue Heurix — recherche, parcours par
+catégorie, statistiques — sans que l'agent ait à connaître l'API REST.
+Chantier 6.1 de la roadmap, 24 juillet 2026.
+
+Trois tools exposés :
+- **`heurix_search`** — recherche par mot-clé, tolérante aux fautes de frappe
+- **`heurix_browse`** — liste les produits d'une catégorie, avec tri (stock, prix, popularité...)
+- **`heurix_catalog_stats`** — liste les catalogues et leurs catégories disponibles
+
+Une fine couche au-dessus de l'API REST Heurix existante — aucune nouvelle
+logique métier, juste une nouvelle façade que les agents IA savent parler
+nativement.
+
+## Installation
+
+```bash
+pip install -r requirements.txt
+```
+
+Testable en local avant de le brancher à un client :
+```bash
+HEURIX_API_KEY=hx_votre_cle python3 server.py
+```
+(Le serveur attend alors une connexion MCP sur stdin/stdout — `Ctrl+C` pour arrêter. C'est normal qu'il ne "fasse rien" visuellement : un client MCP doit s'y connecter pour que quoi que ce soit se passe.)
+
+## Configuration dans Claude Desktop
+
+1. Ouvrez Claude Desktop → **Réglages → Développeur → Modifier la configuration** (ça crée le fichier s'il n'existe pas encore)
+2. Le fichier se trouve à :
+   - macOS : `~/Library/Application Support/Claude/claude_desktop_config.json`
+   - Windows : `%APPDATA%\Claude\claude_desktop_config.json`
+3. Ajoutez (ou complétez s'il existe déjà d'autres serveurs) :
+
+```json
+{
+  "mcpServers": {
+    "heurix": {
+      "command": "/usr/bin/python3",
+      "args": ["/chemin/complet/vers/heurix-mcp-server/server.py"],
+      "env": {
+        "HEURIX_API_KEY": "hx_votre_cle_api",
+        "HEURIX_API_BASE": "https://api.heurix.fr"
+      }
+    }
+  }
+}
+```
+
+**Important** : utilisez le **chemin complet** vers `python3` (`which python3` dans un terminal pour le trouver), pas juste `python3` — Claude Desktop lance la configuration avec un PATH minimal, une commande courte qui fonctionne dans votre terminal peut échouer silencieusement ici. Même chose pour le chemin vers `server.py` : complet, pas relatif.
+
+4. Redémarrez Claude Desktop entièrement (pas juste fermer la fenêtre)
+5. Un nouvel outil (icône 🔌 ou menu MCP selon la version) doit lister `heurix_search`, `heurix_browse`, `heurix_catalog_stats`
+
+## Configuration dans Cursor
+
+Même structure de fichier, deux emplacements possibles :
+- `.cursor/mcp.json` à la racine d'un projet (pour un serveur propre à ce projet)
+- `~/.cursor/mcp.json` (global, disponible dans tous les projets)
+
+```json
+{
+  "mcpServers": {
+    "heurix": {
+      "command": "/usr/bin/python3",
+      "args": ["/chemin/complet/vers/heurix-mcp-server/server.py"],
+      "env": {
+        "HEURIX_API_KEY": "hx_votre_cle_api",
+        "HEURIX_API_BASE": "https://api.heurix.fr"
+      }
+    }
+  }
+}
+```
+
+Ensuite : **Réglages Cursor → Tools & MCP**, vérifiez que "Enable MCP Servers" est coché, et que `heurix` apparaît avec un point vert (connecté). Si rien n'apparaît après un redémarrage, le panneau **Output → MCP** affiche les logs bruts du serveur — souvent plus parlant que l'interface elle-même pour diagnostiquer.
+
+## Exemple concret
+
+**Ce qu'un utilisateur tape dans Claude Desktop**, sans rien connaître de l'API Heurix :
+
+> J'ai un catalogue Heurix qui s'appelle quincaillerie-demo. Est-ce que j'ai des vis M8 en stock, et à quel prix ?
+
+**Ce qui se passe côté agent** (invisible pour l'utilisateur, montré ici pour comprendre) :
+1. Claude appelle `heurix_search(catalog="quincaillerie-demo", query="vis M8")`
+2. Le serveur MCP relaie vers `POST https://api.heurix.fr/v1/index/quincaillerie-demo/search`
+3. La réponse JSON (hits, scores, stock, prix) revient à Claude
+
+**Réponse type de Claude Desktop à l'utilisateur** :
+
+> Oui, vous avez deux références de vis M8 en stock dans quincaillerie-demo :
+>
+> - **Vis M8 x 20 - Inox A2** — 120 en stock, 5,90 €
+> - **Vis M8 x 30 - Inox A2** — 45 en stock, 7,90 €
+>
+> Voulez-vous que je regarde aussi si l'une d'elles a un stock faible, ou que je compare avec une autre référence ?
+
+Aucune ligne de code, aucun appel curl — l'utilisateur pose une question en
+langage naturel, l'agent fait le pont vers l'API.
+
+## Sécurité
+
+`HEURIX_API_KEY` vit uniquement dans la configuration du client MCP (fichier
+local sur la machine de l'utilisateur), jamais en argument de ligne de
+commande, jamais transmise en clair dans un appel de tool — le serveur la
+lit une fois au démarrage depuis l'environnement et l'utilise pour chaque
+appel à l'API Heurix.

heurix_mcp_server-0.1.0/README.md

@@ -0,0 +1,109 @@
+# Serveur MCP Heurix
+
+Permet à un agent IA (Claude Desktop, Cursor, ou tout autre client MCP)
+d'interroger directement un catalogue Heurix — recherche, parcours par
+catégorie, statistiques — sans que l'agent ait à connaître l'API REST.
+Chantier 6.1 de la roadmap, 24 juillet 2026.
+
+Trois tools exposés :
+- **`heurix_search`** — recherche par mot-clé, tolérante aux fautes de frappe
+- **`heurix_browse`** — liste les produits d'une catégorie, avec tri (stock, prix, popularité...)
+- **`heurix_catalog_stats`** — liste les catalogues et leurs catégories disponibles
+
+Une fine couche au-dessus de l'API REST Heurix existante — aucune nouvelle
+logique métier, juste une nouvelle façade que les agents IA savent parler
+nativement.
+
+## Installation
+
+```bash
+pip install -r requirements.txt
+```
+
+Testable en local avant de le brancher à un client :
+```bash
+HEURIX_API_KEY=hx_votre_cle python3 server.py
+```
+(Le serveur attend alors une connexion MCP sur stdin/stdout — `Ctrl+C` pour arrêter. C'est normal qu'il ne "fasse rien" visuellement : un client MCP doit s'y connecter pour que quoi que ce soit se passe.)
+
+## Configuration dans Claude Desktop
+
+1. Ouvrez Claude Desktop → **Réglages → Développeur → Modifier la configuration** (ça crée le fichier s'il n'existe pas encore)
+2. Le fichier se trouve à :
+   - macOS : `~/Library/Application Support/Claude/claude_desktop_config.json`
+   - Windows : `%APPDATA%\Claude\claude_desktop_config.json`
+3. Ajoutez (ou complétez s'il existe déjà d'autres serveurs) :
+
+```json
+{
+  "mcpServers": {
+    "heurix": {
+      "command": "/usr/bin/python3",
+      "args": ["/chemin/complet/vers/heurix-mcp-server/server.py"],
+      "env": {
+        "HEURIX_API_KEY": "hx_votre_cle_api",
+        "HEURIX_API_BASE": "https://api.heurix.fr"
+      }
+    }
+  }
+}
+```
+
+**Important** : utilisez le **chemin complet** vers `python3` (`which python3` dans un terminal pour le trouver), pas juste `python3` — Claude Desktop lance la configuration avec un PATH minimal, une commande courte qui fonctionne dans votre terminal peut échouer silencieusement ici. Même chose pour le chemin vers `server.py` : complet, pas relatif.
+
+4. Redémarrez Claude Desktop entièrement (pas juste fermer la fenêtre)
+5. Un nouvel outil (icône 🔌 ou menu MCP selon la version) doit lister `heurix_search`, `heurix_browse`, `heurix_catalog_stats`
+
+## Configuration dans Cursor
+
+Même structure de fichier, deux emplacements possibles :
+- `.cursor/mcp.json` à la racine d'un projet (pour un serveur propre à ce projet)
+- `~/.cursor/mcp.json` (global, disponible dans tous les projets)
+
+```json
+{
+  "mcpServers": {
+    "heurix": {
+      "command": "/usr/bin/python3",
+      "args": ["/chemin/complet/vers/heurix-mcp-server/server.py"],
+      "env": {
+        "HEURIX_API_KEY": "hx_votre_cle_api",
+        "HEURIX_API_BASE": "https://api.heurix.fr"
+      }
+    }
+  }
+}
+```
+
+Ensuite : **Réglages Cursor → Tools & MCP**, vérifiez que "Enable MCP Servers" est coché, et que `heurix` apparaît avec un point vert (connecté). Si rien n'apparaît après un redémarrage, le panneau **Output → MCP** affiche les logs bruts du serveur — souvent plus parlant que l'interface elle-même pour diagnostiquer.
+
+## Exemple concret
+
+**Ce qu'un utilisateur tape dans Claude Desktop**, sans rien connaître de l'API Heurix :
+
+> J'ai un catalogue Heurix qui s'appelle quincaillerie-demo. Est-ce que j'ai des vis M8 en stock, et à quel prix ?
+
+**Ce qui se passe côté agent** (invisible pour l'utilisateur, montré ici pour comprendre) :
+1. Claude appelle `heurix_search(catalog="quincaillerie-demo", query="vis M8")`
+2. Le serveur MCP relaie vers `POST https://api.heurix.fr/v1/index/quincaillerie-demo/search`
+3. La réponse JSON (hits, scores, stock, prix) revient à Claude
+
+**Réponse type de Claude Desktop à l'utilisateur** :
+
+> Oui, vous avez deux références de vis M8 en stock dans quincaillerie-demo :
+>
+> - **Vis M8 x 20 - Inox A2** — 120 en stock, 5,90 €
+> - **Vis M8 x 30 - Inox A2** — 45 en stock, 7,90 €
+>
+> Voulez-vous que je regarde aussi si l'une d'elles a un stock faible, ou que je compare avec une autre référence ?
+
+Aucune ligne de code, aucun appel curl — l'utilisateur pose une question en
+langage naturel, l'agent fait le pont vers l'API.
+
+## Sécurité
+
+`HEURIX_API_KEY` vit uniquement dans la configuration du client MCP (fichier
+local sur la machine de l'utilisateur), jamais en argument de ligne de
+commande, jamais transmise en clair dans un appel de tool — le serveur la
+lit une fois au démarrage depuis l'environnement et l'utilise pour chaque
+appel à l'API Heurix.

heurix_mcp_server-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+# Paquet installable du serveur MCP Heurix.
+#
+# POURQUOI CE FICHIER : les annuaires MCP (mcp.so, Smithery, Glama) verifient
+# un serveur en INTROSPECTANT un processus qu'ils lancent. Un zip telecharge
+# depuis un site ne leur suffit pas -- il leur faut une commande executable.
+# Publie sur PyPI, le serveur devient lancable par `uvx heurix-mcp-server`,
+# ce que tout crawler d'annuaire sait faire.
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "heurix-mcp-server"
+version = "0.1.0"
+description = "Serveur MCP pour Heurix — recherche et classement de catalogues produits techniques en langage naturel"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Alexis Flahaut", email = "contact@heurix.fr" }]
+keywords = ["mcp", "model-context-protocol", "search", "ecommerce", "catalog", "product-search"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3.10",
+  "Topic :: Internet :: WWW/HTTP :: Indexing/Search",
+]
+dependencies = ["mcp>=1.2.0", "httpx>=0.27"]
+
+[project.urls]
+Homepage = "https://heurix.fr"
+Documentation = "https://heurix.fr/docs.html#ep-mcp"
+Repository = "https://github.com/flahaut-alexis/heurix-mcp-server"
+
+[project.scripts]
+heurix-mcp-server = "server:main"
+
+[tool.hatch.build.targets.wheel]
+include = ["server.py"]

heurix_mcp_server-0.1.0/requirements.txt

@@ -0,0 +1,2 @@
+mcp[cli]>=1.28.0
+httpx>=0.27.0

heurix_mcp_server-0.1.0/server.py

@@ -0,0 +1,172 @@
+"""
+Serveur MCP pour Heurix — chantier 6.1 de la roadmap (24 juillet 2026).
+
+Enveloppe l'API REST Heurix existante en "tools" qu'un agent IA (Claude
+Desktop, Cursor, un agent interne via le SDK MCP) peut découvrir et
+appeler directement. Pas de nouvelle logique métier ici : une nouvelle
+façade sur ce qui existe déjà (recherche, browse, stats catalogue).
+
+Configuration — deux variables d'environnement, jamais codées en dur ni
+passées en clair dans un appel de tool :
+  HEURIX_API_KEY   votre clé API Heurix (hx_...)
+  HEURIX_API_BASE  URL de base de l'API (défaut : https://api.heurix.fr)
+
+Lancement local (test manuel) :
+  HEURIX_API_KEY=hx_... python3 server.py
+
+Voir README.md pour la configuration dans Claude Desktop et Cursor.
+"""
+from __future__ import annotations
+
+import os
+import sys
+
+import httpx
+from mcp.server.fastmcp import FastMCP
+
+HEURIX_API_KEY = os.environ.get("HEURIX_API_KEY", "").strip()
+HEURIX_API_BASE = os.environ.get("HEURIX_API_BASE", "https://api.heurix.fr").rstrip("/")
+
+if not HEURIX_API_KEY:
+    print(
+        "HEURIX_API_KEY manquante — définissez-la dans la configuration MCP de "
+        "votre client (Claude Desktop, Cursor...), jamais en argument de ligne "
+        "de commande ni codée en dur dans ce fichier.",
+        file=sys.stderr,
+    )
+    sys.exit(1)
+
+mcp = FastMCP(
+    "heurix",
+    instructions=(
+        "Outils pour interroger un catalogue produit indexé sur Heurix — un "
+        "moteur de recherche et de classement pour catalogues techniques "
+        "(regex sur références produit, facettes, tri par catégorie). "
+        "Commencez par heurix_catalog_stats si vous ne connaissez pas encore "
+        "les catalogues, catégories ou attributs disponibles sur ce compte : "
+        "les noms de catalogue et de catégorie sont sensibles à la casse et "
+        "doivent être exacts, pas devinés."
+    ),
+)
+
+
+def _auth_headers() -> dict:
+    return {"Authorization": f"Bearer {HEURIX_API_KEY}"}
+
+
+def _handle_response(r: httpx.Response) -> dict:
+    """Ne masque jamais une erreur API derrière un plantage générique — un
+    agent doit pouvoir comprendre, et au besoin expliquer à l'utilisateur,
+    ce qui s'est mal passé (catalogue introuvable, quota dépassé, accès
+    Browse non inclus dans le plan...) plutôt que recevoir une exception
+    opaque."""
+    if r.status_code >= 400:
+        try:
+            detail = r.json().get("detail", r.text)
+        except Exception:  # noqa: BLE001 — reponse non-JSON, on renvoie le texte brut
+            detail = r.text
+        return {"error": True, "status_code": r.status_code, "detail": detail}
+    return r.json()
+
+
+async def _get(path: str, params: dict | None = None) -> dict:
+    async with httpx.AsyncClient(timeout=15.0) as client:
+        r = await client.get(f"{HEURIX_API_BASE}{path}", headers=_auth_headers(), params=params or {})
+    return _handle_response(r)
+
+
+async def _post(path: str, json_body: dict) -> dict:
+    async with httpx.AsyncClient(timeout=15.0) as client:
+        r = await client.post(f"{HEURIX_API_BASE}{path}", headers=_auth_headers(), json=json_body)
+    return _handle_response(r)
+
+
+@mcp.tool()
+async def heurix_search(catalog: str, query: str, filters: list[str] | None = None, limit: int = 10) -> dict:
+    """Recherche des produits dans un catalogue Heurix par mot-clé, avec
+    tolérance aux fautes de frappe et reconnaissance des références
+    techniques (diamètres, longueurs, matières, ISBN...). Utilisez
+    heurix_catalog_stats d'abord si le nom exact du catalogue n'est pas
+    déjà connu.
+
+    La réponse peut inclure `suggested_category` si un mot de la requête
+    recoupe une catégorie Browse connue — utile pour proposer "cherchiez-
+    vous plutôt dans telle catégorie ?", ne change jamais les résultats
+    eux-mêmes.
+
+    Args:
+        catalog: Nom exact du catalogue à interroger.
+        query: Texte de recherche, tel qu'un utilisateur le taperait —
+            les fautes de frappe et formats différents sont tolérés par
+            le moteur, pas la peine de les corriger avant d'appeler.
+        filters: Liste optionnelle de filtres exacts sur des annotations
+            connues (ex. ["DIAM_M8"]). Laisser vide si incertain plutôt
+            que de deviner une valeur.
+        limit: Nombre maximal de résultats, entre 1 et 100 (défaut 10).
+    """
+    return await _post(
+        f"/v1/index/{catalog}/search",
+        {"q": query, "filters": filters or [], "limit": max(1, min(limit, 100))},
+    )
+
+
+@mcp.tool()
+async def heurix_browse(catalog: str, category: str, sort: str = "stock", limit: int = 20) -> dict:
+    """Liste les produits d'une catégorie sans recherche textuelle — pour
+    une demande du type "montre-moi tous les produits de telle
+    catégorie", pas une recherche par mot-clé (utilisez heurix_search
+    pour ça). Utilisez heurix_catalog_stats pour découvrir les
+    catégories réellement disponibles si elles ne sont pas déjà connues
+    — inventer un nom de catégorie renverra une liste vide, pas une erreur.
+
+    Args:
+        catalog: Nom exact du catalogue.
+        category: Valeur de catégorie exacte, sensible à la casse.
+        sort: Stratégie de tri — "stock" (défaut, en stock d'abord),
+            "recent", "alphabetical", "price_asc", "price_desc",
+            "margin", ou "popular" (popularité réelle, clics et achats).
+        limit: Nombre maximal de résultats, entre 1 et 100 (défaut 20).
+    """
+    return await _get(
+        f"/v1/browse/{catalog}/{category}",
+        {"sort": sort, "limit": max(1, min(limit, 100))},
+    )
+
+
+@mcp.tool()
+async def heurix_catalog_stats(catalog: str | None = None) -> dict:
+    """Liste tous les catalogues accessibles avec cette clé API et leurs
+    statistiques de base (nombre de produits, pack de règles actif). Si
+    `catalog` est précisé, renvoie en plus les catégories Browse
+    disponibles pour ce catalogue. À appeler en premier pour découvrir
+    ce qui existe, avant une recherche ou un parcours par catégorie.
+
+    Args:
+        catalog: Nom d'un catalogue précis (optionnel). Sans ce
+            paramètre, liste tous les catalogues du compte.
+    """
+    if catalog:
+        stats = await _get(f"/v1/index/{catalog}/stats")
+        if stats.get("error"):
+            return stats
+        categories = await _get(f"/v1/index/{catalog}/browse-categories")
+        # Browse peut ne pas être inclus dans le plan de cette clé — pas une
+        # raison de faire échouer tout l'appel, juste une liste vide.
+        stats["browse_categories"] = categories.get("categories", []) if not categories.get("error") else []
+        return stats
+    return await _get("/v1/index/catalogs")
+
+
+def main() -> None:
+    """Point d'entree de la commande `heurix-mcp-server`.
+
+    Declaree dans pyproject.toml sous [project.scripts] : sans cette
+    fonction, la commande installee depuis PyPI echouerait a l'import.
+    C'est aussi elle que les annuaires MCP lancent pour introspecter le
+    serveur et verifier les outils qu'il expose.
+    """
+    mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    mcp.run(transport="stdio")