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

Related MCP server: Liturgical Calendar MCP Server

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.

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

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