# estevao-mcp [Health: Active]

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/dodopok/estevao-mcp  
**GitHub Stars:** 0  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/estevao-mcp

## Description
Anglican liturgical calendar, lectionary and Daily Office (Book of Common Prayer) via Estêvão API

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

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

## Documentation & README

# 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/oauth-protected-resource` (also under `/mcp`),
`/.well-known/oauth-authorization-server`, `/authorize`, `/token`, `/register`, `/revoke`,
and the consent screen at `/oauth/consent`. `GET /healthz` reports the active mode.

Security properties: PKCE `S256` is mandatory, authorization codes are single-use and expire in
60s, refresh tokens rotate on use, access tokens are opaque and stored only as digests, tokens
are bound to this server's resource identifier (RFC 8707) and rejected otherwise, and the
Estêvão API key is AES-256-GCM encrypted at rest.

### Connecting any MCP client

The endpoint is standard Streamable HTTP with OAuth 2.1 discovery, so any spec-compliant
client can connect. Concretely:

| Client | How |
|---|---|
| **Claude Code** | `claude mcp add --transport http estevao https://mcp.caminhoanglicano.com.br/mcp` |
| **Claude Code plugin** | `/plugin marketplace add dodopok/estevao-mcp` then `/plugin install estevao@estevao` |
| **Claude Desktop / claude.ai** | Settings → Connectors → Add custom connector → paste the URL |
| **Codex CLI** | `codex mcp add estevao --url …/mcp` then `codex mcp login estevao` |
| **Gemini CLI** | `~/.gemini/settings.json`: `{"mcpServers":{"estevao":{"httpUrl":"…/mcp","oauth":{"enabled":true}}}}` |
| **VS Code / Cursor / Windsurf** | Add an MCP server of type `http` with the URL; the editor runs the OAuth flow |
| **MCP Inspector** | `npx @modelcontextprotocol/inspector`, transport "Streamable HTTP", paste the URL |
| **Anything else** | `{"type":"http","url":"https://mcp.caminhoanglicano.com.br/mcp"}` |

Interoperability details that make this work across clients:

- **Discovery everywhere clients look.** Protected resource metadata is served both at the root
  and under `/mcp`; authorization server metadata is served at
  `/.well-known/oauth-authorization-server`, its `/mcp` path-inserted variant, and both
  OpenID Connect discovery spellings.
- **Registration.** Dynamic Client Registration (RFC 7591) *and* Client ID Metadata Documents
  are both accepted; clients that pre-register a `client_id` work too.
- **Client authentication.** `none` (public clients, the common case) and both
  `client_secret_post` and `client_secret_basic` for confidential ones.
- **Scopes.** There is one read-only scope, `liturgy:read`. Clients that ask for unrelated
  scopes (`openid profile`, `mcp`, or nothing) still get a working connection.
- **CORS.** Preflight is answered and `WWW-Authenticate` is exposed, so browser-based clients
  can read the challenge and start the flow.
- **Probes.** Unauthenticated `GET`/`DELETE` on `/mcp` return the auth challenge rather than a
  bare 405, so clients that probe before authenticating still discover the flow.

### Client config for a key-based deployment

```json
{
  "mcpServers": {
    "estevao": {
      "type": "http",
      "url": "https://<your-host>/mcp",
      "headers": { "X-API-Key": "estevao_your_key" }
    }
  }
}
```

Extra env: `PORT` (default 3333), `ESTEVAO_MCP_ALLOWED_HOSTS` (comma-separated; enables
DNS-rebinding protection).

## Plugin para Codex, Claude e outros clientes

O repositório inclui um pacote universal em [`plugins/estevao`](https://github.com/dodopok/estevao-mcp/blob/HEAD/plugins/estevao), com manifests
para Codex e Claude Code e uma configuração MCP compartilhada. O pacote aponta para o servidor
hospedado, então a conexão usa OAuth e não exige copiar uma API key.

Para Claude Code:

```
/plugin marketplace add dodopok/estevao-mcp
/plugin install estevao@estevao
```

Para Codex CLI:

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

Veja o guia visual de integração no [portal do desenvolvedor](https://estevao.caminhoanglicano.com.br/docs/mcp).
O mesmo endpoint funciona em qualquer cliente MCP compatível com Streamable HTTP e OAuth 2.1.

## Development

```bash
npm install
npm run typecheck && npm test    # vitest + msw fixtures, no network
npm run build                    # tsup → dist/index.js + dist/http.js
npm run inspector                # manual testing with the MCP Inspector

# end-to-end against a local estevao-api (docker-compose up in that repo):
SMOKE_KEY=estevao_… npx tsx scripts/smoke.ts

# remote transport (see .env.example for the OAuth variables):
npm run build && node dist/http.js
docker build -t estevao-mcp . && docker run -p 3333:3333 --env-file .env estevao-mcp
```

## Releasing

```bash
npm version patch        # bumps package.json AND server.json (version hook), commits + tags
git push --follow-tags
npm publish --access public
mcp-publisher publish    # mcp-publisher login github, first time
```

The npm `version` lifecycle hook (`scripts/sync-version.ts`) keeps `server.json` in sync and enforces the registry's 100-char description limit. The server's advertised MCP version comes from `package.json` at build time.

`server.json` lists both the hosted endpoint (`remotes`) and the npm package (`packages`), so
registry clients can pick either. Keep the hosted URL in step with the actual deployment.

Alternatively, once GitHub Actions is available with the `NPM_TOKEN` secret, `git push --follow-tags` alone triggers the release workflow (npm with provenance + MCP registry via GitHub OIDC).

## License

MIT