# Data Platform MCP Server

MCP (Model Context Protocol) server for AI agents to discover, fetch, and export Swedish statistical data.

## Tools

- **discover_datasets** - AI-powered smart search for datasets
- **get_dataset_details** - Get measures, breakdowns, and time ranges
- **fetch_data** - Fetch actual data rows for direct answers
- **build_export_link** - Generate CSV/JSON download links
- **build_session_link** - Deep link to preload data in the app

In Apps SDK-compatible clients, `discover_datasets` also exposes a card-based widget with:
- dataset cards,
- field inspection (measures + breakdowns + time),
- quick line-chart visualization (with bar fallback),
- loading metrics into a working session before opening the app.

## Installation

The package is available on PyPI and installs automatically via `uvx`:

```bash
# No manual installation needed - uvx handles it automatically
# Just add to your MCP client config (see below)
```

For development:

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

## Usage with MCP Clients

Add to your MCP client config:

**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):

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

**Windsurf** (`~/.codeium/windsurf/mcp_config.json`):

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

**Cursor/Cline**: Same configuration format.

The package installs automatically on first use. No manual installation required!

## Configuration

The server connects to the production backend automatically (`https://utforskadata.se`). No extra configuration is needed for normal use.

For remote/Apps SDK usage, you can run the Streamable HTTP entrypoint:

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

Default endpoint is `http://localhost:8080/mcp` with health at `http://localhost:8080/health`.
For connector clients, prefer the explicit trailing-slash URL: `http://localhost:8080/mcp/`.

Optional environment variables:

- `MCP_BACKEND_URL` (default `https://utforskadata.se`)
- `MCP_APP_URL` (default `https://utforskadata.se`)
- `MCP_DEFAULT_LANG` (default `sv`)
- `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`)

For ChatGPT connector compatibility, keep `MCP_HTTP_STATELESS=true` unless you have a specific reason to require stateful transport.

If you have a local shell override like `MCP_BACKEND_URL=http://localhost:8000`, unset it when testing production behavior.

## Example Flows

### Quick Answer

1. `discover_datasets("housing prices in Sweden")`
2. `get_dataset_details(dataset_id)` - check measures/breakdowns
3. `fetch_data(dataset_id, measure="Average price")` - get data
4. Answer the question with the data
5. Offer `build_export_link()` and the `session_link` from `discover_datasets`

### Deep Dive

1. Same as above
2. `build_session_link(selections=[...])` - create link to continue in app
