Portfolio MCP Server

MCP（Model Context Protocol）サーバーで、Cheng-Yun Wuのポートフォリオ（プロジェクト、スキル、履歴書）をツールとして公開します。MCP互換のAIアシスタント（Claude Desktop、Claude.ai Connectors、MCP Inspectorなど）は、ウェブサイトをスクレイピングする代わりに、これらのツールを直接呼び出すことができます。

なぜこれを作ったか

MCPが実際にどのように動作するかを、読むだけでなく理解したいと思ったからです。そこで、自分のポートフォリオサイトのコンテンツを構造化されたツールに変換する小さなサーバーを構築しました。また、これまであまり触れてこなかったDockerと基本的なCI/CDパイプラインを学ぶための、意図的なきっかけでもあります。これらは、私が応募している求人情報で頻繁に登場するスキルです。

Related MCP server: personal-mcp

MCPとは（簡単に）

MCPは（Anthropicによる）オープンプロトコルで、AIアシスタントが外部の「ツール」（名前、説明、スキーマを持つ型付き関数）を呼び出して、トレーニングデータや貼り付けられたドキュメントだけに頼るのではなく、ライブ情報を取得したりアクションを実行したりできるようにします。サーバーは自身のツールを宣言し、MCP対応クライアントはそれらを発見して呼び出すことができます。このプロジェクトはそのようなサーバーの1つで、自身のポートフォリオデータに基づく4つのツールを宣言しています。

ツール

各ツールのdocstringは、AIアシスタントがいつ呼び出すかを判断するために実際に読み取るものです。詳細は src/portfolio_mcp/server.py を参照してください。

カバレッジ: data/projects.json には全31件のポートフォリオ項目が含まれています。7件の詳細なケーススタディ（リリース済みシステム、論文、NSTC研究プロジェクト、受賞論文）と、24件の軽量な項目（その他のコンテスト参加作品、コースレポート、会議論文）です。すべての項目に少なくとも1つのリンクが含まれています。コース段階のレポートや関連論文には、所属する詳細なケーススタディを指す related_project idが含まれており、アシスタントがレポートから完全なストーリーにドリルダウンできます。

アーキテクチャ

Claude Desktop / Claude.ai / MCP Inspector
              │  (stdio locally, or Streamable HTTP remotely)
              ▼
      MCPServer instance (server.py)
              │  registers 4 tools
              ▼
       tools.py  (pure, unit-tested logic)
              │
              ▼
   data_loader.py  →  data/*.json  (projects, skills, resume)

• トランスポート: Streamable HTTP（stdioではありません）。ポイントは、リモートクライアント（例：Claude.aiのConnectors）がローカルで起動されたプロセスだけでなく、公開URL経由でこのサーバーにアクセスできることです。ローカルのClaude Desktop / MCP Inspectorテスト用にstdioもサポートしています。

• データ層: data/ の下にある3つのフラットなJSONファイル。一度ロードされ、キャッシュされます（functools.lru_cache）。データベースはありません。データは小さく、公開されており、変更は稀です。

• ツールロジックとMCP配線: 意図的に分離されています（tools.py vs. server.py）。これにより、MCPサーバーやトランスポートを実行せずにロジックを単体テストできます。

• SDKに関する注意: 公式の mcp Python SDKは、v2.0.0で高レベルサーバーAPIを FastMCP から mcp.server.mcpserver.MCPServer に変更しました。このプロジェクトは mcp>=2.0.0 とその現在のAPIをターゲットにしています。from mcp.server.fastmcp import FastMCP を使用する古いMCPチュートリアルを見たことがある場合、それはv2.0.0以前のAPIであり、pip install mcp で現在入手できるものに対してインポートできません。

プロジェクト構造

portfolio-mcp-server/
├── data/                      # projects.json, skills.json, resume.json
├── src/portfolio_mcp/
│   ├── server.py              # MCPServer app: registers tools, stdio/HTTP entrypoints, /chat route
│   ├── tools.py                # MCP tool logic (testable, no MCP dependency)
│   ├── chat.py                  # /chat: Claude + Tool Runner over the same data, for the site's Q&A widget
│   └── data_loader.py          # cached JSON loading
├── tests/                      # pytest suite run in CI (tools, server security, chat, chat route)
├── Dockerfile                  # python:3.12-slim + uvicorn, Streamable HTTP
├── .github/workflows/ci.yml    # lint (ruff) + test (pytest) on every push
└── claude_desktop_config.json  # example config for local stdio testing

ローカルでの実行

# from the repo root
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

オプションA — stdio、MCP Inspector使用

npx @modelcontextprotocol/inspector python -m portfolio_mcp.server

各ツールを直接呼び出し、リクエスト/レスポンスを検査できるローカルWeb UIが開きます。

オプションB — stdio、Claude Desktop使用

claude_desktop_config.json の mcpServers エントリを自身のClaude Desktop設定（設定 → 開発者 → 設定の編集）にマージし、パスを自分のマシン用に修正してからClaude Desktopを再起動し、「この人が手がけたプロジェクトは？」などと質問してください。

オプションC — Streamable HTTP、ローカル

TRANSPORT=http python -m portfolio_mcp.server
# equivalent — both serve the exact same ASGI app, /chat included:
uvicorn portfolio_mcp.server:app --host 0.0.0.0 --port 8000

テスト

pytest -v
ruff check .

Dockerでの実行

docker build -t portfolio-mcp-server .
docker run -p 8000:8000 portfolio-mcp-server

コンテナは常にStreamable HTTPを提供します（コンテナ化のポイントはこれです — ポータブルで公開可能なユニットであり、1台のマシンに縛られたstdioプロセスではありません）。

デプロイ（Render）

選択したデプロイ先: Render、無料枠。長時間実行されるコンテナ（実行時間制限のあるサーバーレス関数ではない）を実行します。これはStreamable HTTPの永続的な接続に必要であり、開始にクレジットカードは不要です。

1. このリポジトリをGitHubにプッシュします。

2. render.com で: New → Web Service → このリポジトリに接続。

3. Renderが Dockerfile を自動検出し、コンテナとしてビルド/実行します。

4. Free インスタンスタイプを選択 → https://<something>.onrender.com のURLが取得できます。

5. 動作確認:

   npx @modelcontextprotocol/inspector https://<something>.onrender.com/mcp

6. （オプション）RenderのGitHub自動デプロイを有効にすると、git push を main に実行するたびに自動的に再デプロイされます。以下のCIワークフローと組み合わせることで、完全なCI/CDストーリーが完成します。

無料枠の注意: Renderの無料Webサービスは、約15分間アイドル状態が続くとスリープし、次のリクエストで起動するのに30〜60秒かかります。ポートフォリオのデモには問題ありませんが、尋ねられた場合に意図的なコスト/レイテンシのトレードオフとして言及する価値があります。

ライブデプロイ: https://yun-portfolio-mcp.onrender.com/mcp — MCPクライアントをこのURLに接続してください（/mcp パスに注意。ベアドメインは404になります。これは想定内です — Streamable HTTPはその1つのパスのみを提供します）。npx @modelcontextprotocol/inspector https://yun-portfolio-mcp.onrender.com/mcp で自分で確認できます。

これをフォークする場合: server.py のHostヘッダー許可リストはデフォルトで yun-portfolio-mcp.onrender.com にハードコードされています（DNSリバインディング保護により、他のHostヘッダーは421で拒否されます）。MCP_ALLOWED_HOSTS 環境変数を自身のデプロイのホスト名に設定するか、ALLOWED_HOSTS を直接編集してください。

チャットエンドポイント（/chat）— ポートフォリオサイトのQ&Aウィジェット

同じRenderサービス上の2つ目の独立したドアで、yunwcy.github.io に埋め込まれたプレーンなチャットウィジェット用です。上記のMCPプロトコルサーフェスの一部ではありません。 ブラウザが {"message": "..."} を /chat に POST すると、サーバーはAnthropic Tool Runnerを使用して、Claudeに同じ4つのツールのどれを呼び出すかを決定させ（MCPハンドシェイクなしで tools.py を直接呼び出す）、{"reply": "..."} を返します。完全な実装については src/portfolio_mcp/chat.py を参照してください。

なぜこれに実際のバックエンドが必要で、GitHub Pagesだけではできないのか: 自然言語で応答するには、LLMが質問を見てどのツールを呼び出すかを決定する必要があり、それにはAnthropic APIキーが必要です。そして、キーは静的サイトのクライアントサイドJSに決して置くことができません。誰でもソースを表示してアカウントを使い潰せるからです。/chat はキーをサーバーサイド（Renderの環境変数。ブラウザには決して送信されません）に保持し、ブラウザが必要とするウィジェットのみをGitHub Pagesに配信します。

セットアップ（このエンドポイントが機能する前に必要）:

1. Anthropic Console からAPIキーを取得し、Renderの ANTHROPIC_API_KEY 環境変数として追加します（Renderダッシュボード → このサービス → Environment）。これがない場合、/chat はサーバーをクラッシュさせる代わりに 503 {"error": "not_configured"} を返します。

2. CHAT_ALLOWED_ORIGINS（カンマ区切り）がCORSを制御します。デフォルトは https://yunwcy.github.io です。ウィジェットが別の場所にある場合は設定してください。

3. ANTHROPIC_CHAT_MODEL（デフォルト claude-opus-5）— 最も強力な汎用選択肢ですが、これはシンプルで、潜在的に高トラフィックで、コストに敏感な公開ウィジェットであるため、claude-haiku-4-5 はここで特に検討に値します。これはハードコードされず、サーバーを実行する人に委ねられた意図的な選択です。

4. CHAT_RATE_LIMIT_PER_HOUR（デフォルト 30）— シンプルなインメモリのIPごとの制限で、1人の訪問者が単独で請求額を増やせないようにします。再起動/再デプロイのたびにリセットされ、インスタンス間で共有されません。低トラフィックの個人サイトには十分ですが、一般的な悪用防止策ではありません。

CI/CD

.github/workflows/ci.yml は、main ブランチへのプッシュ/PRごとに実行されます。パッケージのインストール、ruff によるリント、pytest スイートの実行を行います。RenderのGitHub自動デプロイ（上記参照）がCD部分を担当します。

セキュリティ / コストに関する注意

• MCPツールサーフェス（/mcp）はそれ自体ではLLMを呼び出しません — ローカルのJSONを読み取って返すだけです。接続する側（そのClaude、そのトークン）がそのコストを負担し、このサーバーは負担しません。

• /chat エンドポイントはLLMを呼び出します。このサーバー自身のAnthropic APIキーを使用します。それがそもそもの目的です（ブラウザはキーを安全に保持できません）。コストはIPごとのレート制限、effort: "low"、および小さな max_tokens によって制限されています。詳細は上記のチャットエンドポイントのセクションを参照してください。

• すべてのデータはすでに私のポートフォリオサイトで公開されています。どちらのエンドポイントにも認証は実装されていません。保護するべきプライベートなものは何もないからです。/chat のCORS許可リストは、誰がAPI予算を使うことができるかを制御するために存在し、データを保護するためではありません。

データの更新

data/ の下のJSONファイルを直接編集してください。id は get_project_details が照合する安定した識別子です。他のフィールドは自由形式です。コンテンツの更新にコードの変更は必要ありません。