# Country Explorer Athena Agent

An Athena-compatible MCP agent and interactive dashboard for exploring country data. The server exposes a `get_country_info` tool, serves an embeddable country dashboard widget, and includes HTTP endpoints that make the same data available in a browser.

## What it does

- Looks up countries by common name, official name, ISO code, alternate spellings, translations, and native names.
- Returns structured demographic, geographic, currency, language, flag, border, map, and Gini-index data.
- Serves a glassmorphism-style country dashboard at `/` and `/country-explorer.html`.
- Supports both MCP transports:
  - Streamable HTTP at `/mcp`
  - SSE at `/sse` with messages posted to `/messages`
- Provides a simple health check at `/health`.
- Uses local datasets (`world-countries` plus `populations.json`) for fast country lookup without relying on client-side CORS.

## Tech stack

- Node.js + Express
- Model Context Protocol SDK
- `world-countries` for country metadata
- Static population enrichment from `populations.json`
- Plain HTML/CSS/JavaScript dashboard in `public/country-explorer.html`

## Quick start

```bash
npm install
npm start
```

The server defaults to port `8080`:

```text
http://localhost:8080
```

You can override the port with an environment variable:

```bash
PORT=3000 npm start
```

## API endpoints

### Browser dashboard

```text
GET /
GET /country-explorer.html
```

### Country lookup JSON

```text
GET /api/country?name=Canada
```

Example:

```bash
curl "http://localhost:8080/api/country?name=Canada"
```

### Health check

```text
GET /health
```

Returns:

```json
{
  "status": "ok",
  "activeSessions": 0
}
```

## MCP tool

The agent exposes one MCP tool:

### `get_country_info`

Fetches country details and returns both text output and structured content for the dashboard widget.

Input schema:

```json
{
  "country": "Canada"
}
```

The structured response includes fields such as:

- `name`
- `officialName`
- `capital`
- `population`
- `populationRaw`
- `region`
- `subregion`
- `area`
- `flagEmoji`
- `flagUrl`
- `currencies`
- `languages`
- `gini`
- `borders`
- `landlocked`
- `latlng`
- `mapLink`

## MCP connection

### Streamable HTTP

Use `/mcp` for stateless MCP clients that support streamable HTTP.

```text
http://localhost:8080/mcp
```

### SSE

Use `/sse` for SSE clients. Client messages are posted to `/messages` with the session ID provided by the SSE transport.

```text
http://localhost:8080/sse
```

## Deployment

The project includes `vercel.json` for Vercel deployment with `index.js` as the serverless entry point.

```bash
vercel deploy
```

## Project structure

```text
.
├── index.js                         # Express server and MCP agent
├── package.json                     # Node scripts and dependencies
├── package-lock.json                # Locked dependency versions
├── populations.json                 # Static population lookup by ISO-2 code
├── public/
│   └── country-explorer.html        # Interactive dashboard widget
└── vercel.json                      # Vercel routing/build config
```

## Notes

- The dashboard can run inside an Athena/MCP app bridge through `window.openai.callTool`.
- When no bridge is present, the page injects a mock `window.openai` interface that calls the local `/api/country` endpoint, so it also works directly in a browser.
- Some Gini data is manually enriched for common countries in `index.js`; countries without a local Gini entry return `N/A`.

## License

MIT