estevao-mcp

estevao-mcp

Estêvão API 的 MCP（Model Context Protocol）服务：Estêvão API 是 Ordo 应用背后的礼仪引擎。它为 Claude 和任何 MCP 客户端提供准确的圣公会礼仪数据：日历（包含真实的优先级规则）、选经表读经，以及跨多个版本的《公祷书》/《共同祈祷书》（Livro de Oração Comum）完整编排的每日祷告。

快速开始

托管服务（无需管理密钥）——浏览器打开后，使用 Google/电子邮件账号登录：

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

其他客户端：请参阅连接任何 MCP 客户端。

本地（stdio）——你需要一个 Estêvão API 密钥（estevao_…）：

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

或者在 .mcp.json / Claude Desktop 配置中：

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

然后可以询问诸如 “下周日的读经内容是什么？”、“编排今晚的晚祷” 或 “比较 1662 年和 2019 年祷告书中的圣诞节” 等问题。

工具

日期可使用 YYYY-MM-DD、today 或 next-sunday。每个工具都接受可选的 prayer_book（默认为 loc_2015）；所有工具均为只读。祷告书代码由 API 验证，而非固定在此服务中，因此上游新增的版本无需在此发布新版本即可使用——list_prayer_books 始终显示当前目录。

工具	功能
get_liturgical_day	指定日期的礼仪季节、颜色、礼仪年、庆典/圣徒、集祷文和读经
get_calendar_month	月历：每天的颜色、庆典和星期
get_year_overview	年度结构：礼仪季节、可移动节日和重要日期
get_readings	选经表读经（第一段、诗篇、第二段、福音），可按礼拜仪式筛选
get_lectionary_cycle	某年的主日（A/B/C）和工作日（1/2）周期
get_daily_office	完整的每日祷告（晨祷/午祷/晚祷/晚祷仪式），以 Markdown 或结构化 JSON 格式呈现
search_celebrations	对节日、圣徒和圣日进行全文搜索
list_celebrations	浏览圣徒历，可按类型、是否可移动和年份筛选
get_celebration	查看单个庆典的详细信息：转移规则、计算方式、集祷文和读经
list_prayer_books	可用的祷告书（20 多个版本，pt-BR/en/es/cy）和圣经译本
get_prayer_book_preferences	某版本支持的偏好设置（诗篇译本、赞歌、周期），以及其礼拜仪式级选项
explain_liturgical_day	说明某个日期的判定依据：优先级、节日转移、颜色，以及各段读经的选择方式
compare_prayer_books	并排比较同一天或同一礼拜仪式所用的 2–4 本祷告书

资源和提示词

• 资源：ordo://prayer-books、ordo://bible-versions、ordo://today，以及模板 ordo://day/{date}、ordo://explain/{date}（决策轨迹）、ordo://office/{date}/{office_type}（Markdown）和 ordo://calendar/{year}/key-dates。
• 提示词（严格遵循事实）：build_liturgy_sheet（可直接打印的礼仪单），explain_feast（历史、优先级、颜色），explain_why（解释为何选用这段读经/这位圣徒/这种颜色，依据引擎的决策轨迹作答，而非推断），compare_traditions（并排比较不同版本）。

**编辑说明：**本服务仅提供事实性的礼仪数据，并忠实编排文档。它不会（也不会发布）用于生成布道、讲道或灵修反思的提示词。

环境变量

变量	默认值	用途
ESTEVAO_API_KEY	—（stdio 必需）	Estêvão API 的 API 密钥
ESTEVAO_BASE_URL	https://api.caminhoanglicano.com.br	覆盖为本地／暂存环境地址
ESTEVAO_DEFAULT_PRAYER_BOOK	loc_2015	默认祈祷书代码
ESTEVAO_TIMEZONE	system	用于确定 today 的 IANA 时区
ESTEVAO_LANGUAGE	—	默认标签语言（pt-BR、en、es）以及上游的 preferences[language]

每本祈祷书的偏好设置

日期范围工具会将 preferences 对象转发给 API，从而启用 Ordo 应用提供的各版本选项——英文祈祷书中的 Coverdale 诗篇译本（{ "psalm_translation": "coverdale" }）、按月或指定的诗篇循环、赞美诗和启始句选项，以及家庭礼仪变体。各祈祷书接受的键有所不同，因此请先调用 get_prayer_book_preferences，不要自行猜测。

语言

礼仪内容始终使用祈祷书本身的语言（1662 年礼仪文本为英文，LOC 2015 为葡萄牙文）。服务端生成的标签——礼仪标题、Season/Tempo/Tiempo、比较标题——会自动使用祈祷书的语言，也可针对单次调用（language 参数）或全局（ESTEVAO_LANGUAGE）覆盖。

远程服务（Streamable HTTP + OAuth）

同一服务也可作为远程 MCP 端点运行（POST /mcp，无状态 Streamable HTTP）。 启用 OAuth 后部署，用户可通过浏览器登录连接，而不必粘贴密钥：

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

客户端会发现授权服务器、完成自身注册并打开授权同意页面，用户使用与 开发者门户相同的 Google／电子邮件账号登录。随后，服务端会为该账号创建 Estêvão API 密钥，对密钥进行静态加密，并在每次上游调用时使用该密钥——用户既看不到也无需处理密钥，客户端的令牌也不会转发到上游。

身份验证模式

模式由环境变量决定，并按以下顺序逐个请求解析：

1. 单密钥（个人部署）：在服务端设置 ESTEVAO_API_KEY。也可设置 ESTEVAO_MCP_TOKEN，要求客户端提供 Authorization: Bearer <token>。
2. API 密钥（保持不变，适用于现有集成）：调用方通过 X-API-Key（或 Authorization: Bearer estevao_…）发送自己的密钥。使用 ESTEVAO_MCP_ALLOW_API_KEY_HEADER=false 可禁用此模式。
3. OAuth 2.1（公共部署推荐）：调用方发送由此服务端签发的访问令牌。当以下 OAuth 变量全部设置后，此模式即启用。

OAuth 配置

变量	必需	用途
MCP_PUBLIC_URL	是	公共源站，例如 https://mcp.caminhoanglicano.com.br。也是 OAuth 颁发者
MCP_ENCRYPTION_KEY	是	32 字节（openssl rand -hex 32）——用于加密存储的 API 密钥
DEVELOPER_FIREBASE_PROJECT_ID	是	开发者门户的 Firebase 项目（不是移动应用）
FIREBASE_API_KEY / FIREBASE_AUTH_DOMAIN	是	授权同意页面使用的 Web 配置
DATABASE_URL	强烈建议	用于客户端、授权码、令牌和密钥保险库的 Postgres。若未设置，状态会保存在内存中，并在重启后丢失
MCP_DATABASE_SSL	否	强制数据库连接使用 TLS（自动检测）
ESTEVAO_PORTAL_URL	否	授权同意页面显示的开发者门户链接
MCP_ALLOW_CLIENT_ID_METADATA_DOCUMENTS	否	接受 URL 格式的 client_id（默认值为 true）
MCP_FIREBASE_AUTH_PROXY	否	从此源站提供 Firebase 的登录辅助程序（默认值为 true，见下文）
MCP_TRUST_PROXY	否	Express 的 trust proxy（默认值为 1，即一个边缘跳点）。速率限制依据真实客户端 IP

只设置其中部分变量属于配置错误，服务端会拒绝启动，而不会静默退回仅密钥模式。Postgres 架构会在启动时创建。

同源登录（移动设备和 Safari 上必需）

默认情况下，Firebase Web SDK 会在 <project>.firebaseapp.com 上运行其登录辅助程序，该域名与此服务的源不同。Safari 的 ITP（16.1+）、Firefox 以及移动助手使用的应用内浏览器会阻止此流程所需的跨源往返：用户选择 Google 账号后，什么也不会发生。因此，此服务会将 /__/auth/* 反向代理到 Firebase 辅助程序，并将同意页面指向自身源，这是 Firebase 记录的解决方案。出于同样的原因，登录使用整页重定向，而非弹出窗口。

完成以下两项一次性控制台操作即可生效：

1. Firebase Console → Authentication → Settings → Authorized domains：添加 MCP 主机。
2. Google Cloud Console → APIs & Services → Credentials → Firebase 使用的 Web OAuth 2.0 客户端：将 https://<mcp host>/__/auth/handler 添加到 Authorized redirect URIs。

将 MCP_FIREBASE_AUTH_PROXY=false 设为 false，即可恢复默认的跨源行为。

诊断登录失败

登录在用户的浏览器中进行，因此浏览器中的失败不会自行写入日志。同意页面会向 /oauth/diagnostics 发送信标，服务会将其写入标准错误：

[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

只会报告错误代码和标志，不会报告令牌或凭据。

端点：/.well-known/oauth-protected-resource（/mcp 下也有）、/.well-known/oauth-authorization-server、/authorize、/token、/register、/revoke，以及 /oauth/consent 上的同意页面。GET /healthz 会报告当前模式。

安全属性：必须使用 PKCE S256；授权码只能使用一次，并在 60 秒后过期；刷新令牌在使用时轮换；访问令牌是不透明的，且仅以摘要形式存储；令牌绑定到此服务的资源标识符（RFC 8707），否则会被拒绝；Estêvão API 密钥在静态存储时使用 AES-256-GCM 加密。

连接任意 MCP 客户端

该端点采用标准的 Streamable HTTP，并支持 OAuth 2.1 发现，因此任何符合规范的客户端都可以连接。具体如下：

客户端	方法
Claude Code	claude mcp add --transport http estevao https://mcp.caminhoanglicano.com.br/mcp
Claude Code 插件	/plugin marketplace add dodopok/estevao-mcp then /plugin install estevao@estevao
Claude Desktop / claude.ai	设置 → 连接器 → 添加自定义连接器 → 粘贴 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	添加一个类型为 http 的 MCP 服务并填入 URL；编辑器会运行 OAuth 流程
MCP Inspector	npx @modelcontextprotocol/inspector，选择传输方式“Streamable HTTP”，然后粘贴 URL
其他客户端	{"type":"http","url":"https://mcp.caminhoanglicano.com.br/mcp"}

以下互操作性细节让它能够在不同客户端中正常工作：

• 随处可进行发现。 受保护资源元数据同时在根路径和 /mcp 下提供；授权服务器元数据则在 /.well-known/oauth-authorization-server、插入 /mcp 路径的变体，以及两种 OpenID Connect 发现路径下提供。
• 注册。 动态客户端注册（RFC 7591）和客户端 ID 元数据文档都受支持；预先注册 client_id 的客户端也能正常工作。
• 客户端身份验证。 支持 none（公共客户端，最常见的情况），以及供机密客户端使用的 client_secret_post 和 client_secret_basic。
• 范围。 只有一个只读范围 liturgy:read。即使客户端请求无关范围（openid profile、mcp 或不请求任何范围），仍能正常连接。
• CORS。 系统会响应预检请求并公开 WWW-Authenticate，因此基于浏览器的客户端可以读取质询并启动流程。
• 探测。 未经身份验证的 /mcp 上的 GET/DELETE 请求会返回身份验证质询，而不是简单的 405，因此在身份验证前进行探测的客户端仍能发现此流程。

基于密钥部署时的客户端配置

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

额外环境变量：PORT（默认值为 3333）、ESTEVAO_MCP_ALLOWED_HOSTS（逗号分隔；启用 DNS 重绑定保护）。

适用于 Codex、Claude 及其他客户端的插件

仓库中包含一个位于 plugins/estevao 的通用软件包，其中包含 Codex 和 Claude Code 的清单，以及共享的 MCP 配置。该软件包指向托管服务，因此连接使用 OAuth，无需复制 API 密钥。

Claude Code 配置：

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

Codex CLI 配置：

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

请参阅开发者门户中的可视化集成指南。同一端点适用于任何兼容 Streamable HTTP 和 OAuth 2.1 的 MCP 客户端。

开发

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

发布

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

npm 的 version 生命周期钩子（scripts/sync-version.ts）会确保 server.json 保持同步，并强制执行注册表 100 字符的描述长度限制。服务器对外公布的 MCP 版本在构建时取自 package.json。

server.json 同时列出了托管端点（remotes）和 npm 软件包（packages），因此注册表客户端可以任选其一。请确保托管 URL 与实际部署保持一致。

或者，当 GitHub Actions 可用且配置了 NPM_TOKEN 密钥后，仅需执行 git push --follow-tags 即可触发发布工作流（npm 发布附带来源证明，并通过 GitHub OIDC 发布到 MCP 注册表）。

许可证

MIT