### Get Metrics Example

Source: https://github.com/datagouv/datagouv-mcp/blob/main/_autodocs/CONTENTS.txt

Retrieves usage statistics (visits, downloads) for datasets or resources. Use to track data popularity and usage.

```python
from datagouv_api_client.metrics import get_metrics

# Get metrics for dataset ID '5a0b4c1d88ee3811a7911111'
metrics = get_metrics(dataset_id='5a0b4c1d88ee3811a7911111')

# Print download count and visit count
print(f"Downloads: {metrics['downloads']}")
print(f"Visits: {metrics['visits']}")
```

--------------------------------

### Install Dependencies with uv

Source: https://github.com/datagouv/datagouv-mcp/blob/main/README.md

Install project dependencies using the 'uv sync' command. Ensure uv is installed first.

```shell
uv sync
```

--------------------------------

### Get Resource Info Example

Source: https://github.com/datagouv/datagouv-mcp/blob/main/_autodocs/CONTENTS.txt

Retrieves details about a specific resource, including metadata and Tabular API availability. Use to check resource properties.

```python
from datagouv_api_client.metadata import get_resource_info

# Get info for resource ID '6a0b4c1d88ee3811a7922222'
resource_info = get_resource_info('6a0b4c1d88ee3811a7922222')

# Print resource ID and format
print(f"Resource ID: {resource_info['id']}, Format: {resource_info['format']}")
```

--------------------------------

### Start Server with uv

Source: https://github.com/datagouv/datagouv-mcp/blob/main/_autodocs/configuration.md

Starts the MCP server using the uv application runner, typically after loading environment variables.

```bash
uv run main.py
```

--------------------------------

### Search Datasets Example

Source: https://github.com/datagouv/datagouv-mcp/blob/main/_autodocs/CONTENTS.txt

Demonstrates how to search for datasets using keywords. Supports pagination and sorting.

```python
from datagouv_api_client.search import search_datasets

# Search for datasets related to 'education' with pagination
results = search_datasets(keywords='education', page=1, page_size=25)

# Print dataset titles
for dataset in results['data']:
    print(dataset['title'])
```

--------------------------------

### Get Data Service Info Example

Source: https://github.com/datagouv/datagouv-mcp/blob/main/_autodocs/CONTENTS.txt

Retrieves detailed metadata for a third-party data service. Use to understand the service's purpose and capabilities.

```python
from datagouv_api_client.metadata import get_dataservice_info

# Get info for data service ID '7a0b4c1d88ee3811a7933333'
dataservice_info = get_dataservice_info('7a0b4c1d88ee3811a7933333')

# Print data service title and endpoint
print(f"Title: {dataservice_info['title']}")
print(f"Endpoint: {dataservice_info['endpoint']}")
```

--------------------------------

### Copy .env.example to .env

Source: https://github.com/datagouv/datagouv-mcp/blob/main/_autodocs/configuration.md

Copies the example environment file to a new file named .env, which can then be customized.

```bash
cp .env.example .env
```

--------------------------------

### Get Resource Metadata Example

Source: https://github.com/datagouv/datagouv-mcp/blob/main/_autodocs/api-reference/datagouv-api-client.md

Fetch minimal metadata for a resource, including its ID, title, description, and associated dataset ID. This is useful for quick resource identification.

```python
resource_metadata = await datagouv_api_client.get_resource_metadata(
    resource_id="f0e1d2c3-b4a5-6789-0123-456789abcdef"
)
```

--------------------------------

### Example Log Entry for Tool Call

Source: https://github.com/datagouv/datagouv-mcp/blob/main/_autodocs/endpoints.md

This is an example log entry showing a tool call with its parameters. It is logged at INFO level, or DEBUG level for detailed parameters.

```text
2024-02-15 10:30:45 | INFO | mcp.tools | Tool called: search_datasets | kwargs={'query': 'immobilier', 'page': 1, 'page_size': 20}
```

--------------------------------

### Create and Edit Environment File

Source: https://github.com/datagouv/datagouv-mcp/blob/main/README.md

Copy the example environment file to create a local configuration and then edit it to set desired variables.

```shell
cp .env.example .env
```

```shell
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)
```

--------------------------------

### Install Pre-commit Hooks

Source: https://github.com/datagouv/datagouv-mcp/blob/main/README.md

Installs the pre-commit hook which automatically lints and formats code before each commit, ensuring consistency and catching common issues.

```shell
uv run pre-commit install
```

--------------------------------

### Combine Filter and Sort

Source: https://github.com/datagouv/datagouv-mcp/blob/main/_autodocs/api-reference/tabular-api-client.md

Example demonstrating how to apply both a filter and a sorting order to the query parameters.

```python
params = {
    "region__exact": "Île-de-France",
    "prix__sort": "desc"
}
```

--------------------------------

### Get Dataset Info Example

Source: https://github.com/datagouv/datagouv-mcp/blob/main/_autodocs/CONTENTS.txt

Retrieves detailed metadata for a specific dataset using its ID. Essential for understanding dataset contents.

```python
from datagouv_api_client.metadata import get_dataset_info

# Get information for a dataset with ID '5a0b4c1d88ee3811a7911111'
dataset_info = get_dataset_info('5a0b4c1d88ee3811a791111')

# Print dataset title and description
print(f"Title: {dataset_info['title']}")
print(f"Description: {dataset_info['description']}")
```

--------------------------------

### Integration Example from datagouv_api_client

Source: https://github.com/datagouv/datagouv-mcp/blob/main/_autodocs/api-reference/env-config.md

Shows how the env_config module is used internally by other API client modules, specifically datagouv_api_client.

```python
base_url = env_config.get_base_url("datagouv_api")
url = f"{base_url}1/datasets/{dataset_id}/"
```

--------------------------------

### Get Resource Details Example

Source: https://github.com/datagouv/datagouv-mcp/blob/main/_autodocs/api-reference/datagouv-api-client.md

Fetch the complete payload for a specific resource using its ID. This retrieves all metadata associated with the resource and its parent dataset.

```python
resource_details = await datagouv_api_client.get_resource_details(
    resource_id="f0e1d2c3-b4a5-6789-0123-456789abcdef"
)
```

--------------------------------

### Get Dataset Metadata Example

Source: https://github.com/datagouv/datagouv-mcp/blob/main/_autodocs/api-reference/datagouv-api-client.md

Fetch minimal metadata for a dataset, including its ID, title, and descriptions. This is useful for quick lookups without retrieving the full dataset object.

```python
dataset_metadata = await datagouv_api_client.get_dataset_metadata(
    dataset_id="a0b1c2d3-e4f5-6789-0123-456789abcdef"
)
```

--------------------------------

### Get Dataset Details Example

Source: https://github.com/datagouv/datagouv-mcp/blob/main/_autodocs/api-reference/datagouv-api-client.md

Fetch the complete payload for a specific dataset using its ID. This retrieves all metadata, resources, and related information.

```python
dataset_details = await datagouv_api_client.get_dataset_details(
    dataset_id="a0b1c2d3-e4f5-6789-0123-456789abcdef"
)
```

--------------------------------

### List Dataset Resources Example

Source: https://github.com/datagouv/datagouv-mcp/blob/main/_autodocs/CONTENTS.txt

Lists all files (resources) within a dataset, including their metadata. Useful for exploring dataset components.

```python
from datagouv_api_client.metadata import list_dataset_resources

# List resources for dataset ID '5a0b4c1d88ee3811a791111'
resources = list_dataset_resources('5a0b4c1d88ee3811a791111')

# Print resource filenames and formats
for resource in resources['data']:
    print(f"Filename: {resource['filename']}, Format: {resource['format']}")
```

--------------------------------

### Multiple Filters and Sort

Source: https://github.com/datagouv/datagouv-mcp/blob/main/_autodocs/api-reference/tabular-api-client.md

Example showing how to apply multiple filters along with a sorting order to refine the data retrieval.

```python
params = {
    "region__exact": "Île-de-France",
    "prix__greater": "5000",
    "prix__sort": "desc"
}
```

--------------------------------

### Fetch Resource Data Example

Source: https://github.com/datagouv/datagouv-mcp/blob/main/_autodocs/api-reference/tabular-api-client.md

Fetches data from a specified resource using pagination, filtering, and sorting parameters.

```python
result = await tabular_api_client.fetch_resource_data(
    "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    page=1,
    page_size=50,
    params={
        "region__exact": "Île-de-France",
        "prix__sort": "desc"
    }
)
```

--------------------------------

### MCP Client Request Example

Source: https://github.com/datagouv/datagouv-mcp/blob/main/_autodocs/endpoints.md

Example of a JSON-RPC 2.0 request to the /mcp endpoint for calling the 'search_datasets' tool. This format is used for all MCP client communications.

```json
{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "tools/call",
  "params": {
    "name": "search_datasets",
    "arguments": {
      "query": "immobilier",
      "page": 1,
      "page_size": 10
    }
  }
}
```

--------------------------------

### Get Data Service OpenAPI Spec Example

Source: https://github.com/datagouv/datagouv-mcp/blob/main/_autodocs/CONTENTS.txt

Fetches and summarizes the OpenAPI specification for a data service. Useful for understanding API structure and available endpoints.

```python
from datagouv_api_client.metadata import get_dataservice_openapi_spec

# Get OpenAPI spec for data service ID '7a0b4c1d88ee3811a7933333'
spec_summary = get_dataservice_openapi_spec('7a0b4c1d88ee3811a7933333')

# Print summary information
print(f"API Title: {spec_summary['info']['title']}")
print(f"Version: {spec_summary['info']['version']}")
```

--------------------------------

### Search Data Services Example

Source: https://github.com/datagouv/datagouv-mcp/blob/main/_autodocs/CONTENTS.txt

Searches for registered third-party APIs. Useful for discovering external data sources.

```python
from datagouv_api_client.search import search_dataservices

# Search for data services related to 'transport'
results = search_dataservices(keywords='transport')

# Print data service titles
for service in results['data']:
    print(service['title'])
```

--------------------------------

### Search Datasets Example

Source: https://github.com/datagouv/datagouv-mcp/blob/main/_autodocs/api-reference/datagouv-api-client.md

Search for datasets using keywords, specifying pagination and result size. Ensure the 'immobilier' query is relevant to your search needs.

```python
result = await datagouv_api_client.search_datasets(
    "immobilier",
    page=1,
    page_size=10
)
```

--------------------------------

### Enable Debug Logging

Source: https://github.com/datagouv/datagouv-mcp/blob/main/_autodocs/configuration.md

Starts the MCP server with debug logging enabled by setting the LOG_LEVEL environment variable.

```bash
LOG_LEVEL=DEBUG uv run main.py
```

--------------------------------

### Clone datagouv-mcp Repository

Source: https://github.com/datagouv/datagouv-mcp/blob/main/README.md

Clone the datagouv-mcp repository and navigate into the directory. Docker is required for the recommended setup.

```shell
git clone git@github.com:datagouv/datagouv-mcp.git
cd datagouv-mcp
```

--------------------------------

### Loading and Overriding Environment Variables

Source: https://github.com/datagouv/datagouv-mcp/blob/main/_autodocs/configuration.md

Example of how to load default values from a .env file and then override specific variables using shell commands.

```bash
# Start with .env values, then override with env vars
source .env  # Load defaults from .env
MCP_PORT=9000 uv run main.py  # Override MCP_PORT
```

--------------------------------

### Search Data Services Example

Source: https://github.com/datagouv/datagouv-mcp/blob/main/_autodocs/api-reference/datagouv-api-client.md

Search for third-party APIs using a query string. This function requires a query to be provided.

```python
result = await datagouv_api_client.search_dataservices(
    query="open-data",
    page=1,
    page_size=5
)
```

--------------------------------

### Launch MCP Inspector

Source: https://github.com/datagouv/datagouv-mcp/blob/main/README.md

Starts the MCP Inspector for interactive testing of server tools and resources. Requires Node.js with npx and a running MCP server.

```shell
npx @modelcontextprotocol/inspector --http-url "http://127.0.0.1:${MCP_PORT}/mcp"
```

--------------------------------

### Search Organizations Example

Source: https://github.com/datagouv/datagouv-mcp/blob/main/_autodocs/CONTENTS.txt

Finds publishing organizations by keywords and filters. Useful for identifying data providers.

```python
from datagouv_api_client.search import search_organizations

# Search for organizations with 'ministere' in their name
results = search_organizations(keywords='ministere')

# Print organization names
for org in results['data']:
    print(org['name'])
```

--------------------------------

### Docker Deployment

Source: https://github.com/datagouv/datagouv-mcp/blob/main/_autodocs/README.md

Command to start the service using Docker Compose, which automatically sets up dependencies and runs the service on port 8000.

```bash
docker compose up -d
```

--------------------------------

### MCP Client Success Response Example

Source: https://github.com/datagouv/datagouv-mcp/blob/main/_autodocs/endpoints.md

Example of a successful JSON-RPC 2.0 response from the /mcp endpoint after a tool call. The 'result' field contains the output, typically as structured text.

```json
{
  "jsonrpc": "2.0",
  "id": "1",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Found 42 dataset(s) for query: 'immobilier'\n..."
      }
    ]
  }
}
```

--------------------------------

### Run Docker Compose with Sentry Enabled

Source: https://github.com/datagouv/datagouv-mcp/blob/main/_autodocs/configuration.md

Starts the MCP server using Docker Compose with Sentry error tracking enabled by providing a Sentry DSN.

```bash
SENTRY_DSN=https://key@sentry.io/project-id docker compose up -d
```

--------------------------------

### Query Resource Data Example

Source: https://github.com/datagouv/datagouv-mcp/blob/main/_autodocs/CONTENTS.txt

Queries tabular data (CSV/XLSX) from a resource with filtering and sorting. Use for data extraction and analysis.

```python
from tabular_api_client.query import query_resource_data

# Query data from resource ID '6a0b4c1d88ee3811a7922222'
# Filter by 'year' column and sort by 'value' descending
data = query_resource_data(
    resource_id='6a0b4c1d88ee3811a7922222',
    filters="year=2023",
    sort="value DESC"
)

# Print first 5 rows
for row in data[:5]:
    print(row)
```

--------------------------------

### Call API Directly

Source: https://github.com/datagouv/datagouv-mcp/blob/main/_autodocs/README.md

Demonstrates how to make a direct HTTP GET request to the search endpoint of the API using httpx.

```python
import httpx
async with httpx.AsyncClient() as client:
    r = await client.get("https://api-adresse.data.gouv.fr/search",
        params={"q": "Paris", "limit": 5})
```

--------------------------------

### Get Dataset Metrics

Source: https://github.com/datagouv/datagouv-mcp/blob/main/_autodocs/api-reference/metrics-api-client.md

Fetch monthly visit metrics for a specific dataset. Results are sorted in descending order by month.

```python
metrics = await metrics_api_client.get_metrics(
    "datasets",
    "5e8c3b2a1f4d9e7c6b1a2f3e",
    limit=12,
    sort_order="desc"
)
for entry in metrics:
    print(f"{entry['metric_month']}: {entry['monthly_visit']} visits")
```

--------------------------------

### Graceful Error Handling Example

Source: https://github.com/datagouv/datagouv-mcp/blob/main/_autodocs/api-reference/crawler-api-client.md

Demonstrates how to handle potential exceptions when fetching resource exceptions. The module internally manages fallback to cached or empty data.

```python
try:
    exceptions = await crawler_api_client.fetch_resource_exceptions()
except Exception:
    # Module handles this internally and returns cached/empty data
    pass
```

--------------------------------

### Filter and Sort Resource Data

Source: https://github.com/datagouv/datagouv-mcp/blob/main/_autodocs/api-reference/query-resource-data.md

This example demonstrates how to filter data by a specific column and value, and sort the results in descending order by another column. It also specifies the page size.

```python
result = await client.call_tool(
    "query_resource_data",
    {
        "resource_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "page": 1,
        "page_size": 50,
        "filter_column": "region",
        "filter_value": "Île-de-France",
        "filter_operator": "exact",
        "sort_column": "prix",
        "sort_direction": "desc"
    }
)
```

--------------------------------

### Manual Deployment with uv

Source: https://github.com/datagouv/datagouv-mcp/blob/main/_autodocs/README.md

Steps to deploy the service manually using uv, including synchronizing dependencies, sourcing environment variables, and running the main application script.

```bash
uv sync
source .env  # Load configuration
uv run main.py
```

--------------------------------

### Kubernetes Health Check Configuration

Source: https://github.com/datagouv/datagouv-mcp/blob/main/_autodocs/endpoints.md

Example Kubernetes probe configurations for liveness and readiness checks using the /health endpoint. These define how Kubernetes monitors the application's health.

```yaml
livenessProbe:
  httpGet:
    path: /health
    port: 8000
  initialDelaySeconds: 10
  periodSeconds: 30
  timeoutSeconds: 5

readinessProbe:
  httpGet:
    path: /health
    port: 8000
  initialDelaySeconds: 5
  periodSeconds: 10
  timeoutSeconds: 5
```

--------------------------------

### Search Organizations Example

Source: https://github.com/datagouv/datagouv-mcp/blob/main/_autodocs/api-reference/datagouv-api-client.md

Search for organizations by keywords or filter by specific criteria like badges or business numbers. The query parameter is optional for listing all organizations.

```python
result = await datagouv_api_client.search_organizations(
    query="",
    page=1,
    page_size=10,
    badge="public-service"
)
```

--------------------------------

### Handle Resource Not Found Errors

Source: https://github.com/datagouv/datagouv-mcp/blob/main/_autodocs/errors.md

Guide users to find the correct resource ID when a 'ResourceNotAvailableError' (404) is encountered. This involves suggesting a workflow using search_datasets and list_dataset_resources.

```python
try:
    result = await tabular_api_client.fetch_resource_data(resource_id)
except tabular_api_client.ResourceNotAvailableError:
    # Guide user to find the correct resource
    print("Please use search_datasets → list_dataset_resources → query_resource_data")
```

--------------------------------

### Create New Release Tag

Source: https://github.com/datagouv/datagouv-mcp/blob/main/README.md

Uses the tag_version.sh script to create git tags, GitHub releases, and update CHANGELOG.md. Requires GitHub CLI installed and authenticated, and a clean main branch.

```shell
# Create a new release
./tag_version.sh <version>

# Example
./tag_version.sh 2.5.0

# Dry run to see what would happen
./tag_version.sh 2.5.0 --dry-run
```

--------------------------------

### Get Dataset Info

Source: https://github.com/datagouv/datagouv-mcp/blob/main/_autodocs/CONTENTS.txt

Get detailed metadata about a specific dataset.

```APIDOC
## POST /mcp

### Description
This endpoint serves as a JSON-RPC interface for invoking various MCP tools, including retrieving detailed dataset information.

### Method
POST

### Endpoint
/mcp

### Parameters
#### Request Body
- **method** (string) - Required - The name of the method to invoke (e.g., "get_dataset_info").
- **params** (object) - Optional - Parameters for the invoked method.

### Request Example
```json
{
  "method": "get_dataset_info",
  "params": {
    "dataset_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef"
  }
}
```

### Response
#### Success Response (200)
- **result** (object) - The detailed metadata of the specified dataset.

#### Response Example
```json
{
  "jsonrpc": "2.0",
  "id": "some-id",
  "result": {
    "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "title": "Detailed Dataset Title",
    "description": "Comprehensive description of the dataset.",
    "organization": {
      "id": "org-id-1",
      "name": "Organization Name"
    }
  }
}
```
```

--------------------------------

### Get Metrics

Source: https://github.com/datagouv/datagouv-mcp/blob/main/_autodocs/CONTENTS.txt

Get usage metrics (visits, downloads) for datasets or resources.

```APIDOC
## POST /mcp

### Description
This endpoint serves as a JSON-RPC interface for invoking various MCP tools, including retrieving usage metrics.

### Method
POST

### Endpoint
/mcp

### Parameters
#### Request Body
- **method** (string) - Required - The name of the method to invoke (e.g., "get_metrics").
- **params** (object) - Optional - Parameters for the invoked method.

### Request Example
```json
{
  "method": "get_metrics",
  "params": {
    "resource_id": "f0e9d8c7-b6a5-4321-0987-fedcba098765",
    "dataset_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "start_date": "2023-01-01",
    "end_date": "2023-12-31"
  }
}
```

### Response
#### Success Response (200)
- **result** (object) - The usage metrics for the specified dataset or resource.

#### Response Example
```json
{
  "jsonrpc": "2.0",
  "id": "some-id",
  "result": {
    "dataset_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "resource_id": "f0e9d8c7-b6a5-4321-0987-fedcba098765",
    "visits": 1500,
    "downloads": 300
  }
}
```
```

--------------------------------

### Get Resource Info

Source: https://github.com/datagouv/datagouv-mcp/blob/main/_autodocs/CONTENTS.txt

Get resource details and check Tabular API availability.

```APIDOC
## POST /mcp

### Description
This endpoint serves as a JSON-RPC interface for invoking various MCP tools, including retrieving resource details.

### Method
POST

### Endpoint
/mcp

### Parameters
#### Request Body
- **method** (string) - Required - The name of the method to invoke (e.g., "get_resource_info").
- **params** (object) - Optional - Parameters for the invoked method.

### Request Example
```json
{
  "method": "get_resource_info",
  "params": {
    "resource_id": "f0e9d8c7-b6a5-4321-0987-fedcba098765"
  }
}
```

### Response
#### Success Response (200)
- **result** (object) - The detailed information about the specified resource.

#### Response Example
```json
{
  "jsonrpc": "2.0",
  "id": "some-id",
  "result": {
    "id": "f0e9d8c7-b6a5-4321-0987-fedcba098765",
    "title": "Resource Title",
    "format": "XLSX",
    "url": "http://example.com/resource.xlsx",
    "is_tabular": true
  }
}
```
```

--------------------------------

### Get Data Service Info

Source: https://github.com/datagouv/datagouv-mcp/blob/main/_autodocs/CONTENTS.txt

Get detailed metadata about a third-party API (data service).

```APIDOC
## POST /mcp

### Description
This endpoint serves as a JSON-RPC interface for invoking various MCP tools, including retrieving detailed data service information.

### Method
POST

### Endpoint
/mcp

### Parameters
#### Request Body
- **method** (string) - Required - The name of the method to invoke (e.g., "get_dataservice_info").
- **params** (object) - Optional - Parameters for the invoked method.

### Request Example
```json
{
  "method": "get_dataservice_info",
  "params": {
    "dataservice_id": "dataservice-id-1"
  }
}
```

### Response
#### Success Response (200)
- **result** (object) - The detailed metadata of the specified data service.

#### Response Example
```json
{
  "jsonrpc": "2.0",
  "id": "some-id",
  "result": {
    "id": "dataservice-id-1",
    "title": "Data Service Title",
    "description": "Description of the third-party API.",
    "url": "http://example.com/api"
  }
}
```
```

--------------------------------

### Development Server with Debug Logging

Source: https://github.com/datagouv/datagouv-mcp/blob/main/_autodocs/endpoints.md

Run the development server on localhost with debug logging enabled and specify MCP host and port. Access the service at the provided URLs.

```bash
LOG_LEVEL=DEBUG MCP_HOST=127.0.0.1 MCP_PORT=8007 uv run main.py
```

--------------------------------

### Run ASGI Application

Source: https://github.com/datagouv/datagouv-mcp/blob/main/_autodocs/endpoints.md

Use this command to run the ASGI application with uvicorn. Ensure the entry point 'main:asgi_app' is correctly specified.

```bash
uvicorn main:asgi_app --host 0.0.0.0 --port 8000
```

--------------------------------

### Crawler API Client - Get Resource Size

Source: https://github.com/datagouv/datagouv-mcp/blob/main/_autodocs/CONTENTS.txt

Client function to get resource size, handling potential exceptions. Use for managing large data files.

```python
from crawler_api_client.crawler_api_client import CrawlerApiClient

client = CrawlerApiClient()
size = client.get_resource_size('6a0b4c1d88ee3811a7922222')
print(f"Resource size: {size} bytes")
```

--------------------------------

### MCP Client Error Response Example

Source: https://github.com/datagouv/datagouv-mcp/blob/main/_autodocs/endpoints.md

Example of a JSON-RPC 2.0 error response from the /mcp endpoint. This indicates an issue with the request, such as invalid parameters or a malformed request.

```json
{
  "jsonrpc": "2.0",
  "id": "1",
  "error": {
    "code": -32600,
    "message": "Invalid Request"
  }
}
```

--------------------------------

### Override Environment with DATAGOUV_API_ENV

Source: https://github.com/datagouv/datagouv-mcp/blob/main/_autodocs/api-reference/env-config.md

Shows how to run the application with a specific environment (e.g., demo) by setting the DATAGOUV_API_ENV environment variable.

```bash
# Run with demo environment
DATAGOUV_API_ENV=demo uv run main.py
```

```python
env_config.get_base_url("datagouv_api")
# Returns: "https://demo.data.gouv.fr/api/"
```

--------------------------------

### Filter by Substring

Source: https://github.com/datagouv/datagouv-mcp/blob/main/_autodocs/api-reference/tabular-api-client.md

Example of filtering data where a specific column contains a given substring.

```python
params = {"ville__contains": "Paris"}
```

--------------------------------

### Get Data Service OpenAPI Spec

Source: https://github.com/datagouv/datagouv-mcp/blob/main/_autodocs/CONTENTS.txt

Fetch and summarize OpenAPI specifications for a data service.

```APIDOC
## POST /mcp

### Description
This endpoint serves as a JSON-RPC interface for invoking various MCP tools, including fetching and summarizing OpenAPI specifications for data services.

### Method
POST

### Endpoint
/mcp

### Parameters
#### Request Body
- **method** (string) - Required - The name of the method to invoke (e.g., "get_dataservice_openapi_spec").
- **params** (object) - Optional - Parameters for the invoked method.

### Request Example
```json
{
  "method": "get_dataservice_openapi_spec",
  "params": {
    "dataservice_id": "dataservice-id-1"
  }
}
```

### Response
#### Success Response (200)
- **result** (object) - A summary or the full OpenAPI specification of the data service.

#### Response Example
```json
{
  "jsonrpc": "2.0",
  "id": "some-id",
  "result": {
    "openapi": "3.0.0",
    "info": {
      "title": "Data Service API",
      "version": "1.0.0"
    },
    "paths": {
      "/items": {
        "get": {
          "summary": "List items"
        }
      }
    }
  }
}
```
```

--------------------------------

### Production Environment Variables

Source: https://github.com/datagouv/datagouv-mcp/blob/main/_autodocs/configuration.md

Configuration for production deployment. Listens on all interfaces (0.0.0.0), uses info-level logging, and enables Sentry with sampling.

```bash
# Environment for production deployment
MCP_HOST=0.0.0.0
MCP_PORT=8000
MCP_ENV=prod
DATAGOUV_API_ENV=prod
LOG_LEVEL=INFO
SENTRY_DSN=https://key@sentry.io/project-id
SENTRY_SAMPLE_RATE=0.1
```

--------------------------------

### Filter by Exact Value

Source: https://github.com/datagouv/datagouv-mcp/blob/main/_autodocs/api-reference/tabular-api-client.md

Example of filtering data where a specific column exactly matches a given value.

```python
params = {"region__exact": "Paris"}
```

--------------------------------

### Environment Configuration - API Endpoint Selection

Source: https://github.com/datagouv/datagouv-mcp/blob/main/_autodocs/CONTENTS.txt

Demonstrates how to configure the MCP client to use different API endpoints based on environment variables. Use for managing deployment environments.

```python
from env_config.env_config import EnvConfig

# Load configuration (reads MCP_HOST, DATAGOUV_API_ENV, etc. from environment)
config = EnvConfig()

print(f"Using DataGouv API endpoint: {config.datagouv_api_endpoint}")
print(f"Using MCP host: {config.mcp_host}")
```

--------------------------------

### Configure AnythingLLM MCP Servers

Source: https://github.com/datagouv/datagouv-mcp/blob/main/README.md

Add this JSON configuration to your AnythingLLM storage plugins directory to connect to the datagouv MCP server. Ensure you locate the correct file path for your operating system.

```json
{
  "mcpServers": {
    "datagouv": {
      "type": "streamable",
      "url": "https://mcp.data.gouv.fr/mcp"
    }
  }
}
```

--------------------------------

### Health Check Endpoint

Source: https://github.com/datagouv/datagouv-mcp/blob/main/_autodocs/CONTENTS.txt

Example of calling the health check endpoint. Use to verify the MCP service is running.

```python
import requests

url = "http://localhost:8000/health"

response = requests.get(url)
print(f"Health status: {response.status_code}")
print(response.json())
```

--------------------------------

### Run Docker Compose with Custom Environment Variables

Source: https://github.com/datagouv/datagouv-mcp/blob/main/_autodocs/configuration.md

Starts the MCP server using Docker Compose, overriding default settings with custom environment variables for port, data source environment, and log level.

```bash
MCP_PORT=8007 DATAGOUV_API_ENV=demo LOG_LEVEL=DEBUG docker compose up -d
```

--------------------------------

### Preview First 20 Rows of Resource Data

Source: https://github.com/datagouv/datagouv-mcp/blob/main/_autodocs/api-reference/query-resource-data.md

Use this snippet to quickly preview the first 20 rows of a resource. It sets the resource ID, page number, and page size.

```python
result = await client.call_tool(
    "query_resource_data",
    {
        "resource_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "page": 1,
        "page_size": 20
    }
)
```

--------------------------------

### Get Metrics as CSV

Source: https://github.com/datagouv/datagouv-mcp/blob/main/_autodocs/api-reference/metrics-api-client.md

Fetch metrics for a specific dataset in CSV format. This is useful for bulk data retrieval and analysis.

```python
csv_data = await metrics_api_client.get_metrics_csv(
    "datasets",
    "5e8c3b2a1f4d9e7c6b1a2f3e"
)
print(csv_data)
```

--------------------------------

### Import env_config Module

Source: https://github.com/datagouv/datagouv-mcp/blob/main/_autodocs/api-reference/env-config.md

Import the necessary env_config module from the helpers package.

```python
from helpers import env_config
```

--------------------------------

### Run stress tests with pytest

Source: https://github.com/datagouv/datagouv-mcp/blob/main/README.md

Execute stress tests against a running MCP server. This requires the server to be started first.

```shell
uv run pytest -m stress
```

--------------------------------

### Find and Analyze a Dataset Workflow

Source: https://github.com/datagouv/datagouv-mcp/blob/main/_autodocs/README.md

This Python code demonstrates a common workflow for finding a dataset, listing its resources, and querying tabular data. It uses the MCP client to call `search_datasets`, `list_dataset_resources`, and `query_resource_data` tools.

```python
# 1. Find the dataset
result = await client.call_tool("search_datasets", {"query": "immobilier"})
# → Found: "Prix de l'immobilier par région" (ID: 5e8c3b2a...)

# 2. List its resources
result = await client.call_tool("list_dataset_resources", 
    {"dataset_id": "5e8c3b2a1f4d9e7c6b1a2f3e"})
# → Files: CSV (2.5 MB), XLSX (5.3 MB)

# 3. Query the CSV data
result = await client.call_tool("query_resource_data", {
    "resource_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "filter_column": "region",
    "filter_value": "Île-de-France",
    "sort_column": "prix",
    "sort_direction": "desc"
})
# → Data table with filtered and sorted rows
```

--------------------------------

### Kiro CLI/IDE MCP Server Configuration

Source: https://github.com/datagouv/datagouv-mcp/blob/main/README.md

Configure the datagouv MCP server for Kiro CLI or Kiro IDE by adding it to the appropriate `mcp.json` settings file.

```json
{
  "mcpServers": {
    "datagouv": {
      "url": "https://mcp.data.gouv.fr/mcp"
    }
  }
}
```

--------------------------------

### Basic Usage of get_base_url

Source: https://github.com/datagouv/datagouv-mcp/blob/main/_autodocs/api-reference/env-config.md

Demonstrates the basic usage of get_base_url to obtain an API URL for the currently configured environment.

```python
from helpers import env_config

# Get API URL for the configured environment
url = env_config.get_base_url("datagouv_api")
# Constructs dataset endpoint like: f"{url}1/datasets/..."
```

--------------------------------

### Check Server Health

Source: https://github.com/datagouv/datagouv-mcp/blob/main/_autodocs/README.md

Verify the health status of the server by sending a GET request to the /health endpoint and parsing the JSON response.

```bash
curl http://localhost:8000/health | jq
```

--------------------------------

### Efficient Session Management with Tabular API Client

Source: https://github.com/datagouv/datagouv-mcp/blob/main/_autodocs/api-reference/tabular-api-client.md

Demonstrates how to reuse an httpx.AsyncClient session for multiple calls to fetch resource profile and data. This improves efficiency by reusing the same underlying connection.

```python
async with httpx.AsyncClient() as session:
    # Multiple calls reuse the same connection
    profile = await tabular_api_client.fetch_resource_profile(
        resource_id,
        session=session
    )
    data = await tabular_api_client.fetch_resource_data(
        resource_id,
        page=1,
        page_size=20,
        session=session
    )
```

--------------------------------

### JSON-RPC Tool Invocation

Source: https://github.com/datagouv/datagouv-mcp/blob/main/_autodocs/CONTENTS.txt

Example of invoking an MCP tool via its JSON-RPC endpoint. Use for programmatic interaction with MCP tools.

```python
import requests
import json

url = "http://localhost:8000/mcp"
headers = {"Content-Type": "application/json"}

# Example: Invoke search_datasets tool
payload = {
    "jsonrpc": "2.0",
    "method": "search_datasets",
    "params": {"keywords": "transport"},
    "id": 1
}

response = requests.post(url, headers=headers, data=json.dumps(payload))
result = response.json()
print(result)
```

--------------------------------

### Tabular API Client - Custom Exception

Source: https://github.com/datagouv/datagouv-mcp/blob/main/_autodocs/CONTENTS.txt

Example of a custom exception for Tabular API requests. Use for robust error handling.

```python
from tabular_api_client.exceptions import TabularApiRequestError

try:
    # Attempt to query data
    pass
except TabularApiRequestError as e:
    print(f"Error querying Tabular API: {e}")
```

--------------------------------

### Discover and Use a Third-party API Workflow

Source: https://github.com/datagouv/datagouv-mcp/blob/main/_autodocs/README.md

This Python code illustrates how to discover a third-party API, retrieve its details, and fetch its OpenAPI specification. It utilizes the MCP client to call `search_dataservices` and `get_dataservice_info`.

```python
# 1. Find the API
result = await client.call_tool("search_dataservices", {"query": "adresse"})
# → Found: "Adresse API" (ID: adresse-api)

# 2. Get API details
result = await client.call_tool("get_dataservice_info", 
    {"dataservice_id": "adresse-api"})
```

--------------------------------

### Metrics API Client - Get Metrics

Source: https://github.com/datagouv/datagouv-mcp/blob/main/_autodocs/CONTENTS.txt

Client function to retrieve usage metrics for datasets or resources. Use for monitoring data popularity.

```python
from metrics_api_client.metrics_api_client import MetricsApiClient

client = MetricsApiClient()
metrics = client.get_metrics(resource_id='6a0b4c1d88ee3811a7922222')
print(metrics)
```

--------------------------------

### Local Development Environment Variables

Source: https://github.com/datagouv/datagouv-mcp/blob/main/_autodocs/configuration.md

Configuration for local development. Binds to 127.0.0.1 for security, enables debug logging, and disables Sentry.

```env
MCP_HOST=127.0.0.1
MCP_PORT=8007
MCP_ENV=local
DATAGOUV_API_ENV=prod
LOG_LEVEL=DEBUG
SENTRY_DSN=
```

--------------------------------

### Get Metrics for a Resource

Source: https://github.com/datagouv/datagouv-mcp/blob/main/_autodocs/api-reference/get-metrics.md

Retrieves monthly usage metrics for a specific resource. Specify the resource ID and an optional limit for the number of months.

```python
result = await client.call_tool(
    "get_metrics",
    {
        "resource_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "limit": 6
    }
)
```

--------------------------------

### Environment Variable Lookup for DATAGOUV_API_ENV

Source: https://github.com/datagouv/datagouv-mcp/blob/main/_autodocs/api-reference/env-config.md

Demonstrates how the DATAGOUV_API_ENV environment variable is read, with a default to 'prod' and handling for invalid values.

```python
import os

env_name = os.getenv("DATAGOUV_API_ENV", "prod").strip().lower()
# If env_name not in ["prod", "demo"], defaults to "prod"
```