Sigao Li — personal MCP server

sigaoli.com

Sigao Li の個人ウェブサイト — AI プロダクトマネージャー · 空間データサイエンティスト。 地図からモデルへ、そしてその間にあるプロダクトへ。

英語版（/）と中国語版（/zh/）に対応しています。Astro + Tailwind CSS v4 + GSAP で構築し、 GitHub Actions 経由で GitHub Pages にデプロイしています。2026-06-11 に公開され、以前の Jekyll（academicpages）サイトに置き換わりました。

主な特長

• 地図をモチーフにした生成キャンバスエフェクト — インタラクティブなパーティクルフィールド（ホーム）、等高線で描く地形（仕事）、流れ場を使った「タイムラインとしての川」（CV）、地理ネットワークのアークマップ（写真）。すべてプレーンな Canvas／SVG で実装し、動きを抑える設定とモバイル向けの代替表示を備え、60fps に調整しています
• ドットで描いた世界地図 — Natural Earth から抽出した陸地に、6 か国で GPS データから抽出した 88 個の写真撮影地点を表示。マーカーをクリックすると、その国のギャラリーが開きます
• デジタルドアキャットの Zoe — Sigao の猫（驺虞）が、AI 生成のクロマキー処理済み VP9-alpha 動画クリップのセットとして、全ページの隅に登場します。クリップは共通のアンカーポーズに固定され、状態マシンによって制御されます。無視されると居眠りし、ページ切り替えに反応し、入力中は耳を傾け、アシスタントの応答中は「返事を入力」し、いくつかのイースターエッグも用意されています（制作ハンドブックは docs/ にあります）
• 組み込み AI レイヤー — 全ページに浮かぶチャットアシスタント（Zoe が案内役として登場）を備えています。質問に応じて最も関連性の高いページを 1 つ提案し、再訪したユーザーには名前で挨拶します（名前はオプトインで、ユーザー自身のブラウザーにのみ保存されます）。さらに、ページと同じ情報源からビルド時に生成されるナレッジパックを使った個人用 MCP サーバーもあります（詳細は以下を参照）
• 機械可読性を考慮した設計 — /llms.txt、/llms-full.txt、/resume.json（JSON Resume）、/knowledge.json、/.well-known/mcp.json、JSON-LD、そして AI クローラーを明示的に歓迎する robots.txt を用意しています
• 写真の整理も自動化 — _inbox/ に高解像度のオリジナル写真を入れてコミットするだけです。コミット前フックが Natural Earth のポリゴンと照合して座標から国を判定し、オリジナルを git の管理対象外にアーカイブします。最大辺が 4096px のマスター画像を作成して EXIF を削除し、ビジョンモデルに英語と中国語のキャプションを依頼して、すべてを photos.json に登録します。地図、件数、アシスタントのナレッジも、これをもとに更新されます
• どちらかの言語を編集すると、もう一方も連動 — 中国語版または英語版を編集してコミットします。フックがどちらを変更したかを判定し、その編集によってもう一方の言語で伝える内容も変わるか、モデルに確認させます。一方の言語を推敲しても他方には手を加えません。事実が変わった場合は書き直すのではなく修正するため、手作業で選んだ表現が保たれます。両方を同じコミットで編集した場合は、すでに手作業で対応済みとみなされます
• Lighthouse（モバイル）：すべてのカテゴリで 96～100。Cookie はゼロ、有料サービスは不使用で、平易な言葉で書かれたプライバシー通知を /privacy に掲載しています

コマンド

コマンド	操作
npm run dev	localhost:4321 で開発サーバーを起動します（Astro 7 はデーモンとして実行するため、npx astro dev stop で停止します）
npm run build	dist/ に本番ビルドを作成します
npm run preview	本番ビルドをローカルで配信します
npm test	両方のフックパイプラインの単体テストです（node --test。追加の依存関係は不要です）
npm run ingest	写真を手動で取り込みます。通常はコミット前フックが実行します。処理を確認する場合に便利です
npm run sync	バイリンガル同期を手動で実行します。同様に、通常はフックが実行しますが、処理を確認する場合に使います
node scripts/check-links.mjs	dist/ 内の内部リンク整合性をチェックします
node scripts/verify-nav.mjs など	Playwright の操作テストスイートです（ローカルサーバーに対して実行します）
npm run dev（worker/ 内）	localhost:8787 でチャットと MCP Worker を起動します（wrangler。シークレットは worker/.dev.vars に設定し、コミットしないでください）
node scripts/verify-chat.mjs	チャットウィジェットの E2E テストです（両方の開発サーバーを起動しておく必要があります）
node scripts/verify-zoe.mjs	Zoe のアクションステートマシンの E2E テストです（分単位のタイマーを短縮するには、ローカルで ?zoe-fast を追加します）
node scripts/verify-typeroute.mjs	インテント駆動のタイピング動画とバイリンガルの 404 ページの E2E テストです

Zoe の状態を待機する Playwright テストスイートでは、時計を固定してください （Date.prototype.getHours = () => 14）。23:00 から 06:00 の間はセッションが スリープ状態で始まり、state が idle に到達しないため、実行がタイムアウトします。

Zoe のクリップを追加するときは、誰がいつプリウォームするかも同時に決めてください。 再生時に初めて取得するクリップは低速接続で停止し、デコードされるまでステージには何も表示されません。これまでにプリウォームを忘れたことがすでに 3 回あります。warm() に渡すのは ZOE キー（sitToLoaf）ではなく、ファイル名（sit-to-loaf）であることに注意してください。

チャットパネルはナビゲーションのたびに再構築されます。transition:persist が維持するのは Zoe のステージであり、パネルではありません。**パネルの DOM 内だけにあるものは、訪問者がリンクをクリックした瞬間に失われます。**ストリーミング応答、ガイダンスチップ、未送信の下書きには、それぞれモジュール状態と paint() を通じて復元する仕組みが必要でした。チップは誰かが気づくまで数週間失われたままでした。ここに永続 UI を追加するときは、まず 2 つの質問に答えてください。paint() はどう再構築するのか、履歴とともに sessionStorage に保存すべきか。ジオメトリはパネルが表示されてから測定してください。非表示の間は scrollHeight が 0 なので、気づかないうちに height: 0px が書き込まれます。

Turnstile は /chat と /classify を保護します。/mcp は決して保護してはいけません。 このエンドポイントは、マシンが Sigao のプロフィールを読み取れるようにするためのものです。公式レジストリに登録されています。Turnstile はマシンを阻止するためのものです。また、配信にコストはかかりません。ツールはナレッジパックを読み取り、モデルを呼び出すことはありません。静的なエンドポイント（llms.txt、knowledge.json、.well-known/mcp.json）は Pages が配信するため、Worker には到達しません。

ローカルでは、Turnstile に Cloudflare の常に通過するテストキーを使います。site.ts の sitekey は import.meta.env.DEV の背後にあり、secret は worker/.dev.vars にあります。本番キーはヘッドレスブラウザーを拒否します。まさにそれが役割であり、それを使うと実際の Worker を操作するすべてのテストスイートが失敗します。本番用の secret は本番環境にのみ存在し、wrangler secret put で設定します。覚えておくべき点として、本番環境での正常な経路はスクリプトから検証できません。そこに到達するには、実際のブラウザーを使う人間が必要です。自動テストではゲートが有効であることは引き続き確認できます（認証情報なしのリクエストは 403 を返す必要があります）。

src/
├── pages/            # en routes + zh/ mirrors; llms.txt / resume.json / knowledge.json endpoints
├── components/       # Nav, Hero, WorldMap, Lightbox, CommandK, ChatWidget …
│   └── pages/        # shared page bodies rendered by both locales
├── content/          # cases & research (en) + cases-zh & research-zh (generated, reviewed)
├── data/             # cv.json / cv.zh.json / photos.json (GPS + bilingual alts)
│   └── knowledge/    # persona sources for the AI assistant (about / faq / guidelines / boundaries)
├── lib/              # i18n dict, GSAP lifecycle helper, site config
│   └── knowledge/    # knowledge-pack pipeline (same-source layers + build-time privacy guard)
└── assets/           # photo originals (optimized at build; originals never shipped)
worker/               # Cloudflare Worker: /chat (SSE) + /classify (intent) + /mcp (MCP server)
└── src/core/         # runtime-agnostic logic; Cloudflare specifics live only in src/adapter/
public/zoe/           # Zoe's clip library (600p VP9 alpha, lazy-loaded; idle loads first)
docs/                 # zoe-production-handbook.md — clip production specs & prompt cards

AI レイヤー

1 つのナレッジレイヤーに 3 つの提供先があります。受動的なクローラー向けの /llms-full.txt、人間向けのチャットアシスタント（POST /chat、SSE）、訪問中のエージェント向けの MCP サーバー（/mcp、Streamable HTTP、認証なし — ツール：get_profile / list_experience / get_case_study）です。いずれも api.sigaoli.com（Cloudflare Worker、コードは worker/）から提供されます。ナレッジパック（/knowledge.json）は、ページと同じソース（ペルソナの Markdown、cv.json、事例研究、写真の統計情報）からビルド時に組み立てられるため、コンテンツを編集すると、次回のデプロイ時に手作業なしですべての提供先に反映されます。プライバシーガードにより、機密情報のパターン（電話番号、ID、座標）がパックに漏れるとビルドが失敗します。

チャットでは、各応答と並行して軽量なインテント分類器（POST /classify、小規模なモデル）を実行し、最も関連性の高いページを 1 つ提案します。また、再訪問者の名前を記憶できます。どちらも訪問者自身のブラウザー内だけに保持され（オプトイン、［Forget me］から消去可能）、サーバーには保存されません。EU／EEA／英国の訪問者は、チャットと分類の接続先が EU ホストのプロバイダーとなり、中国直結の API には接続されません。サイトが保存・送信する内容については、/privacy でわかりやすく説明しています。

コンテンツの編集

• 事例研究／研究：どちらかの言語を編集してコミットします。pre-commit フックはどちらの言語が変更されたかを判定し、その編集によってもう一方に書く内容も実際に変わるかをモデルに確認してから、必要な場合にのみもう一方を修正します。既存の翻訳も渡すため、事実の変更箇所だけを直し、ほかの表現は書き換えずに済みます。一方の言語を推敲しても、もう一方はそのままです。1 回のコミットで両方を編集した場合は、手作業で対応済みとして扱われます。docs/bilingual-sync-design.md を参照してください。
• CV：src/data/cv.json または cv.zh.json を編集します。フックは項目ごとにもう一方を同期するため、1 つの職歴を変更しても、ほかの項目には影響しません。タイムライン、/resume.json、/llms-full.txt はすべてこのファイルから描画されます。あわせて public/files/pdf/CV__Sigao_Li.pdf も差し替えてください。（skills は意図的に同期対象から除外されています。2 つの言語では異なる形式を使い、レンダラーが両方に対応するためです。）
• UI 文字列とヒーローコピー：src/lib/i18n.ts にある手書きのバイリンガル辞書を編集します。
• 写真：フル解像度のオリジナル画像を _inbox/ に入れてコミットします。pre-commit フックが GPS 情報に基づいて写真を分類し、オリジナルを _originals/ にアーカイブし（コミット対象外）、最大辺が 4096px の配信用マスターを生成し、ビジョンモデルで二言語のキャプションを書いて、src/data/photos.json に登録します。GPS 情報のない写真は _inbox/<country-id>/ に入れてください。写真の枚数、地図、AI ナレッジパックには、すべて photos.json の内容が自動的に反映されます。docs/photo-ingest-design.md を参照してください。
• AI アシスタントのペルソナ：src/data/knowledge/*.md を編集します。ナレッジパックはデプロイのたびに再構築され、アシスタントには約 10 分以内に反映されます（Worker 側のキャッシュ TTL）。
• Zoe のアクション：素材クリップはリポジトリの外にあります。パイプライン（scripts/zoe-board2.mjs → zoe-qc2.mjs → zoe-prod2.mjs）でキー付け、QC、ミラーリング、エンコードを行い、public/zoe/ に出力します。新しいアクションの追加は、クリップ 1 本と ChatWidget.astro の ZOE テーブルへの 1 行の追加です。仕様とプロンプトカードについては、docs/zoe-production-handbook.md を参照してください。

ローカルセットアップ

pre-commit フックから 2 つのチェーンが実行されます。写真の取り込みと、2 言語間の同期です。クローンした後、追跡対象のフックディレクトリを一度だけ git に指定します。

git config core.hooksPath .githooks

これを設定しないと、どちらも実行されません。_inbox/ に入れた写真はそのまま残り、2 つの言語の同期も止まります。どちらも処理するものがなければすぐに終了するため、通常のコミットには影響しません。

どちらのチェーンにも .env が必要です（.env.example をコピーします）。キャプション、翻訳、古さのチェックに使うモデル呼び出しは、すべてこのゲートウェイを経由します。

ロックファイルの再生成。 package-lock.json は Linux 上で作成する必要があります。npm は実行中のマシンで解決できるオプション依存関係だけを記録するため、Windows で作成したロックファイルには runner で sharp が必要とする依存関係が含まれず、npm ci のインストールが拒否されます。ここで依存関係を変更した後は、Actions タブから Relock on Linux ワークフローを実行してください。ロックファイルを再生成し、npm ci が動作することを確認して、結果をコミットします。通常のプッシュでは必要ありません。忘れた場合は、verify ジョブが知らせてくれます。

デプロイ

master へのプッシュ → deploy.yml がビルドして Pages にデプロイします。v2 へのプッシュはデプロイせずにビルドします（検証）。

さらに 2 つのワークフローがゲートとしてではなく監視用に動作します。どちらも失敗時にメールを送信し、リリースを止めることはありません。

ワークフロー	実行時期	内容
verify.yml	プッシュのたび	ビルドし、内部リンクをチェックした後、本番ビルドに対して 8 つのブラウザースクリプトを実行します。失敗時はスクリーンショットと Playwright のトレースがアップロードされます。トレースを trace.playwright.dev に読み込むと、実行をフレームごとに再生できます
audit.yml	毎週月曜日	サイトと Worker に対して npm audit を実行します

以前は audit がビルドを止めていました。このチェックはリポジトリではなく、その日のアドバイザリデータベースを参照するため、何も変更していないコミットが一晩で成功から失敗に変わることがあります。実際、それが 9 月 13 日に写真のバッチ公開を止めました。メールで通知を受け取ることには価値がありますが、ブロックされる必要はありません。

Worker は個別にデプロイします。cd worker && npx wrangler deploy（シークレットは wrangler secret put で設定します。カスタムドメイン api.sigaoli.com は Cloudflare ダッシュボードで紐付けます）。1 つのバッチで両方を変更する場合は、Worker を先にデプロイしてください。チャット UI はそのエンドポイントを呼び出すため、サイトを先にプッシュすると、その呼び出しが 404 になる時間が一時的に発生します。

デプロイがすべてのエッジロケーションに反映されるまで、最大 1 分かかります。すぐに確認すると前のバージョンが読み込まれます。これまで 2 回、何も問題がないのにデプロイが壊れたように見えたことがあります。少し待ってから確認してください。

チャットの 1 日あたりの使用状況は https://api.sigaoli.com/usage で確認できます（過去 7 日間のデータと、今日上限に達したかどうかが表示されます）。上限は worker/src/core/quota.ts の DAILY_CAP です。上限に達すると、Cloudflare Email Routing 経由で一度だけメールが送信されます。

⚠️ 「Sync fork」は絶対にクリックしないでください。 このリポジトリは academicpages のフォークとして始まったため、同期すると master が上流のテンプレートにリセットされます。再びそうなった場合は、次のコマンドを実行してください。 git push --force origin <good-commit>:master