Portfolio MCP 伺服器

一個 MCP（模型上下文協定）伺服器，將吳承運的作品集（專案、技能和履歷）以工具形式公開，讓任何相容 MCP 的 AI 助手（Claude Desktop、Claude.ai Connectors、MCP Inspector 等）可以直接呼叫，無需從網站擷取資料。

為何存在

我想真正了解 MCP 是如何端到端運作的，而不只是閱讀相關資料——因此我建立了一個小型伺服器，將我的作品集網站內容轉換為結構化工具。這也是一個刻意學習兩項我之前較少觸及技術的理由：Docker 和基本的 CI/CD 流程，這兩者在我鎖定的求職資訊中反覆出現。

Related MCP server: personal-mcp

MCP 簡介

MCP 是一個開放協定（來自 Anthropic），讓 AI 助手可以呼叫外部「工具」——具有名稱、描述和綱要的型別化函式——以取得即時資訊或執行操作，而不僅依賴訓練資料或貼上的文件。伺服器宣告其工具；任何支援 MCP 的用戶端都可以發現並呼叫它們。此專案就是這樣一個伺服器：它宣告了四個由我自己的作品集資料支援的工具。

工具

每個工具的 docstring 就是 AI 助手實際閱讀以決定何時呼叫的內容——請參閱 src/portfolio_mcp/server.py。

涵蓋範圍： data/projects.json 包含全部 31 個作品集項目——7 個深度案例研究（已上線系統、論文、NSTC 研究專案、獲獎論文）加上 24 個較輕量的條目（其他競賽作品、課程報告、會議論文）。每個項目都至少包含一個連結。課程階段報告和附屬論文包含一個 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/ 下的三個平面 JSON 檔案，載入一次後快取（functools.lru_cache）。無資料庫——資料量小、公開且極少變更。

• 工具邏輯 vs. 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 教學，那是 2.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

開啟一個本地網頁 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（這就是容器化的重點——一個可攜帶、可公開服務的單元，而非綁定於單一機器的 stdio 進程）。

部署（Render）

選擇的部署目標：Render，免費方案——它執行長生命週期容器（非具有執行時間限制的無伺服器函式），這是 Streamable HTTP 持續連線所需的條件，且開始使用無需信用卡。

1. 將此儲存庫推送到 GitHub。

2. 在 render.com 上：新建 → Web 服務 → 連接此儲存庫。

3. Render 會自動偵測 Dockerfile 並將其建置/執行為容器。

4. 選擇 免費 方案類型 → 您會獲得一個 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 僅服務該一個路徑）。使用 npx @modelcontextprotocol/inspector https://yun-portfolio-mcp.onrender.com/mcp 自行驗證。

如果您 fork 此專案： server.py 中的 Host 標頭允許清單預設為 yun-portfolio-mcp.onrender.com（DNS 重新綁定保護會拒絕任何其他 Host 標頭並回傳 421）。將 MCP_ALLOWED_HOSTS 環境變數設定為您自己部署的主機名稱，或直接編輯 ALLOWED_HOSTS。

聊天端點（/chat）——作品集網站的問答小工具

同一個 Render 服務上的第二個獨立入口，用於嵌入在 yunwcy.github.io 上的純聊天小工具——不屬於上述的 MCP 協定範圍。 瀏覽器將 {"message": "..."} POST 到 /chat；伺服器使用 Anthropic Tool Runner 讓 Claude 決定呼叫哪一個相同的四個工具（透過直接呼叫 tools.py——不涉及 MCP 握手），然後回傳 {"reply": "..."}。完整實作請參閱 src/portfolio_mcp/chat.py。

為何這需要真實後端，而僅 GitHub Pages 無法做到： 用自然語言回答需要 LLM 看到問題並決定要呼叫哪個工具，這需要 Anthropic API 金鑰——而金鑰絕不能放在靜態網站的用戶端 JS 中，因為任何人都可以檢視原始碼並消耗帳戶額度。/chat 將金鑰保持在伺服器端（Render 環境變數，從不發送到瀏覽器），並且只將瀏覽器需要的小工具發送到 GitHub Pages。

設定（此端點運作前的必要條件）：

1. 從 Anthropic Console 取得 API 金鑰，並將其作為 ANTHROPIC_API_KEY 環境變數新增到 Render（Render 儀表板 → 此服務 → 環境）。沒有它，/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 限制，使單一訪客無法獨自耗盡帳戶額度。每次重新啟動/重新部署時會重設，且不會在實例間共享——對於低流量的個人網站來說足夠，而非通用的濫用防禦。

CI/CD

.github/workflows/ci.yml 在每次推送/PR 到 main 時執行：安裝套件、使用 ruff 進行 lint，並執行 pytest 套件。Render 的 GitHub 自動部署（見上方）處理 CD 部分。

安全性/成本說明

• MCP 工具範圍（/mcp）本身不呼叫任何 LLM——它僅讀取本地 JSON 並回傳。連接的使用者（他們的 Claude、他們的 token）承擔該成本，而非此伺服器。

• /chat 端點會呼叫 LLM，使用此伺服器自己的 Anthropic API 金鑰——這就是重點（瀏覽器無法安全地持有金鑰）。成本受每 IP 速率限制、effort: "low" 和較小的 max_tokens 約束；請參閱上方的聊天端點章節了解控制選項。

• 所有資料已經在我的作品集網站上公開——兩個端點均未實作驗證，因為沒有需要保護的私有內容。/chat 的 CORS 允許清單存在是為了控制誰可以花費 API 預算，而非保護資料。

更新資料

直接編輯 data/ 下的 JSON 檔案——id 是 get_project_details 比對的穩定識別碼；其他所有欄位均為自由格式。內容更新無需程式碼變更。