douanecode-mcp 0.1.0__py3-none-any.whl

douanecode_mcp/server.py

@@ -0,0 +1,140 @@
+"""DouaneCode MCP server.
+
+Expose la recherche de codes douaniers (HS/NC8/TARIC) de douanecode.fr comme
+outils MCP pour agents IA. Chaque appel est authentifié par la clé API du
+client (plan Pro) via le header X-API-Key ; le backend applique le rate
+limiting et la facturation par plan.
+
+Transports :
+- stdio (défaut) : usage local (Claude Desktop, Claude Code, Cursor...)
+- streamable-http : hébergé (mcp.douanecode.fr), MCP_TRANSPORT=streamable-http
+"""
+
+import os
+import sys
+from typing import Any, Optional
+
+import httpx
+from mcp.server.fastmcp import FastMCP
+
+API_BASE_URL = os.environ.get("DOUANECODE_API_URL", "https://douanecode.fr/api")
+API_KEY_ENV = "DOUANECODE_API_KEY"
+TIMEOUT_SECONDS = 15.0
+
+mcp = FastMCP(
+    "douanecode",
+    instructions=(
+        "Recherche officielle de codes douaniers français/UE (HS, NC8, TARIC) : "
+        "classement tarifaire en langage naturel, taux de droits, mesures TARIC "
+        "et changements tarifaires. Nécessite une clé API DouaneCode Pro "
+        f"(variable d'environnement {API_KEY_ENV}, obtenue sur "
+        "https://douanecode.fr/compte)."
+    ),
+)
+
+
+class DouaneCodeError(Exception):
+    """Erreur API remontée telle quelle à l'agent appelant."""
+
+
+def _api_key() -> str:
+    key = os.environ.get(API_KEY_ENV, "").strip()
+    if not key:
+        raise DouaneCodeError(
+            f"Clé API absente : définissez {API_KEY_ENV}. "
+            "Créez une clé (plan Pro) sur https://douanecode.fr/compte."
+        )
+    return key
+
+
+async def _get(path: str, params: Optional[dict[str, Any]] = None) -> Any:
+    async with httpx.AsyncClient(
+        base_url=API_BASE_URL, timeout=TIMEOUT_SECONDS
+    ) as client:
+        response = await client.get(
+            path,
+            params={k: v for k, v in (params or {}).items() if v is not None},
+            headers={"X-API-Key": _api_key()},
+        )
+    if response.status_code == 429:
+        raise DouaneCodeError(
+            "Limite quotidienne du plan atteinte. "
+            "Passez à un plan supérieur sur https://douanecode.fr/tarifs."
+        )
+    if response.status_code in (401, 403):
+        raise DouaneCodeError(
+            "Clé API invalide ou plan insuffisant (Pro requis) : "
+            "https://douanecode.fr/tarifs."
+        )
+    response.raise_for_status()
+    return response.json()
+
+
+@mcp.tool()
+async def search_customs_code(
+    query: str,
+    limit: int = 10,
+    chapter: Optional[str] = None,
+    leaf_only: bool = True,
+) -> Any:
+    """Trouve les codes douaniers (HS/NC8/TARIC) correspondant à une description
+    de produit en langage naturel.
+
+    Args:
+        query: Description du produit (ex. "carte électronique pour trottinette",
+            "fromage râpé sous vide"). Français ou anglais.
+        limit: Nombre maximum de candidats retournés (1-100).
+        chapter: Filtre optionnel sur un chapitre SH à 2 chiffres (ex. "85").
+        leaf_only: Ne retourner que les codes feuilles déclarables (recommandé).
+    """
+    return await _get(
+        "/search",
+        {"q": query, "limit": limit, "chapter": chapter, "leaf_only": leaf_only},
+    )
+
+
+@mcp.tool()
+async def get_code_details(code: str) -> Any:
+    """Retourne le détail d'un code douanier : libellés, hiérarchie, unités,
+    et informations de classement.
+
+    Args:
+        code: Code SH/NC8/TARIC (4 à 10 chiffres, ex. "8517620000").
+    """
+    return await _get(f"/code/{code.strip()}")
+
+
+@mcp.tool()
+async def get_duty_rates(code: str, origin: Optional[str] = None) -> Any:
+    """Retourne les taux de droits de douane et mesures applicables à un code
+    (droits tiers, préférences, restrictions).
+
+    Args:
+        code: Code NC8/TARIC (8 à 10 chiffres).
+        origin: Code pays d'origine ISO-2 optionnel (ex. "CN", "US") pour les
+            taux préférentiels.
+    """
+    return await _get(f"/duty/{code.strip()}", {"origin": origin})
+
+
+@mcp.tool()
+async def get_tariff_changes(limit: int = 20) -> Any:
+    """Liste les changements tarifaires récents (nomenclature, taux, mesures) —
+    utile pour la veille réglementaire douanière.
+
+    Args:
+        limit: Nombre maximum de changements retournés.
+    """
+    return await _get("/tariff-changes", {"limit": limit})
+
+
+def main() -> None:
+    transport = os.environ.get("MCP_TRANSPORT", "stdio")
+    if transport not in ("stdio", "streamable-http", "sse"):
+        print(f"Transport MCP inconnu : {transport}", file=sys.stderr)
+        sys.exit(1)
+    mcp.run(transport=transport)
+
+
+if __name__ == "__main__":
+    main()

douanecode_mcp-0.1.0.dist-info/METADATA

@@ -0,0 +1,71 @@
+Metadata-Version: 2.4
+Name: douanecode-mcp
+Version: 0.1.0
+Summary: MCP server exposing DouaneCode customs code search (HS/NC8/TARIC) to AI agents
+License-Expression: MIT
+Keywords: ai-agents,customs,douane,hs-code,mcp,taric
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp>=1.2.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# douanecode-mcp
+
+Serveur MCP officiel de [DouaneCode.fr](https://douanecode.fr) : donne aux
+agents IA (Claude, Cursor, agents logistique/ERP/e-commerce) un accès outillé à
+la recherche de codes douaniers HS/NC8/TARIC, aux taux de droits et à la veille
+tarifaire.
+
+**Modèle économique** : chaque appel exige une clé API DouaneCode (plan Pro,
+99 €/an — tier Cabinet à venir). Le serveur est un wrapper mince ; le backend
+existant applique authentification, rate limiting par plan et analytics.
+
+## Outils exposés
+
+| Outil | Description |
+|---|---|
+| `search_customs_code` | Description produit en langage naturel → codes candidats |
+| `get_code_details` | Détail d'un code (libellés, hiérarchie, unités) |
+| `get_duty_rates` | Droits de douane + mesures, option pays d'origine |
+| `get_tariff_changes` | Changements tarifaires récents (veille) |
+
+## Usage local (Claude Desktop / Claude Code / Cursor)
+
+```json
+{
+  "mcpServers": {
+    "douanecode": {
+      "command": "uvx",
+      "args": ["douanecode-mcp"],
+      "env": { "DOUANECODE_API_KEY": "dc_..." }
+    }
+  }
+}
+```
+
+Clé API : https://douanecode.fr/compte (plan Pro requis).
+
+## Dev
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## Déploiement hébergé
+
+`Dockerfile` + `deploy/k8s.yaml` (mcp.douanecode.fr, transport streamable-http).
+Voir la note dans le manifeste : le mode hébergé nécessite de lire la clé API
+depuis les headers client (TODO) ; le mode stdio publié sur PyPI fonctionne
+sans cela.
+
+## Distribution (go-to-market)
+
+1. Publier sur PyPI (`douanecode-mcp`) → utilisable via `uvx` immédiatement.
+2. Lister sur les annuaires MCP (mcp.so, Smithery, PulseMCP, Glama) +
+   registre officiel `registry.modelcontextprotocol.io`.
+3. Page https://douanecode.fr/mcp expliquant l'installation → conversion Pro.

douanecode_mcp-0.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+douanecode_mcp/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+douanecode_mcp/server.py,sha256=s4L_7heUyfqAgwcpOIEKBktE9t2OLNITMdSPY0rM6Bc,4548
+douanecode_mcp-0.1.0.dist-info/METADATA,sha256=0aKwHUJ8Vosel03-c2zVdqlNg0-zUIe-3FY1P8YRgVo,2302
+douanecode_mcp-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+douanecode_mcp-0.1.0.dist-info/entry_points.txt,sha256=9PHHaHdhz8fmmV1C-AIQ6JxuXogbwNaiBxQjlPZwg8k,62
+douanecode_mcp-0.1.0.dist-info/RECORD,,

douanecode_mcp-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

douanecode_mcp-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+douanecode-mcp = douanecode_mcp.server:main