使用说明

MCP Certificate (Curso Guiado)

Repositorio de una clase guiada sobre Model Context Protocol (MCP). Incluye cuadernos por capítulos, ejemplos prácticos y material de referencia para aprender a:

Entender qué es MCP y sus implicaciones de seguridad.
Integrar MCPs en herramientas como Gemini CLI y Windsurf.
Crear tu propio servidor MCP con FastMCP, incluyendo generación desde un OpenAPI y pruebas locales.

Prerrequisitos

Conocimientos previos

Python básico: familiaridad con pip, entornos virtuales y ejecución de scripts
Git: conocimientos básicos de clonado de repositorios y control de versiones
JSON/REST APIs: comprensión de APIs REST y formato JSON (para Chapter 3)
Terminal/línea de comandos: comodidad ejecutando comandos en terminal

Software requerido

1. UV (gestor/runner de Python)

Propósito: gestión de dependencias y ejecución de módulos mcp de python.

Instalación: Accede a https://docs.astral.sh/uv/getting-started/installation/#installation-methods e instala para tu sistema operativo.

Verificación:

uv --version

2. Git

Propósito: clonar el repositorio.

Instalación:

Descarga desde https://git-scm.com/download/win
Durante la instalación, acepta las opciones por defecto
Asegúrate de marcar "Git from the command line and also from 3rd-party software"

Verificación:

git --version

3. Windsurf Editor

Propósito: editor con IA integrada para trabajar con MCPs en el entorno Cascade y seguir este curso guiado.

Instalación:

Descarga desde https://windsurf.com/download
Instala siguiendo el asistente por defecto

Configuración inicial:

Al abrir por primera vez, configura tu cuenta si es necesario
Instala las extensiones recomendadas para Python y Jupyter.

4. Node.js (versión LTS)

Propósito: ejecutar herramientas MCP escritas en JavaScript, MCP Inspector, gemini-cli y Claude Desktop.

Instalación:

Descarga la versión LTS desde https://nodejs.org/
IMPORTANTE: Durante la instalación, marca "Add to PATH" para poder usar node y npm desde terminal
Acepta instalar herramientas adicionales cuando se solicite

Verificación:

node --version
npm --version

Configuración adicional (recomendado):

# Actualizar npm a la última versión
npm install -g npm@latest

5. Docker Desktop (opcional)

Propósito: ejecutar MCPs en contenedores para mayor aislamiento y seguridad.

Instalación:

Descarga desde https://www.docker.com/products/docker-desktop
Ejecuta el instalador y reinicia el sistema si se solicita
Inicia Docker Desktop tras la instalación

Verificación:

docker --version
docker compose version

Configuración del proyecto

Paso 1: Clonar el repositorio

git clone https://github.com/SergiFuster/MCP-certificate.git
cd MCP-certificate

Paso 2: Configurar entorno Python

# Crear entorno virtual con UV
uv venv

# Sincronizar e instalar todas las dependencias
uv sync

Paso 3: Verificar instalación

# Verificar que FastMCP está disponible
uv run fastmcp --help

# Verificar que Jupyter está disponible para los notebooks
uv run jupyter --version

Paso 4: Abrir el proyecto

# Abrir con Windsurf (si está en PATH)
windsurf .

# Alternativa: abrir Windsurf manualmente y seleccionar la carpeta del proyecto

APIs y claves necesarias

Para completar todos los ejercicios del curso necesitarás las siguientes claves API (puedes obtenerlas durante el curso):

Brave Search API: para el Chapter 2 (MCP de búsqueda web)
- Registrarse en: https://api.search.brave.com/
- Variable de entorno: BRAVE_API_KEY
Context7 API (opcional): para integración con Windsurf en Chapter 2
- Registrarse en: https://context7.com/
- Variable de entorno: CONTEXT7_API_KEY
OpenAI/Anthropic/Google (opcional): para TaskMaster AI en Chapter 2
- Configurable con múltiples proveedores

Resolución de problemas comunes

Error de permisos en Windows:

# Ejecutar PowerShell como administrador si hay problemas de permisos
Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

UV no encontrado tras instalación:

Reinicia la terminal
Verifica que esté en PATH: echo $env:PATH (PowerShell) o echo %PATH% (CMD)

Node.js no encontrado:

Reinicia la terminal tras la instalación
Verifica que esté en PATH

Docker no inicia:

Asegúrate de que la virtualización esté habilitada en BIOS
En Windows, habilita WSL2 si se solicita

Índice

Prerrequisitos
Qué son los MCP — Chapter1/
Casos de uso — Chapter2/
FastMCP: crea tu servidor MCP — Chapter3/
Cómo ejecutar los ejemplos
Estructura del repositorio
Referencias

Qué son los MCP — `Chapter1/`

Contenido en Chapter1/chapter_1.ipynb.

Conceptos: introducción a MCP y su rol como puente entre LLMs y herramientas/servicios.
Seguridad: MCP abre la puerta a prompt injection si no se gestiona bien. Recomendaciones:
- Usar implementaciones oficiales.
- Probar MCPs y auditar respuestas.
- Usar claves con permisos/alcance mínimos.
- Trabajar con cuentas/repositorios con información limitada.
Cómo inspeccionar MCPs:
- Uso de MCP Inspector (npx -y @modelcontextprotocol/inspector).
- Diferencias entre MCP tipo STDIO (se ejecutan como procesos locales con command/args/env) y MCP tipo HTTP (servidor accesible por red con SSE/headers).

Casos de uso — `Chapter2/`

Contenido en Chapter2/chapter_2.ipynb.

Gemini CLI: instalación y uso de MCPs desde la CLI de Google Gemini.
- Ejemplos de configuración para MCPs de terceros como Obsidian y Brave Search.
Obsidian MCP: configuración vía uvx mcp-obsidian y variables de entorno (API Key, host/puerto).
Brave Search MCP: configuración vía npx @brave/brave-search-mcp-server con BRAVE_API_KEY.
Windsurf: instalación y configuración de MCPs dentro del chat de Cascade.
- Context7: servidor HTTP con serverUrl y header CONTEXT7_API_KEY.
- TaskMaster AI: servidor STDIO via npx task-master-ai con múltiples API Keys soportadas; selección de modelo y uso en el chat.

FastMCP: crea tu servidor MCP — `Chapter3/`

Contenido en Chapter3/chapter_3.ipynb y ejemplos en Chapter3/src/.

Crear un servidor básico (FastMCP):

Chapter3/src/mcp_server_example.py define un servidor sencillo con un tool greet(name: str).

Ejecución típica:

# Desde la raíz del repo (tras uv sync)
cd Chapter3/src/
fastmcp run mcp_server_example.py:mcp
# HTTP (opcional)
fastmcp run mcp_server_example.py:mcp --transport http --port 8000

Probar el servidor (cliente FastMCP):
- En el notebook Chapter3/chapter_3.ipynb hay un ejemplo con Client("http://localhost:8000/mcp") que llama al tool greet.
Generar un servidor MCP desde un OpenAPI:
- Chapter3/src/mcp_server_from_openapi_spec.py muestra cómo:
  1. Cargar openapi.json de un API (ej. un FastAPI local) y
  2. Crear un servidor MCP con FastMCP.from_openapi(...) usando un httpx.AsyncClient.
- Requisitos: que el API objetivo esté corriendo y accesible.
Servidor FastAPI de ejemplo:
- Chapter3/src/fastapi_server_example.py implementa CRUD en memoria con FastAPI.
- Exporta OpenAPI en http://127.0.0.1:8000/openapi.json al levantar el servidor.

Cómo ejecutar los ejemplos

Antes de empezar, asegúrate de haber hecho uv sync y de estar usando el entorno (source .venv/bin/activate si no usas uv run).

FastAPI (CRUD + OpenAPI):

Instala Uvicorn si hace falta:
```
uv add "uvicorn[standard]"
```

Ejecuta el servidor de ejemplo:

uv run python Chapter3/src/fastapi_server_example.py
# o (si tienes uvicorn):
uv run uvicorn Chapter3.src.fastapi_server_example:app --reload --host 127.0.0.1 --port 8000

Verifica:
- Salud: http://127.0.0.1:8000/health
- OpenAPI: http://127.0.0.1:8000/openapi.json

FastMCP (servidor básico):

cd Chapter3/src/
uv run fastmcp run mcp_server_example.py:mcp
# HTTP (opcional)
uv run fastmcp run mcp_server_example.py:mcp --transport http --port 8000

FastMCP desde OpenAPI:
1. Asegura que un API (por ejemplo el FastAPI anterior) está corriendo en http://127.0.0.1:8000.
2. En otra terminal:
```
uv run python Chapter3/src/mcp_server_from_openapi_spec.py
```
Cliente de prueba (desde notebook):
- Abre Chapter3/chapter_3.ipynb y ejecuta la celda que crea Client("http://localhost:8000/mcp") y llama al tool greet.

Estructura del repositorio

Chapter1/
  chapter_1.ipynb
  src/
    comic.png
    security-schema.png
    security.jpeg
Chapter2/
  chapter_2.ipynb
Chapter3/
  chapter_3.ipynb
  src/
    fastapi_server_example.py
    mcp_server_example.py
    mcp_server_from_openapi_spec.py
pyproject.toml
README.md

Dependencias clave

Definidas en pyproject.toml:

fastapi
fastmcp
ipykernel

Instálalas con:

uv sync

Referencias

Model Context Protocol — https://modelcontextprotocol.io/docs/getting-started/intro
Repositorio oficial de servidores MCP — https://github.com/modelcontextprotocol/servers
Gemini CLI — https://github.com/google-gemini/gemini-cli
Context7 — https://context7.com/
TaskMaster AI — https://www.task-master.dev/
FastMCP — https://gofastmcp.com/getting-started/quickstart

使用说明

MCP Certificate (Curso Guiado)

Prerrequisitos

Conocimientos previos

Software requerido

1. UV (gestor/runner de Python)

2. Git

3. Windsurf Editor

4. Node.js (versión LTS)

5. Docker Desktop (opcional)

Configuración del proyecto

Paso 1: Clonar el repositorio

Paso 2: Configurar entorno Python

Paso 3: Verificar instalación

Paso 4: Abrir el proyecto

APIs y claves necesarias

Resolución de problemas comunes

Índice

Qué son los MCP — Chapter1/

Casos de uso — Chapter2/

FastMCP: crea tu servidor MCP — Chapter3/

Cómo ejecutar los ejemplos

Estructura del repositorio

Dependencias clave

Referencias

相关 MCP

实时网络搜索服务

Blender 3D建模MCP服务

iOS模拟器交互服务器

图像生成服务

滴滴出行MCP服务

网页抓取与搜索MCP服务器

Qué son los MCP — `Chapter1/`

Casos de uso — `Chapter2/`

FastMCP: crea tu servidor MCP — `Chapter3/`