# Utforska Data MCP Server

MCP server package for discovering datasets, fetching filtered data, creating deep links, and generating reports from Utforska Data.

Package: `utforska-data-mcp`

## Tooling Surface

- `discover_datasets`
- `get_dataset_details`
- `fetch_data`
- `build_export_link`
- `build_session_link`
- `generate_report`
- `build_session_export_link`

`discover_datasets` and `generate_report` also support Apps SDK output templates (widget resources).

## Run Modes

### 1) MCP stdio (client launches via `uvx`)

```json
{
  "mcpServers": {
    "utforska-data": {
      "command": "uvx",
      "args": ["utforska-data-mcp"]
    }
  }
}
```

### 2) Streamable HTTP (standalone)

```bash
cd backend/mcp-server
uv run utforska-data-mcp-http
```

Defaults:
- MCP endpoint: `http://localhost:8080/mcp/`
- Health: `http://localhost:8080/health`

### 3) Embedded in main API server

`backend/api_server.py` mounts MCP on `/mcp`.

## Configuration

- `MCP_BACKEND_URL` (default: `https://utforskadata.se`)
- `MCP_APP_URL` (default: `https://utforskadata.se`)
- `MCP_SESSION_API_URL` (optional override for session create/load API)
- `MCP_DEFAULT_LANG` (`sv` or `en`, default `sv`)

HTTP mode options:
- `MCP_HTTP_HOST` (default `0.0.0.0`)
- `MCP_HTTP_PORT` (default `8080`)
- `MCP_HTTP_PATH` (default `/mcp`)
- `MCP_HTTP_STATELESS` (default `true`)
- `MCP_HTTP_JSON_RESPONSE` (default `false`)

## Local Development

```bash
cd backend/mcp-server
pip install -e .
```

or run package scripts directly via `uv run`.

## Switching from a Kolada-only MCP Server

If someone already has a Kolada MCP server, migration can be minimal if they keep the same interaction pattern.

### Fastest path (endpoint swap)

1. Keep their MCP client/tooling layer.
2. Point backend calls to Utforska endpoints instead:
   - discovery: `POST /api/ai/discover`
   - details: `GET /api/v2/datasets/{id}`
   - data: `GET /api/v2/datasets/{id}/data`
   - export: `GET /api/v2/datasets/{id}/export`
3. Restrict to Kolada when needed via source filters (`sources: ["kolada"]`).
4. Keep existing response contract in their MCP wrapper if they need backward compatibility.

### If they adopt this MCP package directly

- Replace MCP server command with `uvx utforska-data-mcp`.
- Optionally set:
  - `MCP_BACKEND_URL` to their Utforska backend host
  - `MCP_APP_URL` to their app host

### Data model differences to account for

Compared with a Kolada-only service, Utforska adds:
- Multi-source dataset IDs (not only Kolada IDs)
- Normalized `content_measures` and `breakdowns`
- Optional session creation/loading deep links

If they currently use direct DB access instead of HTTP APIs, they would need mapping to:
- `datasets`
- `dataset_values`
- `dimension_mappings`
- `metric_aggregations`

Using HTTP endpoints is usually much faster and safer than binding to internal tables directly.
