Metadata-Version: 2.4
Name: data360-mcp
Version: 0.1.2
Summary: Data360 MCP Project
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastmcp>=2.12.4
Requires-Dist: mcp>=1.18.0
Requires-Dist: fastapi>=0.115.0
Requires-Dist: uvicorn[standard]>=0.30.0
Requires-Dist: langchain-mcp-adapters>=0.1.13
Requires-Dist: typer>=0.20.1
Requires-Dist: gunicorn>=23.0.0
Requires-Dist: langchain-openai>=1.1.7
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: draco
Dynamic: license-file

# 🌍 Data360 MCP Server

> **Unlock the World Bank's global development data directly within your LLM agents.**

This Model Context Protocol (MCP) server bridges the gap between Large Language Models and the World Bank's massive [Data360 Platform](https://tcdata360.worldbank.org/). It empowers agents to search, validate, and retrieve precise development indicators—from GDP to gender equality metrics—without hallucinating.

## ✨ Capabilities

This isn't just a wrapper; it's significant "glue" code that makes the Data360 API agent-friendly.

### 🔍 Smart Discovery
**Composable tools for precise searches.**
Use `data360_search_indicators` with `select_fields` to control what data is returned. Validate availability with `data360_get_disaggregation` to check which countries and years have data.

### 📊 Deep Metadata
**Context is king.**
Fetch rich metadata selectively using `data360_get_metadata` with `select_fields` to get only what you need—methodology, statistical concepts, or limitations.

### 📈 Reliable Data Retrieval
**Clean, time-series data.**
Fetch historical data points for any indicator with `data360_get_data`, supporting filters for country, time period, sex, age, and urbanization.

### 🤖 LLM-Optimized Resources
**Built-in guidance for chatbots.**
MCP resources provide system prompts with chain-of-thought reasoning, codelist references, and metadata field mappings.

---

## 🚀 Quick Start

### 1. Prerequisites
- **Python 3.10+** (or use Docker)
- [uv](https://github.com/astral-sh/uv) (recommended)

### 2. Run the Server
```bash
chmod +x scripts/start_server.sh
./scripts/start_server.sh
```

The server will start on port `8021` at `/sse`.

### 3. Connect your Agent
- **Transport**: SSE
- **URL**: `http://localhost:8021/sse`
- **Docker Users**: Use `http://host.docker.internal:8021/sse`

### 4. Try the Demo Script (Optional)
```bash
uv run scripts/llm_mcp_demo.py
```
For debug mode (shows raw JSON):
```bash
DEBUG=true uv run scripts/llm_mcp_demo.py
```

---

## 🛠️ Tools Available

| Tool | Description |
|------|-------------|
| **`data360_search_indicators`** | Search for indicators with enriched metadata. Pass `required_country` for server-side coverage check. Returns `covers_country`, `latest_data`, `dimensions`. |
| **`data360_get_data`** | Fetch data points with filters (REF_AREA, time period, SEX, AGE, etc.). |
| **`data360_get_metadata`** | Get indicator metadata. Use `select_fields` for specific fields. |
| **`data360_get_disaggregation`** | Check available filter values (countries, years, dimensions). |
| **`data360_find_codelist_value`** | Resolve names to codes (e.g., "Kenya" → "KEN", "female" → "F"). |
| **`data360_list_indicators`** | List all indicators for a database. |

### Recommended Workflow

```
1. Search → data360_search_indicators(query, required_country="Kenya")
   Returns: covers_country, latest_data, dimensions for each indicator
   
2. Get Data → data360_get_data(database_id, indicator_id, filters)
   Use REF_AREA code from search, add time filters
```


---

## 📚 Resources Available

| Resource | Description |
|----------|-------------|
| `data360://system-prompt` | Chain-of-thought guidance for chatbot integration |
| `data360://databases` | Available databases (WB_WDI, WB_SSGD, etc.) |
| `data360://codelists` | Codelist reference (REF_AREA, SEX, AGE, etc.) |
| `data360://metadata-fields` | Field mapping for smart question routing |
| `data360://data-filters` | Available filters and usage guidance |
| `data360://search-usage` | Search examples and best practices |

---

## 💬 Chatbot Integration

For chatbot integration, copy the content of `data360://system-prompt` into your system prompt. It includes:
- Chain-of-thought reasoning templates
- Step-by-step workflow guidance
- Filter do's and don'ts (e.g., never use FREQ filter)

---

## ⚙️ Configuration

| Variable | Description | Default |
|----------|-------------|---------|
| `DATA360_API_BASE_URL` | Base URL for the World Bank API | `https://data360api.worldbank.org` |
| `PORT` | Port for the MCP server | `8021` |

---

## 👨‍💻 Development

See [DEVELOPMENT.md](DEVELOPMENT.md) for detailed instructions on setting up the local dev environment.

---

<p align="center">
  <sub>Built with <a href="https://github.com/jlowin/fastmcp">FastMCP</a> and the <a href="https://modelcontextprotocol.io">Model Context Protocol</a>.</sub>
</p>
