estevao-mcp

MCP (Model Context Protocol) server for the Estêvão 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

You need an Estêvão API key (estevao_…). Then:

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

Or in .mcp.json / Claude Desktop config:

{
  "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.

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 (11 editions, pt-BR/en/es) and Bible versions
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://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), 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]

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)

The same server can run as a remote MCP endpoint (POST /mcp, stateless Streamable HTTP):

npm run build && node dist/http.js          # or: docker build -t estevao-mcp . && docker run -p 3333:3333 estevao-mcp

Two auth modes, chosen by env:

• Passthrough (default, multi-tenant): don't set ESTEVAO_API_KEY on the server. Each client sends its own key in the X-API-Key header (or Authorization: Bearer estevao_…).
• Single-key (personal deployment): set ESTEVAO_API_KEY on the server. Optionally set ESTEVAO_MCP_TOKEN to require Authorization: Bearer <token> from clients.

Extra env: PORT (default 3333), ESTEVAO_MCP_ALLOWED_HOSTS (comma-separated; enables DNS-rebinding protection). GET /healthz reports the mode.

Client config for a remote deployment:

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

Development

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

Releasing

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.

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