Metadata-Version: 2.4
Name: permisapi-mcp
Version: 0.4.0
Summary: MCP server pour PermisAPI : 10 outils pour consulter 1,2 M+ permis de construire de France (2014-2026) depuis Claude Desktop, Cursor, Windsurf et tout client MCP-compatible.
Project-URL: Homepage, https://permisapi.fr/mcp
Project-URL: Documentation, https://permisapi.fr/mcp
Project-URL: Setup, https://github.com/Evan-Crx/permisapi-mcp/blob/main/README.md
Project-URL: Source, https://github.com/Evan-Crx/permisapi-mcp
Project-URL: Issues, https://github.com/Evan-Crx/permisapi-mcp/issues
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.7.2
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 a **Claude Desktop**, **Cursor**, **Windsurf** ou tout client MCP-compatible
de consulter **1,2 M+ permis de construire de France** (Sitadel 2014-2026,
residentiel + non-residentiel, depuis 2014) en langage naturel.

10 outils disponibles : recherche par adresse, score d'opportunite Marchand de
Biens, prix au m² des ventes voisines sur 12 ans, zonage urbanisme PLU, risques
(inondation, sismique, ICPE), parcelle cadastre DGFiP, et enrichissement de
liste client.

## Pre-requis

- **Python 3.10 ou plus recent** (requis par le MCP SDK Anthropic, non negociable)
- Une cle PermisAPI : [https://permisapi.fr/#pricing](https://permisapi.fr/#pricing) (gratuite pour commencer)

## Installation

Verifier d'abord la version Python :

```bash
python --version       # macOS / Linux / Windows
```

Si `>= 3.10` :

```bash
pip install permisapi-mcp
```

Si `< 3.10`, voir la section [Troubleshooting](#troubleshooting) plus bas
(workaround `uvx` en 1 commande, pas besoin d'upgrade systeme).

## Configuration Claude Desktop

Editez `~/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"
      }
    }
  }
}
```

Redemarrez Claude Desktop. Vous pouvez maintenant demander :

> *« Liste les permis de logement deposes a Bordeaux ce mois avec un score MDB > 70 »*
>
> *« Trouve-moi des opportunites MDB autour de la rue de Passy a 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 (10)

| Tool | Endpoint | Plan |
|---|---|:---:|
| `search_permits` | GET /v1/permits (13 filtres) | Free |
| `get_permit_details` | GET /v1/permits/{num_pa} | Free |
| `fuzzy_search_addresses` | GET /v1/search?q=text (pg_trgm fuzzy) | Free |
| `find_dvf_neighbors` | GET /v1/permits/{num_pa}/dvf (12 ans : Cerema DVF+ 2014-2020 fusionne Geo-DVF 2021-2025) | Pro |
| `get_mdb_score` | GET /v1/permits/{num_pa}/score (Score MDB v0.2, 10 signaux) | Pro |
| `get_plu_zoning` | GET /v1/permits/{num_pa}/plu | Pro |
| `get_risks` | GET /v1/permits/{num_pa}/risks (Georisques BRGM) | Pro |
| `get_parcelle_geometry` | GET /v1/permits/{num_pa}/parcelle (cadastre DGFiP) | Pro |
| `get_permit_full_view` | GET /v1/permits/{num_pa}/360 (composite 6-en-1) | Pro |
| `bulk_enrich_list` | POST /v1/permits/bulk-enrich (croise liste client jusqu'a 1 000 lignes) | Business |

## Securite

- La cle API reste **cote user** (env var locale, jamais transmise au LLM)
- Le LLM voit uniquement les arguments des tools (pas la cle)
- Validation stricte des inputs (regex sur `num_pa`, ranges Pydantic)
- 9 outils en consultation pure (GET) + 1 outil de croisement de liste (POST
  bulk_enrich_list, lecture seule cote PermisAPI : renvoie les permis qui
  matchent les adresses du client, sans stocker la liste)

## Troubleshooting

### `pip install permisapi-mcp` dit "package introuvable" ou "no matching distribution"

Cause la plus frequente : votre Python est plus ancien que 3.10. Le MCP SDK
Anthropic requiert Python 3.10 minimum, on ne peut pas descendre cette borne.

Verifiez :

```bash
python --version       # ou python3 --version
```

Si `< 3.10`, deux solutions au choix.

**Solution A (recommandee, 30 secondes) : `uvx` avec pin Python**

`uvx` installe et lance le serveur dans un Python isole pinne a la version
voulue, sans toucher a votre installation systeme.

```bash
# 1. Installer uv (une seule fois)
curl -LsSf https://astral.sh/uv/install.sh | sh         # macOS / Linux
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"  # Windows PowerShell

# 2. Lancer le serveur
uvx --python 3.11 permisapi-mcp
```

Puis dans la config Claude Desktop, remplacez `"command": "permisapi-mcp"` par :

```json
{
  "mcpServers": {
    "permisapi": {
      "command": "uvx",
      "args": ["--python", "3.11", "permisapi-mcp"],
      "env": { "PERMISAPI_KEY": "pk_live_VOTRE_CLE" }
    }
  }
}
```

**Solution B : upgrade Python systeme**

- macOS : `brew install python@3.11`
- Windows : telecharger https://www.python.org/downloads/ et cocher "Add to PATH"
- Linux : `sudo apt install python3.11` (ou equivalent distro)

Puis `pip3.11 install permisapi-mcp`.

Guide setup complet + autres FAQ : [https://permisapi.fr/mcp](https://permisapi.fr/mcp)

## Licence

MIT.

## Support

evan@permisapi.fr - reponse 24-48h sur les plans Pro+, 24-72h sur les autres.

## Code source

[github.com/Evan-Crx/permisapi-mcp](https://github.com/Evan-Crx/permisapi-mcp)
