# IFRC GO MCP Server

Read-only MCP server for IFRC GO data, secured with Microsoft Entra ID OAuth/JWT.

## What this server does

- Exposes some IFRC GO datasets as MCP tools.
- Enforces bearer-token auth with Entra JWT validation.
- Publishes OAuth metadata endpoints for MCP clients.
- Applies request rate limiting.
- Removes selected PII fields from responses before returning data.
- Adds GO frontend URLs to records so callers can open source pages directly.

## Main tools

- `get_agent_instructions`
	- Returns the full data model and querying guidance from `agent-instructions.md`.
- `get_server_info`
	- Returns runtime configuration and upstream connectivity status.
- `ifrcgo_meta`
	- Returns live enum/choice metadata for entity fields via OPTIONS.
- `ifrcgo_read`
	- Main read tool for list/detail access across IFRC GO entities.
- `ifrcgo_get_country_plan`
	- Finds and summarizes the best available planning document for a country.
- `ifrcgo_download_document`
	- Downloads authenticated IFRC GO documents and extracts text (including PDFs).

## Supported entities (via `ifrcgo_read`)

- Reference: `region`, `country`, `district`, `disaster_type`
- Events and reports: `event`, `field-report`, `situation_report`
- Appeals: `appeal`, `appeal_document`
- Surge and deployments: `surge_alert`, `eru`, `eru_owner`, `personnel`, `partner_deployment`
- Projects: `project`, `emergency-project`
- Other: `public-per-process-status`, `public-per-stats`, `ops-learning`, `public-local-units`
- Country detail: `country-plan`, `country-document`, `country-supporting-partner`, `delegation_office`

See `agent-instructions.md` for field-level guidance and workflow examples.

## Quick start (local)

### 1. Create and activate a virtual environment

Windows PowerShell:

```powershell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
```

### 2. Install dependencies

```powershell
pip install -r requirements.txt
```

### 3. Configure environment variables

Set these in your shell, profile, or launch config before starting the server.

Required for auth-gated operation:

- `ENTRA_TENANT_ID`
- `ENTRA_AUDIENCE`
- `ENTRA_CLIENT_ID`
- `MCP_SERVER_URL`
- `STATE_SIGNING_SECRET`

IFRC GO upstream auth:


- Static token mode (supported by current `server.py`):
	- `IFRCGO_API_TOKEN`

Note: `local.settings.json.template` and deployment scripts include `IFRCGO_USERNAME` and `IFRCGO_PASSWORD`, but the current server process initializes `IFRCGOClient` with `IFRCGO_API_TOKEN` only.

Optional:

- `IFRCGO_API_BASE_URL` (default: `https://goadmin.ifrc.org/api/v2`)
- `ENTRA_REQUIRED_SCOPE` (default: `mcp.access`)
- `REQUIRED_GROUP_IDS` (comma-separated)
- `REQUIRED_APP_ROLES` (comma-separated)
- `MCP_RATE_LIMIT_REQUESTS` (default: `60`)
- `MCP_RATE_LIMIT_WINDOW_SECONDS` (default: `60`)
- `SCOPE_NAME` (default: `ifrcgo`)
- `HOST` (default: `0.0.0.0`)
- `PORT` (default: `8000`)

### 4. Run the server

```powershell
python server.py
```

Health endpoint:

- `GET /health`

OAuth metadata endpoints:

- `GET /.well-known/oauth-protected-resource`
- `GET /.well-known/oauth-authorization-server`
- `GET /.well-known/oauth-authorization-server/mcp`

OAuth helper endpoints:

- `GET /oauth/authorize`
- `GET /oauth/callback`
- `POST /oauth/token`
- `POST /register`

MCP transport:

- Mounted at `/` using streamable HTTP from FastMCP.
- MCP JSON-RPC calls are available at `/mcp`.

## Testing

Run unit tests:

```powershell
pytest tests -q -m "not smoke" --ignore=tests/smoke
```

Run smoke tests (live endpoint + valid token required):

```powershell
$env:IFRCGO_MCP_URL = "https://<your-host>"
pytest tests/smoke -q -m smoke
```

Notes:

- Smoke tests require a valid Entra access token. The test fixture in `tests/conftest.py` defines how this is sourced (`az_token`).
- The smoke suite calls MCP methods on `${IFRCGO_MCP_URL}/mcp`.

## Deployment (Azure Container Apps)

This repo includes an automated deploy script:

1. Copy `local.settings.json.template` to `local.settings.json`.
2. Fill in required values (subscription, RG, ACR, Entra, IFRC GO credentials, etc.).
3. Run:

```bash
bash infra/deploy.sh
```

On Windows, run the deploy script from a Bash-compatible shell (for example WSL or Git Bash).

What the script handles:

- Validates local settings.
- Runs non-smoke tests before deploy.
- Builds and pushes Docker image.
- Creates/updates Container App and secrets.
- Applies optional ingress IP allow-list.
- Performs health check and optional smoke tests.

## Security and privacy notes

- All data tools are read-only.
- OAuth/JWT validation is enforced unless Entra settings are missing.
- If `REQUIRED_GROUP_IDS` or `REQUIRED_APP_ROLES` are set, caller token must match at least one.
- Selected PII fields are stripped from `personnel` and `project` results.
- Keep `local.settings.json` and credentials out of source control.

## Repository layout

- `server.py`: MCP server, auth middleware, tool definitions.
- `ifrcgo_client.py`: Async IFRC GO client, auth refresh, list/detail/options helpers, document parsing.
- `agent-instructions.md`: Data model and usage guidance surfaced to MCP agents.
- `tests/`: Unit and smoke tests.
- `infra/deploy.sh`: Azure deployment automation.
- `scripts/`: One-off data processing utilities and generated outputs.

## Notes for MCP clients

- Start sessions by calling `get_agent_instructions`.
- Use `ifrcgo_meta` to resolve current enum values before filtering.
- Use `ifrcgo_read` with `limit` and `offset` for paging.
- Use detail mode with `resource_id` when you need full single-record payloads.