Estevao MCP Server

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.

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

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

Bump the version in both package.json and server.json (registry limit: description ≤ 100 chars), then either:

• Manual (current flow): npm publish --access public, then mcp-publisher login github && mcp-publisher publish.
• CI: tag vX.Y.Z — GitHub Actions publishes to npm (provenance) and to the MCP registry via GitHub OIDC. Requires the NPM_TOKEN repo secret.

License

MIT