Interactive Curriculum MCP Server

Official Model Context Protocol (MCP) Server with Streamable HTTP transport over FastMCP, exposing an interactive CV and portfolio for AI assistants (Claude.ai, Cursor, Windsurf) and LLM clients. Includes a self-contained web showcase and a production-ready container for Google Cloud Run.

Descripción del Proyecto (Spanish)

Este proyecto implementa un servidor oficial de Model Context Protocol (MCP) en Python que permite a evaluadores técnicos, reclutadores y modelos LLM (como Claude o GPT) explorar de forma interactiva y estructurada la trayectoria profesional, habilidades técnicas, proyectos insignia y compatibilidad con vacantes de Ana-Catalina Villalobos Contardo (Data Scientist & Machine Learning Engineer).

Características Principales

• Web Showcase & Playground Interactivo: Servido en la raíz (/) y /demo bajo el Pastel-Tech Design System. Permite a reclutadores y visitantes humanos evaluar compatibilidad con vacantes y buscar en el currículum en tiempo real con latencia inferior a 5ms y resultados 100% verificables en memoria.

• Negociación Transparente de Contenido: Devuelve una aplicación web responsiva si la petición proviene de un navegador (Accept: text/html) y el JSON de descubrimiento original si proviene de agentes o APIs.

• Transporte Moderno Streamable HTTP (/mcp): Transporte nativo recomendado por la especificación MCP para conexiones directas desde Claude.ai (conectores personalizados), Gemini (gemini.com Connected Apps) y Cursor / Windsurf (mcp.json).

• 9 Herramientas MCP Especializadas: Consulta granular de experiencia laboral, stack tecnológico con niveles de dominio, proyectos insignia, evaluación automática de vacantes, búsqueda global por palabras clave, educación, contacto y perfil general.

• Desacoplamiento y Rendimiento: Datos estructurados en data/cv_data.json validados en memoria con Pydantic v2 al iniciar el contenedor (<2ms por consulta).

Related MCP server: Bijon Portfolio MCP Server

Project Overview (English)

This project provides an official Model Context Protocol (MCP) server built in Python that enables AI assistants, hiring managers, and evaluators to interactively query the professional experience, technical skill matrix, featured projects, and job compatibility of Ana-Catalina Villalobos Contardo (Data Scientist & Machine Learning Engineer).

Key Features

• Interactive Web Showcase & Playground: Served at / and /demo using the Pastel-Tech Design System. Allows human visitors and evaluators to test job fit and query the curriculum directly in the browser with deterministic accuracy and instant in-memory responses.

• Transparent HTTP Content Negotiation: Serves the interactive web interface to browsers (Accept: text/html) while preserving the structured JSON discovery payload for programmatic agents and curl.

• Modern Streamable HTTP Transport (/mcp): Native transport standard for direct cloud connections from Claude.ai (custom connectors), Gemini (gemini.com Connected Apps) and Cursor / Windsurf (mcp.json).

• 9 Dedicated MCP Tools: Granular exploration of work history, skill taxonomy by category/level, highlighted projects, automated job fit scoring, full-text curriculum search, education, contact details, and general profile.

• Zero-Latency In-Memory Architecture: Clean data validation using Pydantic v2 loaded into memory on container startup (<2ms response time).

📐 Arquitectura del Sistema / System Architecture

flowchart TD
    subgraph ClientLayer["Clientes MCP / AI Clients"]
        A["Claude.ai (Custom Connector)<br/>Streamable HTTP (POST /mcp)"]
        B["Cursor / Windsurf (mcp.json)<br/>Streamable HTTP (POST /mcp)"]
        G["Gemini (gemini.com Connected Apps)<br/>Streamable HTTP (POST /mcp)"]
    end

    subgraph CloudLayer["Google Cloud Run / Serverless Host"]
        C["FastMCP App (:8080)<br/>/mcp & Custom Routes"]
        D["9 Herramientas MCP / Tools"]
        E["CV Service & Pydantic Engine<br/>(models/cv.py)"]
        F[("data/cv_data.json<br/>(In-Memory Dataset)")]
    end

    A <-->|"JSON-RPC Streamable HTTP"| C
    B <-->|"JSON-RPC Streamable HTTP"| C
    G <-->|"JSON-RPC Streamable HTTP"| C
    C <--> D
    D <--> E
    E <--> F

🧰 Catálogo de Herramientas MCP / MCP Tools Catalog

El servidor expone 9 herramientas oficiales registradas a través del protocolo MCP:

💡 Aprendizajes Clave & Decisiones de Diseño

1. Evolución del Transporte MCP (Migración a Streamable HTTP):

   • Inicialmente, los servidores MCP remotos dependían de combinaciones multi-endpoint basadas en Server-Sent Events (/sse y /messages/).

   • La especificación moderna de MCP estandarizó Streamable HTTP (/mcp) mediante un único endpoint unificado sobre HTTP POST que admite respuestas JSON y flujos en tiempo real (Accept: application/json, text/event-stream).

   • Esta arquitectura simplifica drásticamente el despliegue serverless, elimina la necesidad de mantener puentes locales (stdio) para clientes remotos y garantiza compatibilidad nativa directa con Claude.ai (conectores personalizados) y Cursor / Windsurf (mcp.json).

2. Desacoplamiento y Validación de Datos:

   • La separación entre la capa de datos (data/cv_data.json), los contratos de interfaz (models/cv.py) y la lógica de negocio (services/cv_service.py) permite actualizar el contenido del currículum sin modificar el servidor MCP ni arriesgar la compatibilidad de tipos.

3. Compatibilidad y Cambios de API en mcp 2.x:

   • Recientemente, la versión 2.0.0 del SDK oficial de MCP introdujo cambios que renombraron FastMCP. Para mantener la estabilidad del despliegue en Cloud Run y garantizar que nuestro código FastMCP v1 continúe funcionando correctamente sin refactorización inmediata, fijamos la dependencia en requirements.txt a mcp>=1.3.0,<2.

🚀 Instalación y Uso Local / Local Setup

1. Clonar el Repositorio y Configurar Entorno

# Clonar repositorio
git clone https://github.com/AnaCataVC/anacatalina-mcp.git
cd anacatalina-mcp

# Crear y activar entorno virtual
python -m venv .venv

# Windows (PowerShell)
.venv\Scripts\Activate.ps1

# Linux / macOS
source .venv/bin/activate

# Instalar dependencias (producción)
pip install -r requirements.txt

# Instalar dependencias de desarrollo (incluye pytest, para correr la suite de pruebas)
pip install -r requirements-dev.txt

2. Ejecutar la Suite de Pruebas

pytest tests/ -v

3. Sincronización y Auditoría de Datos (anacatalina-cv y projects-hub)

# Auditar consistencia con los repositorios hermanos
python scripts/sync_mcp_data.py --audit

# Sincronizar data/cv_data.json con las últimas actualizaciones
python scripts/sync_mcp_data.py --sync

4. Iniciar el Servidor MCP Local

uvicorn server:app --host 0.0.0.0 --port 8080 --reload

Endpoints disponibles:

• Web Showcase & Playground: http://localhost:8080/ (en navegadores) o http://localhost:8080/demo

• Discovery JSON: http://localhost:8080/ (con cabecera Accept: application/json o agentes MCP)

• Health Check: http://localhost:8080/health

• Streamable HTTP (MCP Endpoint): http://localhost:8080/mcp &mdash; para Claude.ai, Cursor y Windsurf

• APIs REST Auxiliares (Integraciones HTTP directas / Scripts):

  • POST /api/evaluate-fit &mdash; Evaluación determinista de vacantes vía HTTP

  • GET /api/search?q={query} &mdash; Búsqueda transversal por palabras clave vía HTTP

  • GET /api/skills &mdash; Taxonomía de stack y niveles técnicos

  • GET /api/projects &mdash; Proyectos destacados (laborales y personales)

🤖 Conectar Asistentes de IA / AI Clients Setup

1. Claude.ai (Conector Personalizado)

1. En Claude.ai: Ajustes → Conectores → Agregar conector personalizado

2. Nombre: Ana-Catalina MCP

3. URL del servidor:

https://mcp.ana-catalina.com/mcp

4. Autenticación: Ninguna (servidor de portafolio público)

2. Gemini (gemini.com &mdash; Connected Apps)

1. En gemini.google.com: Settings & help → Connected Apps (si no aparece, entra primero a Personal Intelligence → Connected Apps).

2. En "Custom apps for Spark", haz clic en Add a custom app.

3. Pega la URL del servidor:

https://mcp.ana-catalina.com/mcp

4. Haz clic en Next y sigue las instrucciones en pantalla. Una vez conectado, invócalo escribiendo @ en el chat.

3. Cursor & Windsurf (mcp.json)

Agrega el servidor en tu configuración de MCP (~/.cursor/mcp.json o settings de Cursor):

{
  "mcpServers": {
    "anacatalina-cv": {
      "url": "https://mcp.ana-catalina.com/mcp"
    }
  }
}

☁️ Despliegue en Google Cloud Run / Cloud Run Deployment

1. Construir y Probar Contenedor Localmente

docker build -t anacatalina-mcp .
docker run -p 8080:8080 -e PORT=8080 anacatalina-mcp

2. Desplegar a Google Cloud Run con Google Cloud SDK (gcloud)

# Autenticarse en Google Cloud
gcloud auth login
gcloud config set project TU_PROJECT_ID

# Desplegar directamente desde el código fuente
gcloud run deploy anacatalina-mcp \
  --source . \
  --platform managed \
  --region us-central1 \
  --allow-unauthenticated \
  --timeout 3600

📄 Licencia / License

Este proyecto se distribuye bajo la licencia MIT. Desarrollado por Ana-Catalina Villalobos Contardo.