douanecode-mcp 0.1.0__tar.gz

douanecode_mcp-0.1.0/Dockerfile

@@ -0,0 +1,13 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+COPY pyproject.toml README.md ./
+COPY src ./src
+RUN pip install --no-cache-dir .
+
+ENV MCP_TRANSPORT=streamable-http \
+    FASTMCP_HOST=0.0.0.0 \
+    FASTMCP_PORT=8000
+
+EXPOSE 8000
+CMD ["douanecode-mcp"]

douanecode_mcp-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,56 @@
+# 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/deploy/k8s.yaml

@@ -0,0 +1,68 @@
+# douanecode-mcp — serveur MCP hébergé (streamable-http) sur mcp.douanecode.fr
+# NB : en mode hébergé, la clé API vient du CLIENT (header X-API-Key transmis
+# par l'agent via la config MCP) — à terme, adapter le serveur pour lire la clé
+# depuis les headers de la requête MCP plutôt que l'env. Le déploiement stdio
+# local (Claude Desktop/Code, Cursor) fonctionne dès aujourd'hui sans ceci.
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: douanecode-mcp
+  namespace: douanecode-dev
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: douanecode-mcp
+  template:
+    metadata:
+      labels:
+        app: douanecode-mcp
+    spec:
+      containers:
+        - name: douanecode-mcp
+          image: harbor.homalab.com/douanecode/mcp:latest
+          ports:
+            - containerPort: 8000
+          env:
+            - name: MCP_TRANSPORT
+              value: streamable-http
+            - name: DOUANECODE_API_URL
+              value: http://website-backend.douanecode-dev.svc.cluster.local:8000
+          resources:
+            requests: { cpu: 50m, memory: 96Mi }
+            limits: { cpu: 250m, memory: 256Mi }
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: douanecode-mcp
+  namespace: douanecode-dev
+spec:
+  selector:
+    app: douanecode-mcp
+  ports:
+    - port: 80
+      targetPort: 8000
+---
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  name: douanecode-mcp
+  namespace: douanecode-dev
+  annotations:
+    cert-manager.io/cluster-issuer: letsencrypt-prod
+spec:
+  ingressClassName: nginx
+  tls:
+    - hosts: [mcp.douanecode.fr]
+      secretName: douanecode-mcp-tls
+  rules:
+    - host: mcp.douanecode.fr
+      http:
+        paths:
+          - path: /
+            pathType: Prefix
+            backend:
+              service:
+                name: douanecode-mcp
+                port: { number: 80 }

douanecode_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[project]
+name = "douanecode-mcp"
+version = "0.1.0"
+description = "MCP server exposing DouaneCode customs code search (HS/NC8/TARIC) to AI agents"
+readme = "README.md"
+license = "MIT"
+keywords = ["mcp", "customs", "taric", "hs-code", "douane", "ai-agents"]
+requires-python = ">=3.11"
+dependencies = [
+    "mcp>=1.2.0",
+    "httpx>=0.27",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "respx>=0.21",
+]
+
+[project.scripts]
+douanecode-mcp = "douanecode_mcp.server:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/douanecode_mcp"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

douanecode_mcp-0.1.0/src/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/tests/test_server.py

@@ -0,0 +1,79 @@
+import json
+
+import pytest
+import respx
+from httpx import Response
+
+from douanecode_mcp import server
+from douanecode_mcp.server import DouaneCodeError, mcp
+
+API = "https://douanecode.fr/api"
+
+
+@pytest.fixture(autouse=True)
+def api_key(monkeypatch):
+    monkeypatch.setenv(server.API_KEY_ENV, "dc_test_key")
+
+
+async def _call(tool_name: str, args: dict):
+    result = await mcp.call_tool(tool_name, args)
+    # FastMCP returns (content_blocks, raw_result) or content blocks only
+    blocks = result[0] if isinstance(result, tuple) else result
+    return json.loads(blocks[0].text)
+
+
+def test_all_tools_registered():
+    tools = {t.name for t in mcp._tool_manager.list_tools()}
+    assert tools == {
+        "search_customs_code",
+        "get_code_details",
+        "get_duty_rates",
+        "get_tariff_changes",
+    }
+
+
+@respx.mock
+async def test_search_sends_api_key_and_params():
+    route = respx.get(f"{API}/search").mock(
+        return_value=Response(200, json={"results": [{"code": "85176200"}]})
+    )
+    payload = await _call(
+        "search_customs_code", {"query": "carte électronique", "limit": 5}
+    )
+    assert payload["results"][0]["code"] == "85176200"
+    request = route.calls.last.request
+    assert request.headers["X-API-Key"] == "dc_test_key"
+    assert request.url.params["q"] == "carte électronique"
+    assert request.url.params["limit"] == "5"
+    # chapter=None ne doit pas être envoyé
+    assert "chapter" not in request.url.params
+
+
+@respx.mock
+async def test_duty_rates_with_origin():
+    route = respx.get(f"{API}/duty/85176200").mock(
+        return_value=Response(200, json={"duty": "3.7%"})
+    )
+    payload = await _call("get_duty_rates", {"code": " 85176200 ", "origin": "CN"})
+    assert payload["duty"] == "3.7%"
+    assert route.calls.last.request.url.params["origin"] == "CN"
+
+
+@respx.mock
+async def test_rate_limit_maps_to_upsell_error():
+    respx.get(f"{API}/search").mock(return_value=Response(429, json={}))
+    with pytest.raises(DouaneCodeError, match="tarifs"):
+        await server.search_customs_code(query="test")
+
+
+@respx.mock
+async def test_invalid_key_maps_to_auth_error():
+    respx.get(f"{API}/code/8517").mock(return_value=Response(401, json={}))
+    with pytest.raises(DouaneCodeError, match="Pro requis"):
+        await server.get_code_details(code="8517")
+
+
+async def test_missing_api_key_raises(monkeypatch):
+    monkeypatch.delenv(server.API_KEY_ENV, raising=False)
+    with pytest.raises(DouaneCodeError, match="DOUANECODE_API_KEY"):
+        await server.get_tariff_changes()