saagarpatel.dev Portfolio

portfolio-mcp

saagarpatel.dev のエージェントネイティブなレイヤーです。HTML をスクレイピングする代わりに、あらゆる AI エージェントが Saagar の執筆記事、プロジェクト、公開しても安全なリポジトリのプロフィール、ベンチマーク結果を直接照会できる Model Context Protocol サーバーです。

読み取り専用。ステートレス。公開。認証なし、トラッキングなし、データベースなし、実行時の外部通信なし。

構成

ウェブサイトは純粋な静的サイトのままです。このサーバーは、後付けされたバックエンドではなく、隣接するコンポーネントです。

• レイヤー 0（portfolio-index リポジトリ内）：ビルド時に、静的なマシン向けコーパス（corpus-index.json、ドキュメントごとの corpus/<id>.json、.well-known/mcp.json）と、存在する場合は公開しても安全なリポジトリプロフィールのアーティファクトを生成し、HTML とともに提供します。すでに公開されています。
• レイヤー 1（このリポジトリの src/index.ts）：ステートレスな Cloudflare Worker です。レイヤー 0 のコーパスをバンドルに組み込み、MCP（ストリーマブル HTTP、WebStandardStreamableHTTPServerTransport）経由で提供します。実行時のフェッチはありません。
• レイヤー 2（このリポジトリの src/stdio.ts）：同じサーバーを stdio 経由で提供し、npx saagar-portfolio-mcp を使ってローカルで実行します。ツール、リソース、プロンプトの構成は同一です。

共有コア（src/server.ts）はトランスポートに依存せず、両方のレイヤーがこれをラップします。

ツールの構成

すべて読み取り専用です（readOnlyHint: true）。URL やファイルシステムのパスを受け取るツールはありません（SSRF／データ流出の経路はありません）。

ツール	目的
search	コーパス全体を対象とする BM25 検索。任意の section フィルターと limit を指定できます
get_document	id で指定した 1 つのドキュメントの Markdown 全文
list_corpus	目次。任意の type フィルターを指定できます
get_profile	「この人物は誰か」を示すカード（about／now／uses）
list_projects	厳選された公開しても安全なプロジェクトと匿名化された集計データ
list_repo_profiles	最新情報と証拠数を含む、公開しても安全なリポジトリプロフィールのインデックス
get_repo_profile	repoId 引数で指定したリポジトリの回答プロフィール
get_operant_results	公開されている、サニタイズ済みの OPERANT キャリブレーション結果（モデルごとの OCS）

ドキュメントはリソース（portfolio://essays/{slug}、portfolio://book/{slug}、portfolio://notes/{slug}、portfolio://profile）としても公開されます。また、2 つのプロンプトがあります。 introduce_saagar と summarize_writing_on（実行時の search に基づきます）。

検索

組み込みインデックスを使った BM25 検索です（v1 では埋め込みを使用しません。コミット済みのコーパスには 166 件のドキュメントが含まれ、意味の解釈は呼び出し元の LLM が担います）。タイトルには高い重みが付けられています。埋め込みは、検索品質が不十分だと判明した場合にのみ追加する、測定に基づくフェーズ 3 のアップグレードです。

構成

src/
  types.ts            corpus + projects + operant shapes
  bm25.ts             dependency-free BM25 + snippet (pure)
  tools.ts            createTools(corpus) -> the 8 tools (pure, injectable)
  corpus.ts           loads the baked corpus + accessors
  corpus.generated.ts AUTO-GENERATED by build:corpus
  server.ts           buildServer(): shared MCP core (tools + resources + prompts)
  index.ts            Cloudflare Worker transport (streamable HTTP)
  stdio.ts            Layer 2 stdio transport (the npx CLI)
scripts/
	build-corpus.mjs    bakes Layer 0 and local OPERANT inputs into corpus.generated.ts
  probe-mcp.mjs        probes an MCP HTTP endpoint (saagar-mcp-kit driver + domain calls)
  audit-mcp.sh        connected MCPAudit scan of this server (dogfood)
test/                 vitest: bm25, tools, full-protocol server tests

開発

リポジトリのルートから、.node-version と package.json に固定されている Node と npm のバージョンを使用してください。チェックアウト済みの公開しても安全なコーパスだけで通常のチェックを実行できます。隣接リポジトリのチェックアウト、ローカルのポートフォリオインポート、署名キー、Cloudflare の認証情報は不要です。

npm ci
make check

make check は lint、フォーマット検証、型チェック、テスト、stdio ビルドとプロトコルテスト、スモークテスト、パリティチェック、パッケージ内容のチェックを実行します。同じ一連のチェックについてはCIを参照してください。npm run dev はローカル Worker を起動します。

npm run build:corpus は隣接リポジトリのチェックアウトまたは明示的なネットワーク URL からソースを再生成します。URL モードのビルドでは、OPERANT のビルド入力が公開されていないため、OPERANT は除外されます。通常のフィクスチャ検証にコーパスの生成は不要です。npm run probe:mcp はデフォルトで稼働中の Worker を対象とし、接続監査ではローカル Worker を起動して、別途インストールされた mcp-audit CLI を呼び出します。これらはローカルゲートとは分けて実行してください。デプロイと署名は、以下で説明するように運用担当者の承認が必要です。

MCP Inspector を使って、どちらのトランスポートも調査できます。

npx @modelcontextprotocol/inspector http://localhost:8787/mcp   # Layer 1 (HTTP)
npx @modelcontextprotocol/inspector node dist/stdio.js          # Layer 2 (stdio, after build:cli)

デプロイ（レイヤー 1）

npm run build:corpus && npm run deploy   # wrangler deploy
npm run probe:mcp                        # post-deploy live MCP readback

オペレーターの承認が必要です（Cloudflare 認証が必要です）。v1 は引き続きデフォルトの portfolio-mcp.<account>.workers.dev URL にデプロイされ、npm run probe:mcp はデフォルトでこの安定した Worker URL を使用します。公開ディスカバリーでは、検証済みのカスタムエンドポイント https://mcp.saagarpatel.dev/mcp が告知されます。デプロイのたびに、.well-known/mcp.json を変更する前に、Worker と ウェブサイトのマニフェスト／読み戻しパスの両方を検証してください。

wrangler.jsonc では workers_dev: true を固定し、今後カスタムドメインを試す際にも公開 Worker URL が稼働し続けるようにしています。ウェブサイトのマニフェストが検証済みの代替エンドポイントにすでに切り替わっていない限り、これを削除しないでください。

公開（レイヤー 2）

npm run build:corpus && npm run build:cli   # -> dist/stdio.js
npm login && npm publish                     # public package: saagar-portfolio-mcp

公開後は、誰でも npx saagar-portfolio-mcp を実行してローカルで使えます（インストール不要）。

マニフェストへの署名（任意の信頼性シグナル）

.well-known/mcp.json に Ed25519 署名を付けることで、エージェントやレジストリが Saagar によって真正に提供されたものか検証できます（saagar-mcp-kit の署名 CLI と Node 組み込みの暗号機能を使用）：

npx mcp-kit-sign gen-key --manifest=../portfolio-index/.well-known/mcp.json  # one-time; private key -> .signing/ (gitignored, NEVER commit)
npm run sign                             # writes <manifest>.sig + publishes mcp-ed25519.pub
npm run sign:verify                      # checks manifest bytes against .sig + public key

--manifest=／--key=／--pub=／--sig= でパスを上書きします。 .sig と mcp-ed25519.pub（秘密鍵は絶対に含めないでください）をマニフェストの隣にある portfolio-index にコミットし、サイトを再デプロイします。マニフェストが変更されたら、必ず sign を再実行してください（配信されるバイト列そのものに署名します）。

監査状況

MCPAudit／mcp-trust（Saagar 独自のツール）に合格するよう設計されています。受信 MCP トランスポートのみを使用し、shell_execution／file_access／destructive／exfiltration はなく、呼び出し元が制御する送信通信もありません（コーパスは組み込み済みです）。すべてのツールには、読み取り専用で、注入不可能な平易な説明が付与されています。bash scripts/audit-mcp.sh で接続スキャンを実行できます。

このサーバーを実際に使ったことで、MCPAudit の部分文字列マッチングに関する誤検知のバグが見つかりました（portfolio:// 内の port に一致していました）。この修正は MCPAudit リポジトリにあり、このサーバーの検出結果は 62 件から 14 件に減りました。実際のツールの範囲は問題なくスキャンされます（high_risk_servers: 0）。

ステータス

スタック

Node.js 24.21.0、npm 12.2.0、TypeScript、Cloudflare Workers、MCP SDK。

既知のリスク

URL モードのコーパスビルドでは OPERANT が除外されます。その入力はローカルのコーパスビルドでのみ利用できます。Worker のデプロイとパッケージの公開は、ローカル検証には含まれません。

次のステップ

オペレーターがデプロイを承認したら、公開済みの MCP エンドポイントと署名済みディスカバリーマニフェストの同期を保ちます。レジストリへの公開は、別途、明示的な承認が必要なリリース操作です。