Metadata-Version: 2.4
Name: kapsarc-mcp-server
Version: 0.1.0
Summary: MCP server for the KAPSARC Data Portal — search, query, export, and visualize energy/economic datasets
Project-URL: Repository, https://github.com/MHDhazmi/kapsarc-mcp-server
Author: MHDhazmi
License-Expression: MIT
License-File: LICENSE
Keywords: datasets,energy,kapsarc,mcp,opendatasoft
Requires-Python: >=3.11
Requires-Dist: httpx
Requires-Dist: matplotlib>=3.8
Requires-Dist: mcp[cli]
Description-Content-Type: text/markdown

# KAPSARC Data Portal MCP Server

An MCP server that connects LLMs to the [KAPSARC Data Portal](https://datasource.kapsarc.org) — search, query, export, and **visualize** energy and economic datasets via the Opendatasoft Explore API v2.1.

## Tools

### Data Tools

| Tool | Description |
|------|-------------|
| `search_datasets` | Free-text search of KAPSARC datasets |
| `get_dataset` | Full metadata and field definitions for a dataset |
| `get_records` | Query records with ODSQL filters |
| `get_record` | Retrieve a single record by ID |
| `get_dataset_facets` | Categorical field values and counts |
| `get_catalog_facets` | Portal-wide themes, keywords, publishers |
| `export_dataset` | Export without 100-record limit (JSON/CSV) |
| `get_dataset_attachments` | List documentation/file attachments |
| `export_catalog` | Bulk export all dataset metadata |
| `list_export_formats` | Check available export formats |

### Visualization Tools

| Tool | Description |
|------|-------------|
| `visualize_dataset` | Fetch data and render a branded chart image |
| `visualize_data` | Render a chart from pre-fetched records (no API call) |
| `visualize_comparison` | Multi-series comparison charts (e.g. country vs country) |

All charts are returned as PNG images with official KAPSARC branding — logo, color palette, and source attribution. Chart types are auto-detected from data shape, or can be explicitly set to: `bar`, `hbar`, `line`, `pie`, or `scatter`.

## Example Charts

### Bar Chart — Top Oil Producers
![Bar Chart](examples/bar_chart.png)

### Line Chart — Time Series
![Line Chart](examples/line_chart.png)

### Pie Chart — Energy Mix
![Pie Chart](examples/pie_chart.png)

### Multi-Line — Production Comparison
![Multi-Line Chart](examples/multiline_chart.png)

### Scatter Plot — GDP vs Energy
![Scatter Chart](examples/scatter_chart.png)

### Horizontal Bar — Energy by Sector
![Horizontal Bar Chart](examples/hbar_chart.png)

### Electricity Prices
![Electricity Prices](examples/electricity_prices.png)

### Renewable Energy Capacity
![Renewables Capacity](examples/renewables_capacity.png)

### GCC Power Generation Mix
![GCC Power Mix](examples/gcc_power_mix.png)

### Multi-Bar — CO2 Emissions
![CO2 Emissions](examples/co2_emissions_comparison.png)

### Solar Irradiance vs Capacity Factor
![Solar Scatter](examples/solar_scatter.png)

### Renewable Share of Electricity
![Renewable Share Trend](examples/renewable_share_trend.png)

### Hydrogen Production Costs
![Hydrogen Costs](examples/hydrogen_costs.png)

### Brent Crude Oil Price
![Brent Crude Price](examples/brent_crude_price.png)

### Saudi Arabia GDP Composition
![Saudi GDP Composition](examples/saudi_gdp_composition.png)

## Installation

### Quick Start

```bash
uvx kapsarc-mcp-server
```

Or install with pip:

```bash
pip install kapsarc-mcp-server
kapsarc-mcp-server
```

### Claude Code

```bash
claude mcp add kapsarc-data -- uvx kapsarc-mcp-server
```

### Claude Desktop

Add to your Claude Desktop config (`claude_desktop_config.json`):

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

### Development

```bash
git clone https://github.com/MHDhazmi/kapsarc-mcp-server.git
cd kapsarc-mcp-server
uv sync
uv run kapsarc-mcp-server
```

## Configuration

Set the `KAPSARC_API_KEY` environment variable to authenticate with the KAPSARC API. This is optional — most datasets are publicly accessible without a key.

```bash
export KAPSARC_API_KEY="your-api-key"
```

## Development

```bash
# Unit tests (no network needed)
uv run pytest tests/test_charts.py -v

# Integration tests (hits live KAPSARC API)
uv run pytest tests/test_main.py -v

# Regenerate example chart images
uv run python examples/generate_examples.py
```

## License

MIT
