# MEDAS MCP (Still in development!)

MCP server for TÜİK MEDAS (Turkish Statistical Institute indicators).

## Features

- **92 topics** — all TÜİK statistical categories
- **400+ indicators** — cached instantly, live fallback available
- **Dynamic discovery** — 0 hardcoded widget IDs, adaptive to UI changes
- **Cache-first** — `list_topics`/`get_indicators`/`download` all <50ms from cache
- **Binary XLS** — xlwt CDFV2 Excel output (same format as MEDAS pivot.xls)
- **Smart cascading** — auto-selects mandatory breakdowns (COICOP, SITC, etc.)
- **ZK Widget API** — robust kırılım handling via `zk.Widget.$().fire()`

## Install

```bash
pip install playwright xlwt httpx
playwright install chromium
```

Or with uv:

```bash
uv pip install -e .
playwright install chromium
```

## Usage

### As MCP server (stdio)

```bash
python server.py
```

### Pi integration

Add to `~/.pi/config.json`:

```json
{
  "extensions": {
    "medas": {
      "command": "python",
      "args": ["/path/to/medas_mcp/server.py"],
      "cwd": "/path/to/medas_mcp"
    }
  }
}
```

### Claude Desktop

```json
{
  "mcpServers": {
    "medas": {
      "command": "python",
      "args": ["/path/to/medas_mcp/server.py"]
    }
  }
}
```

## Tools

| Tool | Description | Speed |
|------|-------------|-------|
| `list_topics(search?)` | List 92 TÜİK topics | <50ms (cache) |
| `get_indicators(topic_index)` | Get indicators + cascading branches | <50ms (cache) |
| `download(topic_index, indicators?, format?, save_path?, live?)` | Download XLS/CSV report | <50ms cache / ~12s live |

### Example flow

```
1. list_topics("fiyat") → [{index:78, label:"Tüketici Fiyat Endeksi"}]
2. get_indicators(78) → {count:12, indicators:[...]}
3. download(78, format="xls") → /tmp/MEDAS_Tüketici_Fiyat_Endeksi_20260820.xls
```

## Architecture

```
AI Agent  ⇄  MCP (stdio)  ⇄  server.py  ⇄  medas_client.py
                                            ├─ cache (data/*.json) → instant
                                            └─ Playwright (live=true) → ZK AU protocol
```

### Cache vs Live

| Mode | Source | Speed | Data |
|------|--------|-------|------|
| `live=false` (default) | `data/*.json` cache | <50ms | Indicator names + mock values |
| `live=true` | `POST /medas/zkau` → `GET /pivot.xls` | ~12s | Real MEDAS pivot table |

## Files

```
medas_mcp/
├── server.py              # MCP server (3 tools)
├── medas_client.py        # Hybrid client (cache + live Playwright)
├── KNOWHOW.md             # ZK AU protocol traffic notes
├── AGENTS.md              # AI agent instructions
├── README.md              # This file
├── pyproject.toml         # Package metadata
├── .gitignore
└── data/
    ├── topic_mapping.json  # 92 topics with URLs
    ├── topic_gosterge.json # Indicators + cascading branches
    └── medas_unified.json  # Unified dataset
```

## ZK AU Protocol

- `POST /medas/zkau;jsessionid=XXX` with `dtid` + batched `cmd_n=onSelect/onClick`
- Widget IDs change every session — discovered dynamically via DOM
- Cascading: `zk.Widget.$('#selectId').fire('onSelect', {items:[itemId], reference:itemId})`

## License

MIT