Servidor MCP de Portafolio

Un servidor MCP (Model Context Protocol) que expone el portafolio de Cheng-Yun Wu — proyectos, habilidades y currículum — como herramientas que cualquier asistente de IA compatible con MCP (Claude Desktop, Conectores de Claude.ai, MCP Inspector, etc.) puede llamar directamente, en lugar de raspar un sitio web.

Por qué existe esto

Quería entender realmente cómo funciona MCP de principio a fin, no solo leer sobre ello — así que construí un pequeño servidor que convierte el contenido de mi sitio de portafolio en herramientas estructuradas. También es una excusa deliberada para aprender dos cosas que no había tocado mucho antes: Docker y un pipeline básico de CI/CD, ambos aparecen repetidamente en las ofertas de trabajo a las que apunto.

Related MCP server: personal-mcp

¿Qué es MCP, brevemente?

MCP es un protocolo abierto (de Anthropic) que permite a un asistente de IA llamar a "herramientas" externas — funciones tipadas con nombre, descripción y esquema — para obtener información en vivo o realizar acciones, en lugar de depender solo de lo que está en sus datos de entrenamiento o un documento pegado. Un servidor declara sus herramientas; cualquier cliente compatible con MCP puede descubrirlas y llamarlas. Este proyecto es uno de esos servidores: declara cuatro herramientas respaldadas por mis propios datos de portafolio.

Herramientas

El docstring de cada herramienta es lo que el asistente de IA realmente lee para decidir cuándo llamarla — véase src/portfolio_mcp/server.py.

Cobertura: data/projects.json contiene los 31 elementos del portafolio — 7 casos de estudio en profundidad (sistemas entregados, la tesis, el proyecto de investigación NSTC, un artículo premiado) más 24 entradas más ligeras (otras entradas a concursos, informes de cursos, artículos de conferencias). Cada uno lleva al menos un enlace. Los informes de etapa de curso y los artículos complementarios llevan un related_project id que apunta al caso de estudio más completo al que pertenecen, para que un asistente pueda pasar de un informe a la historia completa.

Arquitectura

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)

• Transporte: HTTP Transmisible, no stdio — el punto es que un cliente remoto (por ejemplo, los Conectores de Claude.ai) pueda alcanzar este servidor a través de una URL pública, no solo un proceso local. Stdio sigue siendo compatible para pruebas locales con Claude Desktop / MCP Inspector.

• Capa de datos: tres archivos JSON planos bajo data/, cargados una vez y almacenados en caché (functools.lru_cache). Sin base de datos — los datos son pequeños, públicos y cambian raramente.

• Lógica de herramientas vs. conexión MCP: mantenidas separadas a propósito (tools.py vs. server.py) para que la lógica sea comprobable mediante pruebas unitarias sin necesidad de un servidor MCP o transporte en ejecución.

• Nota sobre el SDK: el SDK oficial de mcp para Python movió su API de servidor de alto nivel de FastMCP a mcp.server.mcpserver.MCPServer en la versión v2.0.0 — este proyecto apunta a mcp>=2.0.0 y a esa API actual. Si has visto tutoriales antiguos de MCP que usan from mcp.server.fastmcp import FastMCP, esa es la API anterior a v2.0.0 y no importará contra lo que pip install mcp te da hoy.

Estructura del proyecto

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

Ejecución local

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

Opción A — stdio, con MCP Inspector

npx @modelcontextprotocol/inspector python -m portfolio_mcp.server

Abre una interfaz web local donde puedes llamar a cada herramienta directamente e inspeccionar la solicitud/respuesta.

Opción B — stdio, con Claude Desktop

Fusiona la entrada mcpServers de claude_desktop_config.json en tu propia configuración de Claude Desktop (Configuración → Desarrollador → Editar Config), corrigiendo las rutas para tu máquina, luego reinicia Claude Desktop y pregunta algo como "¿En qué proyectos ha trabajado esta persona?"

Opción C — HTTP Transmisible, local

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

Pruebas

pytest -v
ruff check .

Ejecución con Docker

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

El contenedor siempre sirve HTTP Transmisible (ese es el punto de contenerizarlo — una unidad portátil y servible públicamente, no un proceso stdio atado a una máquina).

Despliegue (Render)

Destino de despliegue elegido: Render, nivel gratuito — ejecuta contenedores de larga duración (no funciones serverless con límites de tiempo de ejecución), que las conexiones persistentes de HTTP Transmisible necesitan, y no requiere tarjeta de crédito para empezar.

1. Sube este repositorio a GitHub.

2. En render.com: Nuevo → Web Service → conecta este repositorio.

3. Render detecta automáticamente el Dockerfile y lo construye/ejecuta como contenedor.

4. Elige el tipo de instancia Gratis → obtienes una URL https://<algo>.onrender.com.

5. Verifica que está activo:

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

6. (Opcional) Activa el despliegue automático de GitHub de Render para que git push a main se redepliegue automáticamente — combinado con el flujo de trabajo CI a continuación, esa es la historia completa de CI/CD.

Nota sobre el nivel gratuito: los servicios web gratuitos de Render se duermen después de ~15 minutos de inactividad y tardan 30-60s en despertar en la siguiente solicitud. Está bien para una demo de portafolio; vale la pena mencionarlo como una compensación deliberada entre costo y latencia si te preguntan.

Despliegue en vivo: https://yun-portfolio-mcp.onrender.com/mcp — conecta un cliente MCP a esta URL (nota la ruta /mcp; el dominio desnudo da 404, es esperado — HTTP Transmisible solo sirve esa ruta). Verifícalo tú mismo con npx @modelcontextprotocol/inspector https://yun-portfolio-mcp.onrender.com/mcp.

Si bifurcas esto: la lista blanca de encabezados Host en server.py está codificada a yun-portfolio-mcp.onrender.com por defecto (la protección contra rebote de DNS rechaza cualquier otro encabezado Host con un 421). Establece la variable de entorno MCP_ALLOWED_HOSTS al nombre de host de tu propio despliegue, o edita ALLOWED_HOSTS directamente.

Endpoint de chat (/chat) — el widget de preguntas y respuestas del sitio de portafolio

Una segunda puerta separada en el mismo servicio de Render, para un widget de chat simple incrustado en yunwcy.github.io — no forma parte de la superficie del protocolo MCP anterior. Un navegador hace POST con {"message": "..."} a /chat; el servidor usa el Ejecutor de Herramientas de Anthropic para permitir que Claude decida cuál de las mismas cuatro herramientas llamar (llamando a tools.py directamente — sin negociación MCP involucrada), luego devuelve {"reply": "..."}. Véase src/portfolio_mcp/chat.py para la implementación completa.

Por qué esto necesita un backend real, y GitHub Pages solo no puede hacerlo: responder en lenguaje natural significa que un LLM tiene que ver la pregunta y decidir qué herramienta llamar, lo que necesita una clave API de Anthropic — y una clave nunca puede ir en JS del lado del cliente en un sitio estático, ya que cualquiera puede ver el código fuente y quemar la cuenta. /chat mantiene la clave en el lado del servidor (una variable de entorno de Render, nunca enviada al navegador) y solo envía el widget que el navegador necesita a GitHub Pages.

Configuración (requerida antes de que este endpoint funcione):

1. Obtén una clave API de la Consola de Anthropic y agrégala a Render como la variable de entorno ANTHROPIC_API_KEY (Panel de Render → este servicio → Entorno). Sin ella, /chat devuelve 503 {"error": "not_configured"} en lugar de bloquear el servidor.

2. CHAT_ALLOWED_ORIGINS (separado por comas) controla CORS — por defecto es https://yunwcy.github.io. Ajústalo si el widget alguna vez vive en otro lugar.

3. ANTHROPIC_CHAT_MODEL (por defecto claude-opus-5) — la opción de propósito general más potente, pero este es un widget público simple, potencialmente de alto volumen y sensible al costo, por lo que claude-haiku-4-5 vale la pena considerar aquí específicamente. Esta es una elección deliberada que se deja a quien ejecute el servidor, no está codificada.

4. CHAT_RATE_LIMIT_PER_HOUR (por defecto 30) — un límite simple en memoria por IP para que un visitante no pueda disparar la factura solo. Se reinicia en cada reinicio/reimplementación y no se comparte entre instancias — suficiente para un sitio personal de bajo tráfico, no una defensa general contra abusos.

CI/CD

.github/workflows/ci.yml se ejecuta en cada push/PR a main: instala el paquete, verifica el estilo con ruff y ejecuta la suite de pytest. El despliegue automático de GitHub de Render (ver arriba) maneja la parte de CD.

Notas de seguridad / costo

• La superficie de herramientas MCP (/mcp) no llama a ningún LLM por sí misma — solo lee JSON local y lo devuelve. Quien se conecte a ella (su Claude, sus tokens) asume ese costo, no este servidor.

• El endpoint /chat sí llama a un LLM, usando la propia clave API de Anthropic de este servidor — ese es el punto (un navegador no puede mantener una clave de forma segura). El costo está limitado por un límite de tasa por IP, effort: "low" y un max_tokens pequeño; consulta la sección del endpoint de Chat arriba para los controles.

• Todos los datos ya son públicos en mi sitio de portafolio — no se implementa autenticación en ninguno de los endpoints, ya que no hay nada privado que proteger. La lista blanca CORS de /chat existe para controlar quién puede gastar el presupuesto de la API, no para proteger los datos.

Actualización de los datos

Edita los archivos JSON bajo data/ directamente — id es el identificador estable contra el que get_project_details compara; cualquier otro campo es de forma libre. No se necesitan cambios de código para actualizaciones de contenido.