# Secure Public API MCP Server

FastAPI hosts an OAuth-protected FastMCP server for eight read-only public APIs.
The `/query` convenience endpoint accepts `request_id` and `request_message`,
then selects the relevant allow-listed API tools.

## Routing modes

By default, routing is deterministic and does not need an LLM or API key:

```bash
export LLM_ROUTING_ENABLED=false
```

To enable Gemini reasoning, configure Google Cloud Application Default
Credentials (ADC) and restart the server:

```bash
export LLM_ROUTING_ENABLED=true
export GOOGLE_CLOUD_PROJECT='your-gcp-project-id'
export GOOGLE_CLOUD_LOCATION='us-central1' # optional
# Optional; defaults to gemini-2.5-flash
export GEMINI_MODEL='gemini-2.5-flash'
```

For local development, authenticate the Google SDK once:

```bash
gcloud auth application-default login
```

For a deployed workload, attach a service account with Vertex AI access and
use its ambient credentials (or set `GOOGLE_APPLICATION_CREDENTIALS` to the
service-account credential file). Do not put a Gemini API key in this project.

With LLM routing enabled, Gemini receives a constrained prompt and must return
validated JSON naming only the eight local tools. It cannot access arbitrary
URLs, execute code, or bypass authorization. The service validates and bounds
each selected argument before calling any public API. If the flag is enabled
without project/ADC configuration or the SDK, `/query` returns `503`; it does not silently switch
to rule routing.

## Local setup

```bash
cd /Users/nkrishnakumar/Documents/Mohaan/public-api-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

Create the local configuration before starting the app. It prompts for a local
password, generates the JWT and OAuth client secrets, and writes every required
export to `.env.local` (which is Git-ignored):

```bash
python3 setup.py
source .env.local
uvicorn main:app --reload
```

Enable Gemini/Vertex AI routing while creating the configuration:

```bash
python3 setup.py --llm --gcp-project 'your-gcp-project-id'
source .env.local
gcloud auth application-default login
uvicorn main:app --reload
```

`setup.py` configures `APP_ENV`, JWT issuer/audience/expiry/signing key,
allow-listed users and OAuth clients, LLM mode, Google Cloud project/location,
and Gemini model. It also exports `LOCAL_OAUTH_CLIENT_ID` and
`LOCAL_OAUTH_CLIENT_SECRET` for local curl testing. Re-run it whenever you want
new local secrets; it replaces `.env.local`.

The service runs at `http://127.0.0.1:8000`; OpenAPI documentation is at
`/docs`.

## Authentication and authorization

`POST /token` requires both an approved OAuth client (`client_id` and
`client_secret`) and an approved user credential. It issues a short-lived JWT
containing issuer, audience, expiry, role, and scopes. Every `/mcp/*` request
and `/query` needs this Bearer token. `user` has `read`; `admin` has `read`
and `write`. All current public API tools are read-only.

```bash
curl -X POST http://127.0.0.1:8000/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d "username=local-user&password=<the-password-you-entered>&client_id=$LOCAL_OAUTH_CLIENT_ID&client_secret=$LOCAL_OAUTH_CLIENT_SECRET"
```

```bash
curl -X POST http://127.0.0.1:8000/query \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Content-Type: application/json' \
  -d '{"request_id":"local-001","request_message":"Show Texas weather alerts and the EUR exchange rate"}' | jq
```

MCP clients connect to `GET /mcp/sse` with the same Bearer token and call the
tools `get_currency_rate`, `get_artworks`, `get_dog_pic`, `get_cat_pic`,
`get_dictionary_meaning`, `get_weather_alerts`, `get_random_pic`, and
`get_vehicle_manufacturers`.