Skip to content
Back to search

datagouv-mcp

Official data.gouv.fr Model Context Protocol (MCP) server that allows AI chatbots to search, explore, and analyze datasets from the French national Open Data platform, directly through conversation.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/datagouv/datagouv-mcp with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/datagouv/datagouv-mcp'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/datagouv--datagouv-mcp/badge.svg)](/listings/datagouv--datagouv-mcp)

HTML

<a href="/listings/datagouv--datagouv-mcp"><img src="/api/listings/datagouv--datagouv-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

You will need [uv](https://github.com/astral-sh/uv) to install dependencies and run the server.

1. **Install dependencies**

  uv sync

2. **Prepare the environment file**

Copy the [example environment file](.env.example) to create your own `.env` file:

  cp .env.example .env

Then optionally edit `.env` and set the variables that matter for your run:

  MCP_HOST=127.0.0.1  # (defaults to 0.0.0.0, use 127.0.0.1 for local dev)
  MCP_PORT=8007  # (defaults to 8000 when unset)
  MCP_ENV=local  # environment name sent to Sentry (defaults to local when unset)
  DATAGOUV_API_ENV=prod  # Allowed values: demo | prod (defaults to prod when unset)
  LOG_LEVEL=INFO  # Python log level (default: INFO)

Load the variables with your preferred method, e.g.:

  set -a && source .env && set +a

3. **Start the HTTP MCP server**

  uv run main.py

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 546 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # data.gouv.fr MCP Server
  2. <img width="1200" height="675" alt="image" src="https://github.com/user-attachments/assets/5d20e992-349a-4b3b-9a0a-ebe308735cc9" />
  3. > [!TIP]
  4. > Got feedback? [Tell us about it here](https://tally.so/r/KYMboX)
  5. [![CircleCI](https://circleci.com/gh/datagouv/datagouv-mcp.svg?style=svg)](https://circleci.com/gh/datagouv/datagouv-mcp)
  6. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  7. Model Context Protocol (MCP) server that allows AI chatbots (Claude, ChatGPT, Gemini, etc.) to search, explore, and analyze datasets from [data.gouv.fr](https://www.data.gouv.fr), the French national Open Data platform, directly through conversation.
  8. Instead of manually browsing the website, you can simply ask questions like "Quels jeux de données sont disponibles sur les prix de l'immobilier ?" or "Montre-moi les dernières données de population pour Paris" and get instant answers.
  9. > [!TIP]
  10. > Use it now: A public instance is available for everyone at https://mcp.data.gouv.fr/mcp with no access restrictions.
  11. > To connect your favorite chatbot, simply follow [the connection instructions below](#-connect-your-chatbot-to-the-mcp-server).
  12. For a French introduction to the server, see the [data.gouv.fr guides](https://guides.data.gouv.fr/intelligence-artificielle/le-serveur-mcp-de-data.gouv.fr).
  13. ## 🌐 Connect your chatbot to the MCP server
  14. Use the hosted endpoint `https://mcp.data.gouv.fr/mcp` (recommended). If you self-host, swap in your own URL.
  15. The MCP server configuration depends on your client. Use the appropriate configuration format for your client:
  16. [AnythingLLM](#anythingllm) | [L'Assistant](#lassistant) | [Autohand Code](#autohand-code) | [ChatGPT](#chatgpt) | [Claude](#claude) | [Claude Code](#claude-code) | [Cursor](#cursor) | [Gemini CLI](#gemini-cli) | [HuggingChat](#huggingchat) | [IBM Bob](#ibm-bob) | [Kiro CLI](#kiro-cli) | [Kiro IDE](#kiro-ide) | [Mistral Vibe](#mistral-vibe) | [Mistral Vibe CLI](#mistral-vibe-cli) | [OpenCode](#opencode) | [VS Code](#vs-code) | [Windsurf](#windsurf)
  17. ### AnythingLLM
  18. 1. Locate the `anythingllm_mcp_servers.json` file in your AnythingLLM storage plugins directory:
  19. - **Linux**: `~/.config/anythingllm-desktop/storage/plugins/anythingllm_mcp_servers.json`
  20. - **MacOS**: `~/Library/Application Support/anythingllm-desktop/storage/plugins/anythingllm_mcp_servers.json`
  21. - **Windows**: `C:\Users\<username>\AppData\Roaming\anythingllm-desktop\storage\plugins\anythingllm_mcp_servers.json`
  22. 2. Add the following configuration:
  23. ```json
  24. {
  25. "mcpServers": {
  26. "datagouv": {
  27. "type": "streamable",
  28. "url": "https://mcp.data.gouv.fr/mcp"
  29. }
  30. }
  31. }
  32. ```
  33. For more details, see the [AnythingLLM MCP documentation](https://docs.anythingllm.com/mcp-compatibility/overview).
  34. ### L'Assistant
  35. *For French public servants only.*
  36. The data.gouv.fr MCP connector is available directly to French public servants. Log in to [L'Assistant](https://assistant.numerique.gouv.fr/home), then select the data.gouv.fr connector to use it in your conversations.
  37. ### Autohand Code
  38. Use the [Autohand Code](https://github.com/autohandai/code-cli/) CLI to register the hosted endpoint:
  39. ```shell
  40. autohand mcp add --transport http datagouv https://mcp.data.gouv.fr/mcp
  41. ```
  42. Add `--scope project` to keep the registration in the current workspace.
  43. ### ChatGPT
  44. *Available for paid plans only (Plus, Pro, Team, and Enterprise).*
  45. 1. **Access Settings**: Open ChatGPT in your browser, go to `Settings`, then `Apps and connectors`.
  46. 2. **Enable Dev Mode**: Open `Advanced settings` and enable **Developer mode**.
  47. 3. **Add Connector**: Return to `Settings` > `Connectors` > `Browse connectors` and click **Add a new connector**.
  48. 4. **Configure the connector**: Set the URL to `https://mcp.data.gouv.fr/mcp` and save to activate the tools.
  49. ### Claude
  50. *Available on claude.ai, Claude Desktop and Cowork, on all plans (Free plans are limited to one custom connector).*
  51. 1. **Go to Connectors**: Open `Customize` > `Connectors`.
  52. 2. **Add a custom connector**: Click **+ Add** > **Add custom connector**.
  53. 3. **Configure the connector**: Give it a name (for example `datagouv`), set the URL to `https://mcp.data.gouv.fr/mcp`, and click **Add**. No authentication is needed.
  54. See the official docs: [About custom connectors using remote MCP](https://support.claude.com/en/articles/11175166-about-custom-connectors-using-remote-mcp).
  55. ### Claude Code
  56. Use the `claude mcp` command to add the MCP server:
  57. ```shell
  58. claude mcp add --transport http datagouv https://mcp.data.gouv.fr/mcp
  59. ```
  60. ### Cursor
  61. Cursor supports MCP servers through its settings. To configure the server:
  62. 1. Open Cursor Settings
  63. 2. Search for "MCP" or "Model Context Protocol"
  64. 3. Add a new MCP server with the following configuration:
  65. ```json
  66. {
  67. "mcpServers": {
  68. "datagouv": {
  69. "url": "https://mcp.data.gouv.fr/mcp",
  70. "transport": "http"
  71. }
  72. }
  73. }
  74. ```
  75. ### Gemini CLI
  76. Add the following to your `~/.gemini/settings.json` file (Linux: `~/.gemini/settings.json`, MacOS: `~/.gemini/settings.json`, Windows: `%USERPROFILE%\.gemini\settings.json`):
  77. ```json
  78. {
  79. "mcpServers": {
  80. "datagouv": {
  81. "httpUrl": "https://mcp.data.gouv.fr/mcp"
  82. }
  83. }
  84. }
  85. ```
  86. ### HuggingChat
  87. 1. **Access Settings:** In the chat interface, click the + icon, select `MCP Servers`, and click `Manage MCP Servers`.
  88. 2. **Add Server:** Click the + `Add Server` button in the server management window.
  89. 3. **Configure the Server:** Enter a **Server Name** (e.g., "Data Gouv") and set the **Server URL** to `https://mcp.data.gouv.fr/mcp`. Click `Add Server` to save.
  90. 4. **Verify Connection:** Click the `Health Check` button on the new server card to confirm it displays as **Connected**. Ensure the toggle is activated to use the tools in your chat.
  91. ### IBM Bob
  92. IBM Bob supports MCP servers through its settings. To configure the server:
  93. 1. Click the setting icon in the Bob panel.
  94. 2. Select the MCP tab.
  95. 3. Click the appropriate button:
  96. - Edit Global MCP: Opens the global `mcp_settings.json` file
  97. - Edit Project MCP: Opens the project-specific `.bob/mcp.json` file (Bob creates it if it does not exist)
  98. Both files use JSON format with an mcpServers object containing named server configurations.
  99. ```json
  100. {
  101. "mcpServers": {
  102. "datagouv": {
  103. "url": "https://mcp.data.gouv.fr/mcp",
  104. "type": "streamable-http"
  105. }
  106. }
  107. }
  108. ```
  109. ### Kiro CLI
  110. Add the following to `~/.kiro/settings/mcp.json` (Linux: `~/.kiro/settings/mcp.json`, MacOS: `~/.kiro/settings/mcp.json`, Windows: `%USERPROFILE%\.kiro\settings\mcp.json`):
  111. ```json
  112. {
  113. "mcpServers": {
  114. "datagouv": {
  115. "url": "https://mcp.data.gouv.fr/mcp"
  116. }
  117. }
  118. }
  119. ```
  120. ### Kiro IDE
  121. Add the following to your Kiro MCP configuration file (`.kiro/settings/mcp.json` in your workspace, or for global config: Linux: `~/.kiro/settings/mcp.json`, MacOS: `~/.kiro/settings/mcp.json`, Windows: `%USERPROFILE%\.kiro\settings\mcp.json`):
  122. ```json
  123. {
  124. "mcpServers": {
  125. "datagouv": {
  126. "url": "https://mcp.data.gouv.fr/mcp"
  127. }
  128. }
  129. }
  130. ```
  131. ### Mistral Vibe
  132. *Formerly Le Chat. Available on all plans, including free.*
  133. 1. **Go to Connectors**: Open Mistral Vibe in your browser, then go to `Connectors`.
  134. 2. **Add a custom connector**: Click **+ Add Connector** and open the **Custom MCP Connector** tab.
  135. 3. **Configure the connector**: Give it a name (for example `datagouv`) and set the server URL to `https://mcp.data.gouv.fr/mcp`. Leave authentication disabled.
  136. 4. **Create**: Click **Create**.
  137. See the official docs: [MCP connectors](https://docs.mistral.ai/vibe/work/connectors/mcp-connectors).
  138. ### Mistral Vibe CLI
  139. Edit your Vibe config (default: Linux: `~/.vibe/config.toml`, MacOS: `~/.vibe/config.toml`, Windows: `%USERPROFILE%\.vibe\config.toml`) and add the MCP server:
  140. ```toml
  141. [[mcp_servers]]
  142. name = "datagouv"
  143. transport = "streamable-http"
  144. url = "https://mcp.data.gouv.fr/mcp"
  145. ```
  146. See the full Vibe MCP options in the official docs: [MCP server configuration](https://github.com/mistralai/mistral-vibe?tab=readme-ov-file#mcp-server-configuration).
  147. ### OpenCode
  148. Add to `opencode.json` (e.g. `~/.config/opencode/opencode.json` or your project root). Remote servers use the top-level `mcp` object with `type: "remote"`. See [OpenCode MCP servers](https://opencode.ai/docs/mcp-servers/).
  149. ```json
  150. {
  151. "$schema": "https://opencode.ai/config.json",
  152. "mcp": {
  153. "datagouv": {
  154. "type": "remote",
  155. "url": "https://mcp.data.gouv.fr/mcp",
  156. "enabled": true
  157. }
  158. }
  159. }
  160. ```
  161. ### VS Code
  162. Add the following to your VS Code `mcp.json` file (Linux: `~/.config/Code/User/mcp.json`, MacOS: `~/Library/Application Support/Code/User/mcp.json`, Windows: `%APPDATA%\Code\User\mcp.json`). Run **MCP: Open User Configuration** from the Command Palette to open it.
  163. ```json
  164. {
  165. "servers": {
  166. "datagouv": {
  167. "url": "https://mcp.data.gouv.fr/mcp",
  168. "type": "http"
  169. }
  170. }
  171. }
  172. ```
  173. ### Windsurf
  174. Add the following to your `~/.codeium/windsurf/mcp_config.json` (Linux: `~/.codeium/windsurf/mcp_config.json`, MacOS: `~/.codeium/windsurf/mcp_config.json`, Windows: `%USERPROFILE%\.codeium\windsurf\mcp_config.json`):
  175. ```json
  176. {
  177. "mcpServers": {
  178. "datagouv": {
  179. "command": "npx",
  180. "args": [
  181. "-y",
  182. "mcp-remote",
  183. "https://mcp.data.gouv.fr/mcp"
  184. ]
  185. }
  186. }
  187. }
  188. ```
  189. **Note:**
  190. - The hosted endpoint is `https://mcp.data.gouv.fr/mcp`. If you run the server yourself, replace it with your own URL (see “Run locally” below for the default local endpoint).
  191. - This MCP server only exposes read-only tools for now, so no API key is required.
  192. ## 🖥️ Run locally
  193. ### 1. Run the MCP server
  194. Before starting, clone this repository and browse into it:
  195. ```shell
  196. git clone git@github.com:datagouv/datagouv-mcp.git
  197. cd datagouv-mcp
  198. ```
  199. Docker is required for the recommended setup. Install it via [Docker Desktop](https://www.docker.com/products/docker-desktop/) or any compatible Docker Engine before continuing.
  200. #### 🐳 With Docker (Recommended)
  201. ```shell
  202. # With default settings (port 8000, prod environment)
  203. docker compose up -d
  204. # With custom environment variables
  205. MCP_PORT=8007 DATAGOUV_API_ENV=demo LOG_LEVEL=DEBUG docker compose up -d
  206. # Stop
  207. docker compose down
  208. ```
  209. **Environment variables:**
  210. - `MCP_HOST`: host to bind to (defaults to `0.0.0.0`). Set to `127.0.0.1` for local development to follow MCP security best practices.
  211. - `MCP_PORT`: port for the MCP HTTP server (defaults to `8000` when unset).
  212. - `MCP_ENV`: environment name reported to Sentry (defaults to `local` when unset). Set explicitly to `prod`, `preprod`, or `demo` in your deployment.
  213. - `DATAGOUV_API_ENV`: `prod` (default) or `demo`. This controls which data.gouv.fr environement it uses the data from (https://www.data.gouv.fr or https://demo.data.gouv.fr). By default the MCP server talks to the production data.gouv.fr. Set `DATAGOUV_API_ENV=demo` if you specifically need the demo environment.
  214. - `LOG_LEVEL`: Python logging level for the application (defaults to `INFO`). Common values: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`.
  215. - `SENTRY_DSN`: Sentry DSN to enable error and performance monitoring. Monitoring is disabled when unset.
  216. - `SENTRY_SAMPLE_RATE`: sampling rate for Sentry traces and profiles (float `0.0`–`1.0`, defaults to `1.0`).
  217. #### ⚙️ Manual Installation
  218. You will need [uv](https://github.com/astral-sh/uv) to install dependencies and run the server.
  219. 1. **Install dependencies**
  220. ```shell
  221. uv sync
  222. ```
  223. 2. **Prepare the environment file**
  224. Copy the [example environment file](.env.example) to create your own `.env` file:
  225. ```shell
  226. cp .env.example .env
  227. ```
  228. Then optionally edit `.env` and set the variables that matter for your run:
  229. ```
  230. MCP_HOST=127.0.0.1 # (defaults to 0.0.0.0, use 127.0.0.1 for local dev)
  231. MCP_PORT=8007 # (defaults to 8000 when unset)
  232. MCP_ENV=local # environment name sent to Sentry (defaults to local when unset)
  233. DATAGOUV_API_ENV=prod # Allowed values: demo | prod (defaults to prod when unset)
  234. LOG_LEVEL=INFO # Python log level (default: INFO)
  235. ```
  236. Load the variables with your preferred method, e.g.:
  237. ```shell
  238. set -a && source .env && set +a
  239. ```
  240. 3. **Start the HTTP MCP server**
  241. ```shell
  242. uv run main.py
  243. ```
  244. ### 2. Connect your chatbot to the local MCP server
  245. Follow the steps in [Connect your chatbot to the MCP server](#-connect-your-chatbot-to-the-mcp-server) and simply swap the hosted URL for your local endpoint (default: `http://127.0.0.1:${MCP_PORT:-8000}/mcp`).
  246. ## 🚚 Transport support
  247. The MCP server is built using the [official Python SDK for MCP servers and clients](https://github.com/modelcontextprotocol/python-sdk) and uses the **Streamable HTTP transport only**.
  248. **STDIO and SSE are not supported**.
  249. ## 📋 Available Endpoints
  250. **Streamable HTTP transport (standards-compliant):**
  251. - `POST /mcp` - JSON-RPC messages (client → server)
  252. - `GET /health` - Health check endpoint: runs `search_datasets` in-process (no recursive HTTP call). Returns `{"status":"ok",...}` with HTTP 200 if healthy, or `{"status":"mcp_unavailable"}` with HTTP 503 if the MCP stack is not responding correctly.
  253. ## 🛠️ Available Tools
  254. The MCP server provides tools to interact with data.gouv.fr datasets and third-party APIs cataloged on the platform.
  255. **Note:** data.gouv.fr exposes these third-party APIs (e.g., Adresse API, Sirene API) over HTTP under the `dataservices` resource paths; that is separate from data.gouv.fr's own internal APIs (Main/Tabular/Metrics) that power this MCP server.
  256. ### Datasets (static data files)
  257. - **`search_datasets`** - Search for datasets by keywords. Returns datasets with metadata (title, description, organization, tags, resource count).
  258. Parameters: `query` (required), `page` (optional, default: 1), `page_size` (optional, default: 20, max: 100)
  259. - **`search_organizations`** - List or search publishing organizations on data.gouv.fr. Returns trimmed rows (id, name, slug, acronym, badges, metrics, URLs).
  260. Parameters: `query` (optional; AND-style keyword search; omit or leave empty to browse), `page` (optional, default: 1), `page_size` (optional, default: 20, max: 100), `sort` (optional; e.g. `datasets`, `-datasets`), `badge` (optional; e.g. `public-service`, `certified`, `association`, `company`, `local-authority`), `name` (optional, exact name filter), `business_number_id` (optional).
  261. - **`get_dataset_info`** - Get detailed information about a specific dataset (metadata, organization, tags, dates, license, etc.).
  262. Parameters: `dataset_id` (required)
  263. - **`list_dataset_resources`** - List all resources (files) in a dataset with their metadata (format, size, type, URL).
  264. Parameters: `dataset_id` (required)
  265. - **`get_resource_info`** - Get detailed information about a specific resource (format, size, MIME type, URL, dataset association, Tabular API availability).
  266. Parameters: `resource_id` (required)
  267. - **`query_resource_data`** - Query data from a specific resource via the Tabular API. Fetches rows from a resource to answer questions.
  268. Parameters: `resource_id` (required), `page` (optional, default: 1), `page_size` (optional, default: 20, max: 200)
  269. Note: Recommended workflow: 1) Use `search_datasets` to find the dataset, 2) Use `list_dataset_resources` to see available resources, 3) Use `query_resource_data` with default `page_size` (20) to preview data structure. For small datasets (<500 rows), increase `page_size` or paginate. For large datasets (>1000 rows), continue paginating or use `get_resource_info` to retrieve the raw file URL and fetch it directly. Works for CSV/XLS resources within Tabular API size limits (CSV ≤ 100 MB, XLSX ≤ 12.5 MB).
  270. ### Third-party APIs
  271. These tools use data.gouv.fr HTTP paths under `dataservices`; tool and parameter names match that API (`search_dataservices`, `dataservice_id`).
  272. - **`search_dataservices`** - Search for third-party APIs cataloged on data.gouv.fr by keywords. Returns entries with metadata (title, description, organization, base API URL, tags).
  273. Parameters: `query` (required), `page` (optional, default: 1), `page_size` (optional, default: 20, max: 100)
  274. - **`get_dataservice_info`** - Get detailed metadata for one third-party API (title, description, organization, base API URL, OpenAPI spec URL, license, dates, related datasets).
  275. Parameters: `dataservice_id` (required) — same as in the data.gouv.fr API and as the `id` from search results.
  276. - **`get_dataservice_openapi_spec`** - Fetch and summarize the OpenAPI/Swagger specification for a third-party API. Returns a concise overview of available endpoints with their parameters.
  277. Parameters: `dataservice_id` (required)
  278. Note: Recommended workflow: 1) Use `search_dataservices` to find the API, 2) Use `get_dataservice_info` for metadata and documentation URL, 3) Use `get_dataservice_openapi_spec` for endpoints and parameters, 4) Call the API using the `base_api_url` per the spec.
  279. ### Metrics
  280. - **`get_metrics`** - Get metrics (visits, downloads) for a dataset and/or a resource.
  281. Parameters: `dataset_id` (optional), `resource_id` (optional), `limit` (optional, default: 12, max: 100)
  282. Returns monthly statistics including visits and downloads, sorted by month in descending order (most recent first). At least one of `dataset_id` or `resource_id` must be provided. **Note:** This tool only works with the production environment (`DATAGOUV_API_ENV=prod`). The Metrics API does not have a demo/preprod environment.
  283. ## 🧪 Tests
  284. ### ✅ Automated Tests with pytest
  285. Run the tests with pytest (these cover helper modules; the MCP server wiring is best exercised via the MCP Inspector):
  286. ```shell
  287. # Run all tests
  288. uv run pytest
  289. # Run with verbose output
  290. uv run pytest -v
  291. # Run specific test file
  292. uv run pytest tests/test_tabular_api.py
  293. # Run with custom resource ID
  294. RESOURCE_ID=3b6b2281-b9d9-4959-ae9d-c2c166dff118 uv run pytest tests/test_tabular_api.py
  295. # Run with prod environment
  296. DATAGOUV_API_ENV=prod uv run pytest
  297. ```
  298. ### 🔥 Stress Tests
  299. Stress tests send many concurrent requests against a running MCP server. They require a running server and make real HTTP requests, so they are excluded from default `pytest` runs.
  300. ```shell
  301. # Start the server first, then in another terminal:
  302. uv run pytest -m stress
  303. ```
  304. Currently includes a test that mixes normal requests with abrupt client TCP disconnects, verifying the server stays healthy and keeps serving despite the disruption. It uses `MCP_PORT` (default: `8000`) to connect to the local server.
  305. ### 🩺 Run a Health Check from the CLI
  306. Runs `search_datasets` in-process to validate end-to-end stack health (tool layer + data.gouv.fr API). Requires network access to data.gouv.fr. Excluded from default `pytest` runs.
  307. ```shell
  308. uv run pytest -m health_check
  309. ```
  310. ### 🛠️ Local Tool Testing Script
  311. `scripts/call_tool.py` lets you call any MCP tool directly without manually managing the curl handshake. Requires a running server.
  312. ```shell
  313. # Start the server first, then in another terminal:
  314. python scripts/call_tool.py search_datasets '{"query": "IRVE"}'
  315. python scripts/call_tool.py get_resource_info '{"resource_id": "<id>"}'
  316. ```
  317. ### 🔍 Interactive Testing with MCP Inspector
  318. Use the official [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector) to interactively test the server tools and resources.
  319. Prerequisites:
  320. - Node.js with `npx` available
  321. Steps:
  322. 1. Start the MCP server (see above)
  323. 2. In another terminal, launch the inspector:
  324. ```shell
  325. npx @modelcontextprotocol/inspector --http-url "http://127.0.0.1:${MCP_PORT}/mcp"
  326. ```
  327. Adjust the URL if you exposed the server on another host/port.
  328. ## 🤝 Contributing
  329. We welcome contributions! To keep the project stable and reviews manageable, please observe these rules before submitting:
  330. - **Human review and accountability:** **Issues and pull requests** must not be raw, unreviewed AI output. You must have read, fully understood, and (for code) tested what you submit. **By opening an issue or a pull request, you certify you could explain and defend it in review without relying on an AI assistant.**
  331. - **Keep it small:** We strictly follow a **1 feature = 1 PR** workflow.
  332. - **Conventional commits:** Use the [Conventional Commits](https://www.conventionalcommits.org/) format for **git commit messages** and **PR titles** (e.g. `feat: add dataset search`, `fix: handle empty API response`). See the specification for allowed types, scopes, and breaking-change markers.
  333. We use a standard review-and-deploy process:
  334. 1. **Submit a PR:** Propose your changes via a Pull Request against the `main` branch.
  335. 2. **Continuous integration:** CI runs automatically on the pull request. **All required checks must pass** before the PR can be merged (tests, linting, formatting, and type checking). Run the same checks locally—tests per [Tests](#-tests), and lint/format/type via [Code linting and formatting](#-code-linting-and-formatting) or the [pre-commit hook](#-pre-commit-hooks)—to avoid surprise CI failures.
  336. 3. **Review:** All PRs must be reviewed and approved by a maintainer before merging.
  337. 4. **Deployment process:** Once merged into `main`, maintainers deploy changes periodically to **[pre-production](https://mcp.preprod.data.gouv.fr/)** for more tests and validation before wider release.
  338. ### 🧹 Code Linting and Formatting
  339. This project follows PEP 8 style guidelines using [Ruff](https://astral.sh/ruff/) for linting and formatting, and [ty](https://docs.astral.sh/ty/) for type checking.
  340. **Either running these commands manually or [installing the pre-commit hook](#-pre-commit-hooks) is required before submitting contributions.**
  341. ```shell
  342. # Lint (including import sorting) and format code
  343. uv run ruff check --fix && uv run ruff format
  344. # Type check (ty)
  345. uv run ty check
  346. ```
  347. ### 🔗 Pre-commit Hooks
  348. This repository uses a [pre-commit](https://pre-commit.com/) hook which lint and format code before each commit. Installing the pre-commit hook is strongly recommended so the checks run automatically.
  349. **Install pre-commit hooks:**
  350. ```shell
  351. uv run pre-commit install
  352. ```
  353. The pre-commit hook that automatically:
  354. - Check YAML syntax
  355. - Fix end-of-file issues
  356. - Remove trailing whitespace
  357. - Check for large files
  358. - Run Ruff linting and formatting
  359. ### 🏷️ Releases and versioning
  360. The release process uses the [`tag_version.sh`](tag_version.sh) script to create git tags, GitHub releases and update [CHANGELOG.md](CHANGELOG.md) automatically. Package version numbers are automatically derived from git tags using [setuptools_scm](https://github.com/pypa/setuptools_scm), so no manual version updates are needed in `pyproject.toml`.
  361. **Prerequisites**: [GitHub CLI](https://cli.github.com/) must be installed and authenticated, and you must be on the main branch with a clean working directory.
  362. ```shell
  363. # Create a new release
  364. ./tag_version.sh <version>
  365. # Example
  366. ./tag_version.sh 2.5.0
  367. # Dry run to see what would happen
  368. ./tag_version.sh 2.5.0 --dry-run
  369. ```
  370. The script automatically:
  371. - Extracts commits since the last tag and formats them for CHANGELOG.md
  372. - Identifies breaking changes (commits with `!:` in the subject)
  373. - Creates a git tag and pushes it to the remote repository
  374. - Creates a GitHub release with the changelog content
  375. ## 📄 License
  376. This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.