permisapi-mcp 0.1.0__py3-none-any.whl

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/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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,7 @@
+permisapi_mcp/__init__.py,sha256=w827Sv18pA1gI-2GxfRkPnziVbIPfFbv6165oipUZfg,539
+permisapi_mcp/server.py,sha256=Gb7Nsya1kmyzTjSs_34bE8c_flX1bwugdddEzE0-mB4,2639
+permisapi_mcp/tools.py,sha256=uEp63BfEM_rFPcsOTp0rw9PwgEPQX2QMaJGXajKzIMg,13357
+permisapi_mcp-0.1.0.dist-info/METADATA,sha256=LSq1STXBhcI-N-7yPVtqAbcInTZWFS1OWxXmL6eMy-0,3246
+permisapi_mcp-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+permisapi_mcp-0.1.0.dist-info/entry_points.txt,sha256=LOkP_9LtZ3k-jL4_svD3dJ2F4fQsm4lGSGkguj497XE,60
+permisapi_mcp-0.1.0.dist-info/RECORD,,

permisapi_mcp-0.1.0.dist-info/WHEEL

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

permisapi_mcp-0.1.0.dist-info/entry_points.txt

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