Metadata-Version: 2.4
Name: utforska-data-mcp
Version: 1.0.2
Summary: MCP server for Swedish statistical data discovery and export
Project-URL: Homepage, https://utforskadata.se
Project-URL: Repository, https://github.com/deslay1/data-platform
Author-email: Utforska Data <datary@protonmail.com>
License: MIT
License-File: LICENSE
Keywords: ai,data,mcp,scb,statistics,sweden
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Requires-Dist: httpx>=0.25.0
Requires-Dist: mcp>=1.25.0
Requires-Dist: starlette>=0.37.0
Requires-Dist: uvicorn>=0.30.0
Description-Content-Type: text/markdown

# 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
