estevao-mcp

# estevao-mcp

[![npm](https://img.shields.io/npm/v/estevao-mcp)](https://www.npmjs.com/package/estevao-mcp)
[![MCP Registry](https://img.shields.io/badge/MCP_Registry-io.github.dodopok%2Festevao--mcp-blue)](https://registry.modelcontextprotocol.io/?search=estevao)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

MCP (Model Context Protocol) server for the [Estêvão API](https://github.com/dodopok/estevao-api) — the liturgical engine behind the Ordo app. Gives Claude and any MCP client accurate Anglican liturgical data: calendar (with real precedence rules), lectionary readings, and the fully assembled Daily Office across multiple editions of the Book of Common Prayer / Livro de Oração Comum.

## Quick start

**Hosted (no key to manage)** — sign in with your Google/e-mail account when the browser opens:

```bash
claude mcp add --transport http estevao https://mcp.caminhoanglicano.com.br/mcp   # Claude Code
codex mcp add estevao --url https://mcp.caminhoanglicano.com.br/mcp               # Codex CLI
```

Other clients: see [Connecting any MCP client](#connecting-any-mcp-client).

**Local (stdio)** — you need an Estêvão API key (`estevao_…`):

```bash
claude mcp add estevao --env ESTEVAO_API_KEY=estevao_your_key -- npx -y estevao-mcp
```

Or in `.mcp.json` / Claude Desktop config:

```json
{
  "mcpServers": {
    "estevao": {
      "command": "npx",
      "args": ["-y", "estevao-mcp"],
      "env": { "ESTEVAO_API_KEY": "estevao_your_key" }
    }
  }
}
```

Then ask things like *"what are the readings for next Sunday?"*, *"assemble tonight's Compline"* or *"compare Christmas in the 1662 and 2019 prayer books"*.

## Tools

Dates accept `YYYY-MM-DD`, `today` or `next-sunday`. Every tool takes an optional `prayer_book` (default `loc_2015`); all tools are read-only. Prayer book codes are validated by the API rather than pinned in this server, so editions added upstream work without a release here — `list_prayer_books` always shows the current catalogue.

| Tool | What it does |
|---|---|
| `get_liturgical_day` | Season, color, liturgical year, celebration/saint, collect and readings for a date |
| `get_calendar_month` | Month grid: color, celebration and week per day |
| `get_year_overview` | Year structure: seasons, movable feasts and key dates |
| `get_readings` | Lectionary readings (first, psalm, second, gospel), optionally per service |
| `get_lectionary_cycle` | Sunday (A/B/C) and weekday (1/2) cycles for a year |
| `get_daily_office` | The complete Daily Office (morning/midday/evening/compline) as markdown or structured JSON |
| `search_celebrations` | Full-text search of feasts, saints and holy days |
| `list_celebrations` | Browse the sanctoral calendar with filters (type, movable, year) |
| `get_celebration` | One celebration in detail: transfer rules, calculation, collects, readings |
| `list_prayer_books` | Available prayer books (20+ editions, pt-BR/en/es/cy) and Bible versions |
| `get_prayer_book_preferences` | Which preferences a book accepts (psalm translation, canticles, cycles) plus its office-level options |
| `explain_liturgical_day` | The reasoning behind a date: precedence, transfers, colour and how each reading was chosen |
| `compare_prayer_books` | Side-by-side comparison of 2–4 prayer books for the same day or office |

## Resources & prompts

- **Resources**: `ordo://prayer-books`, `ordo://bible-versions`, `ordo://today`, plus templates `ordo://day/{date}`, `ordo://explain/{date}` (the decision trail), `ordo://office/{date}/{office_type}` (markdown) and `ordo://calendar/{year}/key-dates`.
- **Prompts** (strictly factual): `build_liturgy_sheet` (print-ready boletim), `explain_feast` (history, precedence, color), `explain_why` (why this reading/saint/colour, answered from the engine's decision trail rather than inferred), `compare_traditions` (side-by-side across editions).

> **Editorial note:** this server intentionally exposes only factual liturgical data and faithful document assembly. It does not (and will not) ship prompts that generate sermons, homilies or devotional reflections.

## Environment variables

| Variable | Default | Purpose |
|---|---|---|
| `ESTEVAO_API_KEY` | — (required for stdio) | API key for the Estêvão API |
| `ESTEVAO_BASE_URL` | `https://api.caminhoanglicano.com.br` | Override for local/staging |
| `ESTEVAO_DEFAULT_PRAYER_BOOK` | `loc_2015` | Default prayer book code |
| `ESTEVAO_TIMEZONE` | system | IANA timezone used to resolve `today` |
| `ESTEVAO_LANGUAGE` | — | Default label language (`pt-BR`, `en`, `es`) and upstream `preferences[language]` |

### Per-book preferences

The date-scoped tools take a `preferences` object forwarded to the API, which unlocks the
per-edition options the Ordo app exposes — the Coverdale psalter on the English books
(`{ "psalm_translation": "coverdale" }`), monthly vs appointed psalm cycles, canticle and
opening-sentence choices, family-rite variants. The accepted keys differ per book, so call
`get_prayer_book_preferences` first rather than guessing.

### Languages

Liturgical content always stays in the prayer book's own language (a 1662 office is English, LOC 2015 is Portuguese). Labels generated by the server — office titles, `Season/Tempo/Tiempo`, comparison headings — automatically follow the book's language, and can be overridden per call (`language` param) or globally (`ESTEVAO_LANGUAGE`).

## Remote server (Streamable HTTP + OAuth)

The same server runs as a remote MCP endpoint (`POST /mcp`, stateless Streamable HTTP).
Deployed with OAuth enabled, users connect with a browser sign-in instead of pasting a key:

```bash
claude mcp add --transport http estevao https://mcp.caminhoanglicano.com.br/mcp
codex mcp add estevao --url https://mcp.caminhoanglicano.com.br/mcp && codex mcp login estevao
```

The client discovers the authorization server, registers itself, opens the consent screen,
and the user signs in with the same Google/e-mail account they use in the
[developer portal](https://estevao.caminhoanglicano.com.br). The server then provisions an
Estêvão API key for that account, encrypts it at rest and uses it for every upstream call —
the user never sees or handles a key, and the client's token is never forwarded upstream.

### Auth modes

The mode is chosen by environment, and resolved per request in this order:

1. **Single-key** (personal deployment): `ESTEVAO_API_KEY` set on the server. Optionally set
   `ESTEVAO_MCP_TOKEN` to require `Authorization: Bearer <token>` from clients.
2. **API key** (unchanged, for existing integrations): the caller sends its own key in
   `X-API-Key` (or `Authorization: Bearer estevao_…`). Disable with
   `ESTEVAO_MCP_ALLOW_API_KEY_HEADER=false`.
3. **OAuth 2.1** (recommended for public deployments): the caller sends an access token issued
   by this server. Enabled when the OAuth variables below are all set.

### OAuth configuration

| Variable | Required | Purpose |
|---|---|---|
| `MCP_PUBLIC_URL` | yes | Public origin, e.g. `https://mcp.caminhoanglicano.com.br`. Also the OAuth issuer |
| `MCP_ENCRYPTION_KEY` | yes | 32 bytes (`openssl rand -hex 32`) — encrypts stored API keys |
| `DEVELOPER_FIREBASE_PROJECT_ID` | yes | Firebase project of the **developer portal** (not the mobile app) |
| `FIREBASE_API_KEY` / `FIREBASE_AUTH_DOMAIN` | yes | Web config used by the consent screen |
| `DATABASE_URL` | strongly recommended | Postgres for clients, codes, tokens and the key vault. Without it, state is in memory and lost on restart |
| `MCP_DATABASE_SSL` | no | Force TLS on the database connection (auto-detected) |
| `ESTEVAO_PORTAL_URL` | no | Developer portal link shown on the consent screen |
| `MCP_ALLOW_CLIENT_ID_METADATA_DOCUMENTS` | no | Accept URL-shaped `client_id`s (default `true`) |
| `MCP_FIREBASE_AUTH_PROXY` | no | Serve Firebase's sign-in helper from this origin (default `true`, see below) |
| `MCP_TRUST_PROXY` | no | Express `trust proxy` (default `1`, one edge hop). Rate limits key off the real client IP |

Setting only some of these is a configuration error and the server refuses to start, rather
than silently falling back to key-only mode. The Postgres schema is created on boot.

#### Same-origin sign-in (required on mobile and Safari)

By default the Firebase Web SDK runs its sign-in helper on `<project>.firebaseapp.com`, a
different origin from this server. Safari's ITP (16.1+), Firefox and the in-app browsers used
by mobile assistants block the cross-origin round trip that flow needs: the user picks a Google
account and then nothing happens. So this server reverse-proxies `/__/auth/*` to the Firebase
helper and points the consent screen at its own origin, which is the fix
[Firebase documents](https://firebase.google.com/docs/auth/web/redirect-best-practices) for it.
Sign-in uses a full-page redirect rather than a popup, for the same reason.

Two one-time console steps make this work:

1. **Firebase Console → Authentication → Settings → Authorized domains**: add the MCP host.
2. **Google Cloud Console → APIs & Services → Credentials → the Web OAuth 2.0 client** used by
   Firebase: add `https://<mcp host>/__/auth/handler` to *Authorized redirect URIs*.

Set `MCP_FIREBASE_AUTH_PROXY=false` to go back to the stock cross-origin behaviour.

#### Diagnosing a failed sign-in

Sign-in runs in the user's browser, so a failure there reaches no log by itself. The consent
screen posts beacons to `/oauth/diagnostics`, which the server writes to stderr:

```
[consent] rendered request=… client=Claude
[consent] stage=loaded pending=false storage=true ua=…
[consent] stage=redirect-start request=… ua=…
[consent] stage=redirect-lost request=… ua=…     ← came back from Google, state was lost
[consent] stage=redirect-error code=auth/…       ← Firebase rejected the sign-in
[consent] approve failed request=… error=…       ← sign-in worked, key provisioning did not
```

Only error codes and flags are reported — never tokens or credentials.

Endpoints: `/.well-known/