permisapi-mcp 0.1.0__tar.gz

permisapi_mcp-0.1.0/.gitignore

@@ -0,0 +1,65 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+env/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Environment
+.env
+.env.local
+.env.*.backup
+.env.backup-*
+.env.*.local
+
+# Secrets inventory (file listant les valeurs sensibles a copier dans
+# 1Password/Bitwarden avant de changer de machine). Ne doit JAMAIS
+# remonter sur git.
+SECRETS_INVENTORY.md
+
+# Claude Code workspace (launch.json personnel)
+.claude/
+
+# Data (too big, ignored)
+data/raw/*.csv
+data/raw/*.zip
+data/processed/*.parquet
+
+# Database
+*.sqlite
+*.db
+
+# Logs
+*.log
+logs/
+
+# Tests
+.pytest_cache/
+.coverage
+htmlcov/
+
+# OS
+.DS_Store
+Thumbs.db
+desktop.ini
+
+# Node (landing page)
+landing/node_modules/
+landing/.next/
+landing/out/
+
+# Post-piratage rotation (contient les nouvelles cles API en clair)
+secrets_NEW_KEYS.json
+scrape-downloads/

permisapi_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: permisapi-mcp
+Version: 0.1.0
+Summary: MCP server pour PermisAPI : permettez a Claude / ChatGPT / Cursor de consulter les permis de construire France en langage naturel.
+Project-URL: Homepage, https://permisapi.fr/mcp
+Project-URL: Documentation, https://permisapi.fr/mcp
+Project-URL: Setup, https://github.com/Evan-Crx/permisapi/blob/master/docs/MCP_SETUP.md
+Author-email: Evan Caroux <evan@permisapi.fr>
+License: MIT
+Keywords: anthropic,chatgpt,claude,construire,france,mcp,permis,real-estate,sitadel
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: French
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: permisapi-client>=0.6.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=7.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# permisapi-mcp
+
+Serveur **MCP** (Model Context Protocol, Anthropic) pour [PermisAPI](https://permisapi.fr).
+
+Permet à **Claude Desktop**, **Cursor**, **Windsurf** ou tout client MCP-compatible de consulter les **311 000 permis de construire France** en langage naturel.
+
+## Installation
+
+```bash
+pip install permisapi-mcp
+```
+
+Vous avez besoin d'une clé API PermisAPI (gratuite pour commencer) :
+[https://permisapi.fr/#pricing](https://permisapi.fr/#pricing)
+
+## Configuration Claude Desktop
+
+Éditez `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) ou `%APPDATA%\Claude\claude_desktop_config.json` (Windows) :
+
+```json
+{
+  "mcpServers": {
+    "permisapi": {
+      "command": "permisapi-mcp",
+      "env": {
+        "PERMISAPI_KEY": "pk_live_VOTRE_CLE"
+      }
+    }
+  }
+}
+```
+
+Redémarrez Claude Desktop. Vous pouvez maintenant demander :
+
+> *« Liste les permis de logement déposés à Bordeaux ce mois avec un score MDB > 70 »*
+>
+> *« Trouve-moi des opportunités MDB autour de la rue de Passy à Paris »*
+>
+> *« Quel est le zonage PLU du permis PC07404021K1 ? »*
+
+## Configuration Cursor / Windsurf / autres clients
+
+Voir le guide complet : [https://permisapi.fr/mcp](https://permisapi.fr/mcp)
+
+## Tools disponibles (6)
+
+| Tool | Endpoint | Plan requis |
+|---|---|:---:|
+| `search_permits` | GET /v1/permits | Free |
+| `get_permit_details` | GET /v1/permits/{num_pa} | Free |
+| `find_dvf_neighbors` | GET /v1/permits/{num_pa}/dvf | Pro |
+| `get_mdb_score` | GET /v1/permits/{num_pa}/score | Pro |
+| `get_plu_zoning` | GET /v1/permits/{num_pa}/plu | Pro |
+| `get_risks` | GET /v1/permits/{num_pa}/risks | Pro |
+
+## Sécurité
+
+- La clé API reste **côté user** (env var locale, jamais transmise au LLM)
+- Le LLM voit uniquement les arguments des tools (pas la clé)
+- Validation stricte des inputs (regex sur `num_pa`, ranges Pydantic)
+- Pas de side-effects : tous les tools sont **read-only** (GET uniquement)
+
+## Licence
+
+MIT.
+
+## Support
+
+evan@permisapi.fr — réponse 24-72h.

permisapi_mcp-0.1.0/README.md

@@ -0,0 +1,69 @@
+# permisapi-mcp
+
+Serveur **MCP** (Model Context Protocol, Anthropic) pour [PermisAPI](https://permisapi.fr).
+
+Permet à **Claude Desktop**, **Cursor**, **Windsurf** ou tout client MCP-compatible de consulter les **311 000 permis de construire France** en langage naturel.
+
+## Installation
+
+```bash
+pip install permisapi-mcp
+```
+
+Vous avez besoin d'une clé API PermisAPI (gratuite pour commencer) :
+[https://permisapi.fr/#pricing](https://permisapi.fr/#pricing)
+
+## Configuration Claude Desktop
+
+Éditez `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) ou `%APPDATA%\Claude\claude_desktop_config.json` (Windows) :
+
+```json
+{
+  "mcpServers": {
+    "permisapi": {
+      "command": "permisapi-mcp",
+      "env": {
+        "PERMISAPI_KEY": "pk_live_VOTRE_CLE"
+      }
+    }
+  }
+}
+```
+
+Redémarrez Claude Desktop. Vous pouvez maintenant demander :
+
+> *« Liste les permis de logement déposés à Bordeaux ce mois avec un score MDB > 70 »*
+>
+> *« Trouve-moi des opportunités MDB autour de la rue de Passy à Paris »*
+>
+> *« Quel est le zonage PLU du permis PC07404021K1 ? »*
+
+## Configuration Cursor / Windsurf / autres clients
+
+Voir le guide complet : [https://permisapi.fr/mcp](https://permisapi.fr/mcp)
+
+## Tools disponibles (6)
+
+| Tool | Endpoint | Plan requis |
+|---|---|:---:|
+| `search_permits` | GET /v1/permits | Free |
+| `get_permit_details` | GET /v1/permits/{num_pa} | Free |
+| `find_dvf_neighbors` | GET /v1/permits/{num_pa}/dvf | Pro |
+| `get_mdb_score` | GET /v1/permits/{num_pa}/score | Pro |
+| `get_plu_zoning` | GET /v1/permits/{num_pa}/plu | Pro |
+| `get_risks` | GET /v1/permits/{num_pa}/risks | Pro |
+
+## Sécurité
+
+- La clé API reste **côté user** (env var locale, jamais transmise au LLM)
+- Le LLM voit uniquement les arguments des tools (pas la clé)
+- Validation stricte des inputs (regex sur `num_pa`, ranges Pydantic)
+- Pas de side-effects : tous les tools sont **read-only** (GET uniquement)
+
+## Licence
+
+MIT.
+
+## Support
+
+evan@permisapi.fr — réponse 24-72h.

permisapi_mcp-0.1.0/permisapi_mcp/__init__.py

@@ -0,0 +1,22 @@
+"""permisapi-mcp : serveur MCP pour PermisAPI.
+
+Permet a Claude Desktop, Cursor, Windsurf, ou tout client MCP-compatible
+de consulter les permis de construire France en langage naturel.
+
+Usage :
+    pip install permisapi-mcp
+
+    # Configure Claude Desktop avec :
+    # {
+    #   "mcpServers": {
+    #     "permisapi": {
+    #       "command": "permisapi-mcp",
+    #       "env": {"PERMISAPI_KEY": "pk_live_..."}
+    #     }
+    #   }
+    # }
+
+Voir docs/MCP_SETUP.md pour le guide complet.
+"""
+
+__version__ = "0.1.0"

permisapi_mcp-0.1.0/permisapi_mcp/server.py

@@ -0,0 +1,85 @@
+"""Serveur MCP stdio pour PermisAPI.
+
+Implemente le Model Context Protocol (Anthropic, novembre 2024) en
+mode stdio pour Claude Desktop / Cursor / Windsurf / autres clients
+MCP-compatibles.
+
+Lance via la commande `permisapi-mcp` (entry point pyproject.toml).
+La cle PermisAPI est lue depuis l'env PERMISAPI_KEY au demarrage.
+
+Architecture :
+  - Imports `mcp` lib (Anthropic) au runtime, gracieux si absent
+  - Tools list construit a partir de tools.TOOL_SCHEMAS
+  - Dispatch via tools.call_tool() (logique testable separement)
+"""
+from __future__ import annotations
+
+import asyncio
+import logging
+import sys
+
+logger = logging.getLogger("permisapi-mcp")
+logging.basicConfig(
+    level="INFO",
+    format="%(asctime)s %(levelname)-5s [permisapi-mcp] %(message)s",
+    stream=sys.stderr,  # IMPORTANT : MCP stdio utilise stdout pour le protocole
+)
+
+
+def main() -> None:
+    """Entry point synchrone (appele par `permisapi-mcp` script)."""
+    try:
+        asyncio.run(_run_server())
+    except KeyboardInterrupt:
+        logger.info("Arret demande, bye.")
+    except Exception:  # noqa: BLE001
+        logger.exception("Erreur fatale")
+        sys.exit(1)
+
+
+async def _run_server() -> None:
+    """Cree le serveur MCP et lance le transport stdio."""
+    try:
+        from mcp.server import Server
+        from mcp.server.stdio import stdio_server
+        from mcp.types import TextContent, Tool
+    except ImportError as exc:
+        logger.error(
+            "Le package `mcp` n'est pas installe. Lance "
+            "`pip install permisapi-mcp` pour tout installer correctement. "
+            "Erreur : %s",
+            exc,
+        )
+        sys.exit(2)
+
+    from permisapi_mcp.tools import TOOL_SCHEMAS, call_tool
+
+    app = Server("permisapi")
+
+    @app.list_tools()
+    async def list_tools() -> list[Tool]:
+        return [
+            Tool(
+                name=t["name"],
+                description=t["description"],
+                inputSchema=t["inputSchema"],
+            )
+            for t in TOOL_SCHEMAS
+        ]
+
+    @app.call_tool()
+    async def handle_call_tool(name: str, arguments: dict | None) -> list[TextContent]:
+        result_text = await call_tool(name, arguments or {})
+        return [TextContent(type="text", text=result_text)]
+
+    logger.info("permisapi-mcp pret. Connecte via stdio.")
+    async with stdio_server() as (read_stream, write_stream):
+        await app.run(
+            read_stream,
+            write_stream,
+            app.create_initialization_options(),
+        )
+
+
+if __name__ == "__main__":
+    main()

permisapi_mcp-0.1.0/permisapi_mcp/tools.py

@@ -0,0 +1,378 @@
+"""Tools metier : appels a l'API PermisAPI, independants du protocole MCP.
+
+Cette couche est testable sans avoir le `mcp` package installe : on
+mock juste httpx ou on utilise MockTransport. Le server.py construit
+les Tool MCP a partir d'ici.
+
+6 tools exposes :
+  1. search_permits     : GET /v1/permits avec filtres
+  2. get_permit_details : GET /v1/permits/{num_pa}
+  3. find_dvf_neighbors : GET /v1/permits/{num_pa}/dvf
+  4. get_mdb_score      : GET /v1/permits/{num_pa}/score
+  5. get_plu_zoning     : GET /v1/permits/{num_pa}/plu
+  6. get_risks          : GET /v1/permits/{num_pa}/risks
+
+Securite : la cle API du user est lue depuis l'env PERMISAPI_KEY au
+demarrage du serveur, jamais transmise via les arguments d'un tool.
+Pas de risque qu'un LLM puisse "leaker" la cle dans une reponse.
+"""
+from __future__ import annotations
+
+import json
+import os
+from typing import Any
+
+import httpx
+
+PERMISAPI_BASE = os.environ.get("PERMISAPI_BASE_URL", "https://api.permisapi.fr")
+HTTP_TIMEOUT = 15.0
+
+
+class PermisapiError(Exception):
+    """Erreur retournee par l'API PermisAPI (4xx / 5xx)."""
+
+    def __init__(self, status_code: int, detail: str):
+        self.status_code = status_code
+        self.detail = detail
+        super().__init__(f"PermisAPI {status_code} : {detail}")
+
+
+def _api_key() -> str:
+    """Lit la cle PermisAPI depuis l'env. Raise si absente."""
+    key = os.environ.get("PERMISAPI_KEY")
+    if not key:
+        raise RuntimeError(
+            "PERMISAPI_KEY non configuree. Ajoute-la dans la config "
+            "MCP de ton client (Claude Desktop, Cursor, etc). Obtiens "
+            "une cle gratuite sur https://permisapi.fr/#pricing"
+        )
+    return key
+
+
+async def _http_get(
+    path: str,
+    params: dict[str, Any] | None = None,
+    *,
+    client: httpx.AsyncClient | None = None,
+) -> dict[str, Any]:
+    """Helper GET sur PermisAPI avec auth + gestion d'erreur."""
+    headers = {
+        "X-API-Key": _api_key(),
+        "Accept": "application/json",
+        "User-Agent": "permisapi-mcp/0.1.0",
+    }
+    own_client = client is None
+    c = client or httpx.AsyncClient(timeout=HTTP_TIMEOUT)
+    try:
+        resp = await c.get(f"{PERMISAPI_BASE}{path}", params=params, headers=headers)
+    finally:
+        if own_client:
+            await c.aclose()
+
+    if resp.status_code >= 400:
+        try:
+            payload = resp.json()
+            detail = payload.get("detail") or payload.get("message") or resp.text
+        except (ValueError, AttributeError):
+            detail = resp.text[:200]
+        raise PermisapiError(resp.status_code, str(detail))
+
+    return resp.json()
+
+
+# ----------------------------------------------------------------------------
+# Tool definitions (JSON Schema for inputs)
+# ----------------------------------------------------------------------------
+
+
+TOOL_SCHEMAS: list[dict[str, Any]] = [
+    {
+        "name": "search_permits",
+        "description": (
+            "Recherche des permis de construire France avec filtres "
+            "combinables : departement, commune, type de permis, etat, "
+            "dates, surface min, SIREN demandeur. Retourne une page de "
+            "permits avec leurs infos de base. Plan Free OK."
+        ),
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "dep_code": {
+                    "type": "string",
+                    "description": "Code departement INSEE 2 chars (ex 75 Paris, 33 Bordeaux). Requis pour Free/Explorer.",
+                },
+                "comm_code": {
+                    "type": "string",
+                    "description": "Code commune INSEE 5 chars (ex 75116 Paris 16e).",
+                },
+                "permit_type": {
+                    "type": "string",
+                    "enum": [
+                        "PC_LOGEMENT", "PC_LOCAUX",
+                        "DP_LOGEMENT", "DP_LOCAUX",
+                        "PA", "PD",
+                    ],
+                },
+                "etat_pa": {
+                    "type": "integer",
+                    "description": "Etat permis : 1=Accorde, 2=Tacite, 3=Refuse, 4=Irrecevable, 5=Retrait, 6=Acheve.",
+                    "minimum": 1, "maximum": 6,
+                },
+                "date_from": {"type": "string", "description": "YYYY-MM-DD."},
+                "date_to": {"type": "string", "description": "YYYY-MM-DD."},
+                "min_superficie": {
+                    "type": "integer", "description": "Surface terrain min en m².",
+                },
+                "siren_dem": {
+                    "type": "string",
+                    "description": "SIREN du demandeur (9 chiffres).",
+                },
+                "limit": {"type": "integer", "minimum": 1, "maximum": 50, "default": 20},
+            },
+        },
+    },
+    {
+        "name": "get_permit_details",
+        "description": (
+            "Recupere tous les details d'un permis a partir de son "
+            "identifiant Sitadel (num_pa) : adresse complete, demandeur, "
+            "dates, surface, parcelle cadastre, lat/lng. Plan Free OK."
+        ),
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "num_pa": {
+                    "type": "string",
+                    "description": "Identifiant Sitadel unique (ex PC07404021K1).",
+                },
+            },
+            "required": ["num_pa"],
+        },
+    },
+    {
+        "name": "find_dvf_neighbors",
+        "description": (
+            "Pour un permis, retourne les top transactions immobilieres "
+            "DVF voisines (5 ans glissants). Permet d'estimer la valeur "
+            "fonciere du quartier. Plan Pro+ uniquement."
+        ),
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "num_pa": {"type": "string"},
+                "limit": {"type": "integer", "minimum": 1, "maximum": 5, "default": 3},
+                "type_local": {
+                    "type": "string",
+                    "description": "CSV des types : 1=Maison, 2=Appartement, 3=Dependance, 4=Local commercial.",
+                },
+                "min_year": {"type": "integer", "minimum": 2014, "maximum": 2100},
+            },
+            "required": ["num_pa"],
+        },
+    },
+    {
+        "name": "get_mdb_score",
+        "description": (
+            "Calcule le Score Opportunite Marchand de Biens v0.1 pour "
+            "un permis (note 0-100 + tier low/medium/high/premium + "
+            "breakdown de 7 signaux ponderes). Plan Pro+ uniquement."
+        ),
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "num_pa": {"type": "string"},
+            },
+            "required": ["num_pa"],
+        },
+    },
+    {
+        "name": "get_plu_zoning",
+        "description": (
+            "Retourne le zonage urbanisme PLU au point geocode du permis "
+            "(UA/UB urbain, AU a urbaniser, A agricole, N naturelle) avec "
+            "verdict booleen constructible et raison juridique. Source "
+            "Geoportail de l'Urbanisme. Plan Pro+ uniquement."
+        ),
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "num_pa": {"type": "string"},
+            },
+            "required": ["num_pa"],
+        },
+    },
+    {
+        "name": "get_risks",
+        "description": (
+            "Risques naturels et technologiques (inondation, seisme, "
+            "argile, ICPE proches) connus sur la commune du permis. "
+            "Score agrege 0-100 + tier. Source Georisques BRGM. Plan "
+            "Pro+ uniquement."
+        ),
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "num_pa": {"type": "string"},
+            },
+            "required": ["num_pa"],
+        },
+    },
+]
+
+
+# ----------------------------------------------------------------------------
+# Tool implementations
+# ----------------------------------------------------------------------------
+
+
+def _validate_num_pa(num_pa: Any) -> str:
+    """Defense en profondeur cote MCP : valide que num_pa est string et
+    safe (pas d'injection URL).
+    """
+    if not isinstance(num_pa, str):
+        raise ValueError(f"num_pa doit etre une string, recu : {type(num_pa).__name__}")
+    if not num_pa or len(num_pa) > 50:
+        raise ValueError("num_pa doit faire entre 1 et 50 caracteres")
+    # Whitelist : alphanumeric + space + - + _
+    for c in num_pa:
+        if not (c.isalnum() or c in " -_"):
+            raise ValueError(f"num_pa contient un caractere interdit : {c!r}")
+    return num_pa
+
+
+async def search_permits(
+    arguments: dict[str, Any],
+    *,
+    client: httpx.AsyncClient | None = None,
+) -> dict[str, Any]:
+    """GET /v1/permits avec filtres."""
+    params: dict[str, Any] = {}
+    for k in (
+        "dep_code", "comm_code", "permit_type", "etat_pa",
+        "date_from", "date_to", "min_superficie", "siren_dem",
+    ):
+        v = arguments.get(k)
+        if v is not None and v != "":
+            params[k] = v
+    limit = arguments.get("limit", 20)
+    params["limit"] = max(1, min(50, int(limit)))
+    return await _http_get("/v1/permits", params=params, client=client)
+
+
+async def get_permit_details(
+    arguments: dict[str, Any],
+    *,
+    client: httpx.AsyncClient | None = None,
+) -> dict[str, Any]:
+    """GET /v1/permits/{num_pa}."""
+    num_pa = _validate_num_pa(arguments.get("num_pa"))
+    return await _http_get(f"/v1/permits/{num_pa}", client=client)
+
+
+async def find_dvf_neighbors(
+    arguments: dict[str, Any],
+    *,
+    client: httpx.AsyncClient | None = None,
+) -> dict[str, Any]:
+    """GET /v1/permits/{num_pa}/dvf."""
+    num_pa = _validate_num_pa(arguments.get("num_pa"))
+    params: dict[str, Any] = {}
+    if "limit" in arguments and arguments["limit"] is not None:
+        params["limit"] = max(1, min(5, int(arguments["limit"])))
+    if arguments.get("type_local"):
+        params["type_local"] = arguments["type_local"]
+    if arguments.get("min_year") is not None:
+        params["min_year"] = int(arguments["min_year"])
+    return await _http_get(
+        f"/v1/permits/{num_pa}/dvf", params=params or None, client=client
+    )
+
+
+async def get_mdb_score(
+    arguments: dict[str, Any],
+    *,
+    client: httpx.AsyncClient | None = None,
+) -> dict[str, Any]:
+    """GET /v1/permits/{num_pa}/score."""
+    num_pa = _validate_num_pa(arguments.get("num_pa"))
+    return await _http_get(f"/v1/permits/{num_pa}/score", client=client)
+
+
+async def get_plu_zoning(
+    arguments: dict[str, Any],
+    *,
+    client: httpx.AsyncClient | None = None,
+) -> dict[str, Any]:
+    """GET /v1/permits/{num_pa}/plu."""
+    num_pa = _validate_num_pa(arguments.get("num_pa"))
+    return await _http_get(f"/v1/permits/{num_pa}/plu", client=client)
+
+
+async def get_risks(
+    arguments: dict[str, Any],
+    *,
+    client: httpx.AsyncClient | None = None,
+) -> dict[str, Any]:
+    """GET /v1/permits/{num_pa}/risks."""
+    num_pa = _validate_num_pa(arguments.get("num_pa"))
+    return await _http_get(f"/v1/permits/{num_pa}/risks", client=client)
+
+
+# ----------------------------------------------------------------------------
+# Dispatch
+# ----------------------------------------------------------------------------
+
+
+TOOL_HANDLERS = {
+    "search_permits": search_permits,
+    "get_permit_details": get_permit_details,
+    "find_dvf_neighbors": find_dvf_neighbors,
+    "get_mdb_score": get_mdb_score,
+    "get_plu_zoning": get_plu_zoning,
+    "get_risks": get_risks,
+}
+
+
+async def call_tool(
+    name: str,
+    arguments: dict[str, Any],
+    *,
+    client: httpx.AsyncClient | None = None,
+) -> str:
+    """Dispatch un appel de tool MCP vers la bonne fonction handler.
+
+    Retourne du texte JSON-encoded (le format attendu par MCP TextContent).
+    Les erreurs sont retournees comme texte d'erreur, pas raised, car
+    MCP attend toujours du contenu (pas une exception).
+    """
+    handler = TOOL_HANDLERS.get(name)
+    if handler is None:
+        return json.dumps({"error": f"Tool inconnu : {name}"}, ensure_ascii=False)
+
+    try:
+        result = await handler(arguments, client=client)
+        return json.dumps(result, ensure_ascii=False, indent=2)
+    except PermisapiError as exc:
+        return json.dumps(
+            {
+                "error": "permisapi_error",
+                "status_code": exc.status_code,
+                "detail": exc.detail,
+            },
+            ensure_ascii=False,
+        )
+    except ValueError as exc:
+        return json.dumps(
+            {"error": "validation", "detail": str(exc)},
+            ensure_ascii=False,
+        )
+    except RuntimeError as exc:
+        return json.dumps(
+            {"error": "config", "detail": str(exc)},
+            ensure_ascii=False,
+        )
+    except Exception as exc:  # noqa: BLE001
+        return json.dumps(
+            {"error": "internal", "detail": f"{type(exc).__name__}: {exc}"},
+            ensure_ascii=False,
+        )

permisapi_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "permisapi-mcp"
+version = "0.1.0"
+description = "MCP server pour PermisAPI : permettez a Claude / ChatGPT / Cursor de consulter les permis de construire France en langage naturel."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [
+    { name = "Evan Caroux", email = "evan@permisapi.fr" },
+]
+keywords = ["permis", "construire", "france", "mcp", "claude", "chatgpt", "anthropic", "real-estate", "sitadel"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Natural Language :: French",
+]
+dependencies = [
+    "mcp>=1.0.0",
+    "permisapi-client>=0.6.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.4",
+    "pytest-asyncio>=0.23",
+]
+
+[project.scripts]
+permisapi-mcp = "permisapi_mcp.server:main"
+
+[project.urls]
+Homepage = "https://permisapi.fr/mcp"
+Documentation = "https://permisapi.fr/mcp"
+Setup = "https://github.com/Evan-Crx/permisapi/blob/master/docs/MCP_SETUP.md"
+
+[tool.hatch.build.targets.wheel]
+packages = ["permisapi_mcp"]

permisapi_mcp-0.1.0/tests/test_tools.py

@@ -0,0 +1,320 @@
+"""Tests des tools MCP : valident la logique metier sans dependre du
+package `mcp` (le test du protocole stdio est out-of-scope, c'est de
+l'integration avec Anthropic SDK).
+"""
+from __future__ import annotations
+
+import json
+import os
+from contextlib import contextmanager
+
+import httpx
+import pytest
+
+from permisapi_mcp.tools import (
+    TOOL_HANDLERS,
+    TOOL_SCHEMAS,
+    PermisapiError,
+    _validate_num_pa,
+    call_tool,
+)
+
+
+@contextmanager
+def env(**kwargs):
+    """Set env vars for the duration of a test."""
+    old: dict[str, str | None] = {k: os.environ.get(k) for k in kwargs}
+    for k, v in kwargs.items():
+        if v is None:
+            os.environ.pop(k, None)
+        else:
+            os.environ[k] = v
+    try:
+        yield
+    finally:
+        for k, v in old.items():
+            if v is None:
+                os.environ.pop(k, None)
+            else:
+                os.environ[k] = v
+
+
+def _mock_transport(handler):
+    return httpx.AsyncClient(transport=httpx.MockTransport(handler))
+
+
+# ----------------------------------------------------------------------------
+# Schemas
+# ----------------------------------------------------------------------------
+
+
+def test_six_tools_defined():
+    names = {t["name"] for t in TOOL_SCHEMAS}
+    assert names == {
+        "search_permits",
+        "get_permit_details",
+        "find_dvf_neighbors",
+        "get_mdb_score",
+        "get_plu_zoning",
+        "get_risks",
+    }
+
+
+def test_each_schema_has_required_fields():
+    for t in TOOL_SCHEMAS:
+        assert t["name"]
+        assert t["description"]
+        assert "inputSchema" in t
+        assert t["inputSchema"]["type"] == "object"
+
+
+def test_schemas_have_handlers():
+    for t in TOOL_SCHEMAS:
+        assert t["name"] in TOOL_HANDLERS
+
+
+# ----------------------------------------------------------------------------
+# _validate_num_pa
+# ----------------------------------------------------------------------------
+
+
+def test_validate_num_pa_accepts_valid():
+    for ok in [
+        "PC07404021K1",
+        "PC 075 116 22 B0042",
+        "DP_075_108_23_B0012",
+        "PA-44-2024-0001",
+    ]:
+        assert _validate_num_pa(ok) == ok
+
+
+def test_validate_num_pa_rejects_dangerous():
+    for bad in [
+        "<script>",
+        "PC';DROP",
+        "PC\nSubject: x",
+        "PC@x.com",
+        "PC<>",
+    ]:
+        with pytest.raises(ValueError):
+            _validate_num_pa(bad)
+
+
+def test_validate_num_pa_rejects_non_string():
+    for bad in [None, 42, ["PC1"], {}]:
+        with pytest.raises(ValueError):
+            _validate_num_pa(bad)
+
+
+def test_validate_num_pa_rejects_too_long():
+    with pytest.raises(ValueError):
+        _validate_num_pa("A" * 51)
+
+
+def test_validate_num_pa_rejects_empty():
+    with pytest.raises(ValueError):
+        _validate_num_pa("")
+
+
+# ----------------------------------------------------------------------------
+# call_tool : auth requise
+# ----------------------------------------------------------------------------
+
+
+@pytest.mark.asyncio
+async def test_call_tool_requires_api_key():
+    with env(PERMISAPI_KEY=None):
+        result = await call_tool("get_permit_details", {"num_pa": "PC1"})
+    parsed = json.loads(result)
+    assert parsed["error"] == "config"
+    assert "PERMISAPI_KEY" in parsed["detail"]
+
+
+@pytest.mark.asyncio
+async def test_call_tool_unknown_tool_returns_error():
+    with env(PERMISAPI_KEY="pk_test_x"):
+        result = await call_tool("unknown_tool", {})
+    parsed = json.loads(result)
+    assert "error" in parsed
+    assert "unknown_tool" in parsed["error"]
+
+
+# ----------------------------------------------------------------------------
+# call_tool : forwards to PermisAPI correctly
+# ----------------------------------------------------------------------------
+
+
+@pytest.mark.asyncio
+async def test_search_permits_calls_correct_url():
+    captured = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        captured["url"] = str(request.url)
+        captured["headers"] = dict(request.headers)
+        return httpx.Response(200, json={"data": [], "pagination": {}})
+
+    with env(PERMISAPI_KEY="pk_test_xyz", PERMISAPI_BASE_URL="https://api.test"):
+        async with _mock_transport(handler) as client:
+            from permisapi_mcp.tools import search_permits
+
+            await search_permits(
+                {"dep_code": "75", "limit": 5}, client=client
+            )
+    assert "/v1/permits" in captured["url"]
+    assert "dep_code=75" in captured["url"]
+    assert "limit=5" in captured["url"]
+    assert captured["headers"]["x-api-key"] == "pk_test_xyz"
+
+
+@pytest.mark.asyncio
+async def test_get_permit_details_calls_correct_url():
+    captured = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        captured["url"] = str(request.url)
+        return httpx.Response(200, json={"num_pa": "PC1"})
+
+    with env(PERMISAPI_KEY="pk_test_xyz", PERMISAPI_BASE_URL="https://api.test"):
+        async with _mock_transport(handler) as client:
+            from permisapi_mcp.tools import get_permit_details
+
+            await get_permit_details({"num_pa": "PC07404021K1"}, client=client)
+    assert "/v1/permits/PC07404021K1" in captured["url"]
+
+
+@pytest.mark.asyncio
+async def test_find_dvf_neighbors_calls_correct_url():
+    captured = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        captured["url"] = str(request.url)
+        return httpx.Response(200, json={"matches": []})
+
+    with env(PERMISAPI_KEY="pk_test_xyz", PERMISAPI_BASE_URL="https://api.test"):
+        async with _mock_transport(handler) as client:
+            from permisapi_mcp.tools import find_dvf_neighbors
+
+            await find_dvf_neighbors(
+                {"num_pa": "PC1", "limit": 5, "min_year": 2023},
+                client=client,
+            )
+    assert "/v1/permits/PC1/dvf" in captured["url"]
+    assert "limit=5" in captured["url"]
+    assert "min_year=2023" in captured["url"]
+
+
+@pytest.mark.asyncio
+async def test_get_mdb_score_calls_correct_url():
+    captured = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        captured["url"] = str(request.url)
+        return httpx.Response(200, json={"score": 78})
+
+    with env(PERMISAPI_KEY="pk_test_xyz", PERMISAPI_BASE_URL="https://api.test"):
+        async with _mock_transport(handler) as client:
+            from permisapi_mcp.tools import get_mdb_score
+
+            await get_mdb_score({"num_pa": "PC1"}, client=client)
+    assert "/v1/permits/PC1/score" in captured["url"]
+
+
+@pytest.mark.asyncio
+async def test_get_plu_zoning_calls_correct_url():
+    captured = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        captured["url"] = str(request.url)
+        return httpx.Response(200, json={"has_plu": True})
+
+    with env(PERMISAPI_KEY="pk_test_xyz", PERMISAPI_BASE_URL="https://api.test"):
+        async with _mock_transport(handler) as client:
+            from permisapi_mcp.tools import get_plu_zoning
+
+            await get_plu_zoning({"num_pa": "PC1"}, client=client)
+    assert "/v1/permits/PC1/plu" in captured["url"]
+
+
+@pytest.mark.asyncio
+async def test_get_risks_calls_correct_url():
+    captured = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        captured["url"] = str(request.url)
+        return httpx.Response(200, json={"risk_score": 25})
+
+    with env(PERMISAPI_KEY="pk_test_xyz", PERMISAPI_BASE_URL="https://api.test"):
+        async with _mock_transport(handler) as client:
+            from permisapi_mcp.tools import get_risks
+
+            await get_risks({"num_pa": "PC1"}, client=client)
+    assert "/v1/permits/PC1/risks" in captured["url"]
+
+
+# ----------------------------------------------------------------------------
+# Error handling
+# ----------------------------------------------------------------------------
+
+
+@pytest.mark.asyncio
+async def test_permisapi_4xx_raises_permisapierror():
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(402, json={"detail": "Plan Pro requis"})
+
+    with env(PERMISAPI_KEY="pk_test_xyz", PERMISAPI_BASE_URL="https://api.test"):
+        async with _mock_transport(handler) as client:
+            from permisapi_mcp.tools import get_mdb_score
+
+            with pytest.raises(PermisapiError) as exc_info:
+                await get_mdb_score({"num_pa": "PC1"}, client=client)
+            assert exc_info.value.status_code == 402
+
+
+@pytest.mark.asyncio
+async def test_call_tool_handles_402_and_returns_error_text():
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(402, json={"detail": "Plan Pro requis"})
+
+    # call_tool ne prend pas client, on monkeypatch via env
+    with env(PERMISAPI_KEY="pk_test_xyz", PERMISAPI_BASE_URL="https://api.test"):
+        # Le call_tool va creer son propre client httpx, donc on ne peut pas
+        # facilement injecter le mock. On test plutot via le handler.
+        # Pour ce test, on test le format d'erreur via une exception simulee
+        from permisapi_mcp.tools import call_tool as ct
+
+        # Force une PermisapiError en patchant le handler avec un client
+        # qui rejette
+        result = await ct(
+            "get_permit_details",
+            {"num_pa": "PC1"},
+            client=httpx.AsyncClient(transport=httpx.MockTransport(handler)),
+        )
+    parsed = json.loads(result)
+    assert parsed["error"] == "permisapi_error"
+    assert parsed["status_code"] == 402
+
+
+@pytest.mark.asyncio
+async def test_call_tool_handles_validation_error():
+    with env(PERMISAPI_KEY="pk_test_xyz"):
+        result = await call_tool(
+            "get_permit_details", {"num_pa": "<script>alert(1)</script>"}
+        )
+    parsed = json.loads(result)
+    assert parsed["error"] == "validation"
+
+
+@pytest.mark.asyncio
+async def test_call_tool_returns_json_text_on_success():
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(200, json={"num_pa": "PC1", "etat_pa": 1})
+
+    with env(PERMISAPI_KEY="pk_test_xyz", PERMISAPI_BASE_URL="https://api.test"):
+        result = await call_tool(
+            "get_permit_details",
+            {"num_pa": "PC1"},
+            client=httpx.AsyncClient(transport=httpx.MockTransport(handler)),
+        )
+    parsed = json.loads(result)
+    assert parsed["num_pa"] == "PC1"
+    assert parsed["etat_pa"] == 1