Portfolio MCP Server

An MCP (Model Context Protocol) server that exposes Cheng-Yun Wu's portfolio — projects, skills, and resume — as tools any MCP-compatible AI assistant (Claude Desktop, Claude.ai Connectors, MCP Inspector, etc.) can call directly, instead of scraping a website.

Why this exists

I wanted to actually understand how MCP works end to end, not just read about it — so I built a small server that turns my portfolio site's content into structured tools. It's also a deliberate excuse to pick up two things I hadn't touched much before: Docker and a basic CI/CD pipeline, both of which show up repeatedly in job postings I'm targeting.

What is MCP, briefly

MCP is an open protocol (from Anthropic) that lets an AI assistant call external "tools" — typed functions with a name, a description, and a schema — to fetch live information or take actions, instead of relying only on what's in its training data or a pasted document. A server declares its tools; any MCP-aware client can discover and call them. This project is one such server: it declares four tools backed by my own portfolio data.

Tools

Each tool's docstring is what the AI assistant actually reads to decide when to call it — see src/portfolio_mcp/server.py.

Coverage: data/projects.json holds all 33 portfolio items — 8 deep-dive case studies (shipped systems, this MCP server itself, the thesis, the NSTC research project, an award paper) plus 25 lighter entries (other competition entries, course reports, conference papers). Every single one carries at least one link. Course-stage reports and companion papers carry a related_project id pointing at the fuller case study they belong to, so an assistant can drill from a report into the full story.

Architecture

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)

• Transport: Streamable HTTP, not stdio — the point is that a remote client (e.g. Claude.ai's Connectors) can reach this server over a public URL, not just a locally-spawned process. Stdio is still supported for local Claude Desktop / MCP Inspector testing.

• Data layer: three flat JSON files under data/, loaded once and cached (functools.lru_cache). No database — the data is small, public, and changes rarely.

• Tool logic vs. MCP wiring: kept separate on purpose (tools.py vs. server.py) so the logic is unit-testable without a running MCP server or transport.

• SDK note: the official mcp Python SDK moved its high-level server API from FastMCP to mcp.server.mcpserver.MCPServer at v2.0.0 — this project targets mcp>=2.0.0 and that current API. If you've seen older MCP tutorials using from mcp.server.fastmcp import FastMCP, that's the pre-2.0 API and won't import against what pip install mcp gives you today.

Project structure

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: OpenAI Responses API + a small tool-calling loop 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

Running locally

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

Option A — stdio, with MCP Inspector

npx @modelcontextprotocol/inspector python -m portfolio_mcp.server

Opens a local web UI where you can call each tool directly and inspect the request/response.

Option B — stdio, with Claude Desktop

Merge the mcpServers entry from claude_desktop_config.json into your own Claude Desktop config (Settings → Developer → Edit Config), fixing the paths for your machine, then restart Claude Desktop and ask something like "What projects has this person worked on?"

Option C — Streamable HTTP, locally

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

Tests

pytest -v
ruff check .

Running with Docker

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

The container always serves Streamable HTTP (that's the point of containerizing it — a portable, publicly-servable unit, not a stdio process tied to one machine).

Deploying (Render)

Chosen deployment target: Render, free tier — it runs long-lived containers (not serverless functions with execution-time limits), which Streamable HTTP's persistent connections need, and it needs no credit card to start.

1. Push this repo to GitHub.

2. On render.com: New → Web Service → connect this repo.

3. Render auto-detects the Dockerfile and builds/runs it as a container.

4. Pick the Free instance type → you get a https://<something>.onrender.com URL.

5. Verify it's live:

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

6. (Optional) Enable Render's GitHub auto-deploy so git push to main redeploys automatically — combined with the CI workflow below, that's the full CI/CD story.

Free-tier note: Render's free web services sleep after ~15 minutes idle and take 30-60s to wake on the next request. Fine for a portfolio demo; worth mentioning as a deliberate cost/latency trade-off if asked.

Live deployment: https://yun-portfolio-mcp.onrender.com/mcp — connect an MCP client to this URL (note the /mcp path; the bare domain 404s, that's expected — Streamable HTTP only serves that one path). Verify it yourself with npx @modelcontextprotocol/inspector https://yun-portfolio-mcp.onrender.com/mcp.

If you fork this: the Host-header allowlist in server.py is hardcoded to yun-portfolio-mcp.onrender.com by default (DNS-rebinding protection rejects any other Host header with a 421). Set the MCP_ALLOWED_HOSTS env var to your own deployment's hostname, or edit ALLOWED_HOSTS directly.

Chat endpoint (/chat) — the portfolio site's Q&A widget

A second, separate door on the same Render service, for a plain chat widget embedded on yunwcy.github.io — not part of the MCP protocol surface above. A browser POSTs {"message": "..."} to /chat; the server uses OpenAI's Responses API (with a small hand-written tool-calling loop, since the Responses API has no built-in agent-loop helper) to let the model decide which of the same four tools to call (by calling tools.py directly — no MCP handshake involved), then returns {"reply": "..."}. See src/portfolio_mcp/chat.py for the full implementation.

Why this needs a real backend, and GitHub Pages alone can't do it: answering in natural language means an LLM has to see the question and decide which tool to call, which needs an OpenAI API key — and a key can never go in client-side JS on a static site, since anyone can view-source it and burn the account. /chat keeps the key server-side (a Render environment variable, never sent to the browser) and only ships the widget the browser needs down to GitHub Pages.

Setup (required before this endpoint works):

1. Get an API key from the OpenAI Platform dashboard and add it to Render as the OPENAI_API_KEY environment variable (Render dashboard → this service → Environment). Without it, /chat returns 503 {"error": "not_configured"} rather than crashing the server.

2. CHAT_ALLOWED_ORIGINS (comma-separated) controls CORS — defaults to https://yunwcy.github.io. Set it if the widget ever lives somewhere else.

3. OPENAI_CHAT_MODEL (default gpt-5.6) — a solid general-purpose choice, but this is a simple, potentially high-volume, cost-sensitive public widget, so a cheaper nano/mini-tier model is worth considering here specifically (check platform.openai.com/docs/pricing for the current cheapest option — model names and pricing shift often). This is a deliberate choice left to whoever runs the server, not hardcoded.

4. CHAT_RATE_LIMIT_PER_HOUR (default 30) — a simple in-memory per-IP cap so one visitor can't run up the bill alone. It resets on every restart/redeploy and isn't shared across instances — enough for a low-traffic personal site, not a general abuse defense.

CI/CD

.github/workflows/ci.yml runs on every push/PR to main: installs the package, lints with ruff, and runs the pytest suite. Render's GitHub auto-deploy (see above) handles the CD half.

Security / cost notes

• The MCP tool surface (/mcp) does not call any LLM itself — it only reads local JSON and returns it. Whoever connects to it (their Claude, their tokens) bears that cost, not this server.

• The /chat endpoint does call an LLM, using this server's own OpenAI API key — that's the whole point (a browser can't hold a key safely). Cost is bounded by a per-IP rate limit, a small max_output_tokens, and a capped tool-calling loop; see the Chat endpoint section above for the knobs.

• All data is already public on my portfolio site — no auth is implemented on either endpoint, since there's nothing private to protect. /chat's CORS allowlist exists to control who can spend the API budget, not to protect the data.

Updating the data

Edit the JSON files under data/ directly — id is the stable identifier get_project_details matches against; every other field is free-form. No code changes needed for content updates.