estevao-mcp

estevao-mcp

Estêvão API 用の MCP（Model Context Protocol）サーバーです。Ordo アプリを支える典礼エンジンです。Claude やあらゆる MCP クライアントに、正確な英国国教会の典礼データを提供します。暦（実際の優先順位規則を含む）、聖書日課、そして複数の『祈祷書』／『共通祈祷書』版に対応した、毎日の礼拝全体を組み立てます。

クイックスタート

ホスト型（管理するキーは不要） — ブラウザーが開いたら、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]

祈祷書ごとの設定

日付を対象とするツールは、API に転送する preferences オブジェクトを受け取ります。これにより、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	はい	同意画面で使用するウェブ設定
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、エッジホップ 1 つ）。レート制限では実際のクライアント IP を基準にします

これらの一部だけを設定すると設定エラーになり、サーバーはキーのみのモードに暗黙的にフォールバックせず、起動を拒否します。Postgres のスキーマは起動時に作成されます。

同一オリジンでのサインイン（モバイルと Safari では必須）

デフォルトでは、Firebase Web SDK は <project>.firebaseapp.com 上でサインイン用ヘルパーを実行します。このオリジンはこのサーバーとは異なります。Safari の ITP（16.1 以降）、Firefox、およびモバイルアシスタントが使用するアプリ内ブラウザーでは、このフローに必要なクロスオリジンの往復がブロックされます。ユーザーが Google アカウントを選んでも、その後何も起こりません。そのため、このサーバーは /__/auth/* を Firebase ヘルパーにリバースプロキシし、同意画面のオリジンを独自のものに設定します。これは Firebase が案内している解決方法です。同じ理由から、サインインにはポップアップではなく、ページ全体のリダイレクトを使用します。

これを機能させるには、コンソールで次の 2 つの手順を一度だけ行います。

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 を設定します。

サインイン失敗の診断

サインインはユーザーのブラウザーで実行されるため、そこで失敗しても、それだけではログに記録されません。同意画面は /oauth/diagnostics にビーコンを送信し、サーバーはそれを 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

報告されるのはエラーコードとフラグのみで、トークンや認証情報は報告されません。

エンドポイント：/.well-known/oauth-protected-resource（/mcp 配下にもあります）、/.well-known/oauth-authorization-server、/authorize、/token、/register、/revoke、および /oauth/consent の同意画面。GET /healthz はアクティブなモードを報告します。

セキュリティ特性：PKCE S256 は必須です。認可コードは 1 回のみ使用でき、有効期限は 60 秒です。リフレッシュトークンは使用時にローテーションされます。アクセストークンは不透明で、ダイジェストのみが保存されます。トークンはこのサーバーのリソース識別子（RFC 8707）に紐付けられ、それ以外の場合は拒否されます。また、Estêvão API キーは保存時に AES-256-GCM で暗号化されます。

任意の MCP クライアントを接続する

エンドポイントは OAuth 2.1 ディスカバリーに対応した標準の Streamable HTTP なので、仕様に準拠したクライアントであれば接続できます。具体的には、次のとおりです。

クライアント	方法
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	設定 → コネクター → カスタムコネクターを追加 → 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 の 2 種類のディスカバリー形式で提供されます。
• 登録。 動的クライアント登録（RFC 7591）とクライアント ID メタデータドキュメントの両方に対応しています。client_id を事前登録するクライアントも使用できます。
• クライアント認証。 none（パブリッククライアントで一般的な方式）と、機密クライアント向けの client_secret_post および client_secret_basic の両方に対応しています。
• スコープ。 読み取り専用スコープは liturgy:read の 1 つだけです。無関係なスコープ（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、その他のクライアント向けプラグイン

リポジトリには、Codex と Claude Code 用のマニフェストおよび共有 MCP 設定を含む、汎用パッケージ plugins/estevao が含まれています。このパッケージはホストされたサーバーを参照するため、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 は実際のデプロイに合わせて更新してください。

または、NPM_TOKEN シークレットを設定した GitHub Actions が利用可能になれば、git push --follow-tags だけでリリースワークフローが起動します（provenance 付きの npm と、GitHub OIDC 経由の MCP レジストリ）。

ライセンス

MIT