# Portfolio MCP Server

An [MCP](https://modelcontextprotocol.io) (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

| Tool | What it does |
|---|---|
| `list_projects()` | Every portfolio item — shipped systems, competition entries, research projects, published papers, and course reports, not just the flagship case studies — with id, name, tagline, category, year, one-line summary, and its **links right in the listing** (live system, GitHub, report, demo video, etc.) |
| `get_project_details(name)` | Full record for one item. For a flagship project: role, tech stack, problem, challenges & solutions, outcome, links. For a lighter item: whatever's on file — at minimum a description and links. Matching is forgiving and alias-aware (`"lab handover"` → `ifit-lab-handover`; `"NTPU OPE Assistant"` → the thesis system it actually is) |
| `search_skills(keyword)` | Keyword search across the skills taxonomy, ranked by relevance, each result naming the projects that demonstrate it |
| `get_resume_summary(length)` | Self-introduction at `"short"` / `"medium"` / `"long"`, plus contact info |

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

**Coverage:** [`data/projects.json`](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](https://modelcontextprotocol.io/docs/concepts/transports), 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/`](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

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

### Option A — stdio, with MCP Inspector

```bash
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`](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

```bash
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

```bash
pytest -v
ruff check .
```

## Running with Docker

```bash
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](https://render.com)**, 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](https://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:
   ```bash
   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`](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`](src/portfolio_mcp/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](https://yunwcy.github.io/) — **not part of the MCP protocol surface above.** A browser `POST`s `{"message": "..."}` to `/chat`; the server uses [OpenAI's Responses API](https://platform.openai.com/docs/guides/function-calling) (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`](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](https://platform.openai.com/api-keys) 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](https://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`](.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](https://yunwcy.github.io/) — 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/`](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.