Ryan Lindsey

ryanlindsey.me

ryanlindsey.me を支えるコードです。Cloudflare 開発者プラットフォーム上の Astro サイトに加え、mcp.ryanlindsey.me でリモート MCP サーバーを提供する 2 つ目の Worker があります。1 つのリポジトリから、2 つの Worker をデプロイし、D1、KV、R2、Queues、Analytics Engine の各リソースを共有します。

このサイトは、人とエージェントがそれぞれ別の入口から同じコーパスを読めるように構築されています。

ソースコードを公開しているので、構築方法を確認できます。LICENSE ファイルはありません。これは見落としではなく、意図したものです。ライセンスがない場合、すべての権利が留保されるため、ここにあるものは再利用が許諾されていません。

デプロイは main から Workers Builds で実行され、CI にデプロイ手順はありません。CLAUDE.md には、コマンド、編集前に知っておくべき注意点、そして一見奇妙に見える部分の背景にある理由など、作業に必要なメモが記載されています。

エージェントの方へ

契約上安定している 4 つのエントリーポイント：

エントリーポイント	内容
/llms.txt	厳選されたインデックスで、最初に確認する場所です
/.well-known/ard.json	ARD マニフェストであり、ai-catalog.json としても提供されます
/.well-known/mcp/server-card.json	サーバーカードであり、両方のオリジンで提供されます
https://mcp.ryanlindsey.me/mcp	プロトコルのエンドポイントそのものです

このファイルにはほかのエンドポイントを記載していません。その省略こそが、読む価値のある部分です。このサイトが公開するすべてのエンドポイントは、src/lib/discovery/surface.ts にある ADVERTISED_SURFACE という 1 つのリストに含まれています。これは API カタログと ARD マニフェストの両方として公開され、tests/discovery-catalog.test.ts で検証されています。ここに表を載せると、テストスイートの外に 2 つ目の一覧ができ、エンドポイントが移動した途端に内容がずれてしまいます。このファイルを信頼するのではなく、カタログを取得してください。

意図的にそのリストに含めていないものが 1 つあります。要件により、/fit とその配下はすべて一覧に載せません。カタログとは、作成者が興味深いと考えるパスを公開する一覧なので、そこに載せれば非掲載の意味がなくなってしまいます。

どのように連携するか

flowchart TB
  person(["person"])
  agent(["agent"])

  subgraph site["site Worker (ryanlindsey.me)"]
    S["pages, posts, case studies, résumé<br>markdown variants, llms.txt, feeds<br>well-known catalogs<br>chat page and the form surfaces"]
  end

  subgraph mcpw["MCP Worker (mcp.ryanlindsey.me)"]
    G{"grant resolved<br>here, and only here"}
    T["/mcp, the chat stream,<br>the fit engine"]
    R[["rate limiter<br>Durable Object"]]
    G --> T
    T -->|every tool call spends budget| R
  end

  P[("R2_PRIVATE")]

  person --> site
  agent --> site
  agent --> mcpw
  site -->|service binding| mcpw
  mcpw -->|reads published documents| site
  T -. "private-docs.ts, the only reader" .-> P

2 つの Worker に分けているのは、見た目だけの理由ではありません。サイトの設定に ai バインディングがあると、astro build がリモートプロキシセッションを開始しますが、認証情報を持たない CI では認証できません。そのため、推論は 2 つ目の Worker で行い、サイトからはサービスバインディング経由でアクセスします。それぞれの Worker が相手を指定しています。この循環は意図的なもので、合法です。サービスバインディングは Worker の定義時ではなく、呼び出し時に解決されるためです。

この図は意図的に不完全です。構造を示しつつ、各 Worker が使用するストレージ、呼び出すモデル、キューのコンシューマー、cron などは省いています。サイトでは、デプロイ済みの構成を示す独自の図を /ops で公開しています。その図は、このリポジトリでアーキテクチャを記述する唯一のファイル src/lib/architecture.ts を基にしています。また、このページではシステムの最近の動作状況とコストも、ここで断定するのではなく、リクエスト時に読み取って報告します。

このリポジトリが保証すること

4つの主張それぞれに、保証ではなく、その根拠を示すファイルを対応させています。

主張	強制するもの
プライベート層はフィルターではなく、分離された領域です。公開ドキュメント層の環境変数インターフェースには、プライベートバケットが一切記載されていません。	tests/tier-private-docs.test.ts、型レベルでの検証
認証されていない tools/list では、アクセス制限されたツール名を列挙できません。また、名前を指定して呼び出しても、拒否されたことを明かすのではなく、不明なツールとして応答します。	tests/mcp-gated.test.ts の「権限付与なしでの不可視性」
テストが Workers AI、Vectorize、Browser Rendering、または実際のシークレットにアクセスすることはありません。デプロイ設定でオーバーライド変数は宣言されておらず、認識されない値を渡すと例外が発生します。	tests/workers.ts で一箇所に設定し、tests/mcp-env.test.ts で両方のデプロイ設定から除外しているほか、src/lib/turnstile.ts のように呼び出し時に認識されない値を渡すと例外が発生します
MCP Worker のバインディング一覧は、Wrangler 設定との間で、どちらの方向にもずれません。	tests/mcp-env.test.ts

このコードベースを5分で理解する

読む順に4つのファイルを紹介します。これらを読めば、残りの内容も理解できます。

1. src/lib/discovery/surface.ts：このサイトが公開するすべてのエンドポイントが1つのリストにまとめられています。2つではなく1つのリストにしている理由も記載されています。
2. src/lib/tier/grant.ts：トークンを検証する唯一の場所です。サイト Worker はトークンのコピーを保持せず、不透明な文字列として扱い、サービスバインディングを介して問い合わせます。そのため、同じ処理を実装する箇所は1つで済み、2つの実装を一致させる必要がありません。
3. tests/workers.ts：テストスイートが workerd 内で実際の Workers を起動する理由と、アクセスしない対象を説明しています。
4. src/components/ArchitectureDiagram.astro：出力ではなく、ヘッダーを読んでください。そのヘッダーには、最初の草稿にあった2つの主張が誤りだったこと、誤りの内容、そこから得た教訓が記されています。このリポジトリのほかの部分のコメントを知るうえで、よい例です。

リリース

release-please は main を監視し、次のバージョンと変更履歴を含むリリース用プルリクエストを常に開いておきます。このプルリクエストをマージすると、リリースにタグが付けられ、公開されます。

プルリクエストはスカッシュマージされるため、release-please が読み取るコミットの件名はプルリクエストのタイトルです。認識される type(scope): summary 形式のプレフィックスがないタイトルは、通知なくスキップされます。バージョンの更新も変更履歴への記載も行われません。feat はマイナーバージョンの更新、fix と perf はパッチ更新、type!: または BREAKING CHANGE: フッターはメジャーバージョンの更新です。タイプの全一覧は、release-please-config.json の changelog-sections にあります。