Metadata-Version: 2.4
Name: mcp-server-statbridge
Version: 0.1.0
Summary: MCP server for official statistics from ISTAT, Eurostat, OECD, and ECB — with publication-quality charts and maps
Author: StatBridge
License-Expression: MIT
Project-URL: Homepage, https://statbridge.net
Project-URL: Documentation, https://statbridge.net/docs/mcp
Project-URL: Repository, https://github.com/statbridge/statbridge
Keywords: mcp,statistics,istat,eurostat,oecd,ecb,sdmx,data
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: sdmx1>=2.14
Requires-Dist: pandas>=1.5
Requires-Dist: requests>=2.28
Requires-Dist: pyyaml>=6.0
Requires-Dist: mcp[cli]>=1.0
Requires-Dist: matplotlib>=3.7
Requires-Dist: geopandas>=0.13
Requires-Dist: numpy>=1.24
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-mock>=3.0; extra == "dev"

# StatBridge

Official statistics, ready to use. Verified access to ISTAT, Eurostat, OECD and ECB through a hosted REST API, with the local MCP toolkit included in this repo.

> [statbridge.net](https://statbridge.net)

---

## What's in this repo

| Directory | What it does |
|-----------|-------------|
| `sdk/` | **Python SDK** — thin API client (`pip install statbridge`), just httpx |
| `statbridge/` | Core library — SDMX client, topic registry, 4 verified source adapters |
| `mcp_server/` | FastMCP server — 9 tools: search, browse, describe, coverage, get data, chart, map |
| `api/` | FastAPI service — runs on the VPS behind Cloudflare Tunnel |
| `web/` | Next.js 14 app — marketing site, dashboard, docs, auth |
| `agents/` | Shared repo-local agent instructions |
| `db/` | Postgres schema for accounts, API keys, and usage events |
| `docs/` | API and MCP reference docs |
| `CHART_GUIDELINES.md` | StatBridge standards for choosing and formatting charts |
| `CHART_RENDERER_CHECKLIST.md` | Short operational checklist used by the chart tool |
| `tests/` | Unit tests (98 passing) |

---

## Product

| Plan | Price | Volume |
|------|-------|--------|
| **Starter** | €9/mo | 500 req/mo |
| **Pro** | €29/mo | 5,000 req/mo |

Every plan gets the same API, same response format, same source metadata. The hosted product is the REST API. The local MCP server and Python toolkit remain available in this repo for advanced workflows.

---

## Production stack

- **Compute:** Ubuntu VPS (statbridge-vps)
- **Edge / TLS:** Cloudflare Tunnel (no Nginx needed)
- **Web app:** Next.js 14 via `next start` on port 3000
- **API app:** FastAPI via Uvicorn on port 8000
- **Database:** Local PostgreSQL
- **Auth:** NextAuth (Google OAuth)
- **Billing:** Stripe
- **Object storage:** Cloudflare R2 (optional, for exports/media)
- **DNS:** Cloudflare

```
User → Cloudflare Tunnel
         ├─ statbridge.net      → Next.js (port 3000)
         ├─ api.statbridge.net  → FastAPI (port 8000)
         └─ catch-all           → 404
```

Both services run as systemd units. See `DEPLOYMENT.md` for the full setup.

---

## Verified sources

| Source | Status | Coverage |
|--------|--------|----------|
| ISTAT | Live | Italy — regional labour, agriculture, daily life |
| Eurostat | Live | EU-wide economic + social |
| OECD | Live | International |
| ECB | Live | Eurozone — rates, monetary |
| IMF, ILO, BIS, World Bank | Planned | — |

25 live topics today.

---

## Python SDK

The recommended way to use StatBridge from Python. One dependency (`httpx`), no heavy SDMX stack.

```bash
pip install statbridge
```

```python
from statbridge_sdk import StatBridge

sb = StatBridge()  # reads STATBRIDGE_API_KEY from env

sb.search("gdp")
sb.get("unemployment_rate", REF_AREA="IT")
sb.topics()
sb.dimensions("inflation")
sb.health()
```

### Core library (advanced)

For local SDMX access without the hosted API (used internally by the MCP server):

```bash
pip install -e ".[dev]"
```

```python
import statbridge

df = statbridge.get("unemployment_rate")
statbridge.search("gdp")
statbridge.subject_areas()
statbridge.browse(subject_area="labour")
statbridge.describe("inflation")
statbridge.coverage()
```

### Available topics

`unemployment_rate` · `employment_rate` · `gdp_growth` · `inflation` · `population` · `life_expectancy` · `government_debt` · `trade_balance` · `interest_rates` · `house_prices` · `education_expenditure` · `co2_emissions` · `gini_coefficient` · `poverty_rate` · `neet_rate` · `housing_cost_overburden` · `energy_import_dependency` · `labour_productivity_growth` · `tourism_nights_per_capita` · `health_expenditure` · `tax_revenue` · `average_annual_wages` · `median_household_income` · `foreign_born_population`

---

## MCP server

```bash
pip install mcp-server-statbridge
```

Add to Claude Desktop, VS Code, Cursor, or any MCP client:
```json
{
  "mcpServers": {
    "statbridge": {
      "command": "uvx",
      "args": ["mcp-server-statbridge"]
    }
  }
}
```

Tools: `list_sources` · `list_subject_areas` · `search_data` · `browse_topics` · `describe_topic` · `coverage_report` · `get_data` · `create_chart` · `create_map`

---

## Local development

### Next.js (web/)

```bash
cd web
cp .env.example .env.local   # fill in keys
npm install && npm run dev
```

### FastAPI (api/)

```bash
cd api
cp .env.example .env
pip install -r requirements.txt
uvicorn main:app --reload
```

---

## Tests

```bash
# Unit (no network)
python -m pytest tests/unit/ -v

# Integration (requires network)
python -m pytest tests/integration/ -m integration -v

# Coverage report
python -m statbridge.verification
```

---

## Roadmap

- [ ] IMF, ILO, World Bank, BIS source adapters
- [ ] R2-backed chart export endpoint (`/v1/chart` → PNG URL)
- [ ] R2-backed map export endpoint (`/v1/map` → PNG URL)
- [ ] Team plan (shared usage pool, multiple seats)
