Protocolo de Contexto Modelo (MCP): Una guía con proyecto de demostración

El sitio Protocolo de Contexto de Modelo (MCP) es una norma abierta que permite que grandes modelos lingüísticos interactúen dinámicamente con herramientas externas, bases de datos y API a través de una interfaz normalizada.

En este blog, te guiaré en la construcción de un servidor de revisión de relaciones públicas impulsado por MCP que se integra con Claude Desktop. Este servidor lo hará:

• Obtener detalles del RP y archivos modificados de GitHub
• Analiza los cambios en el código mediante la aplicación Claude Desktop
• Generar resúmenes y sugerencias de revisión de relaciones públicas
• Guardar opiniones en Notion

Utilizaremos el Protocolo de Contexto Modelo (MCP) para estandarizar la comunicación entre el servidor y Claude Desktop, haciéndolo modular y escalable.

¿Qué es el Protocolo de Contexto Modelo (MCP)?

El Protocolo de Contexto de Modelos (MCP) es una norma abierta desarrollada por Anthropic para permitir una integración fácil y estandarizada entre los modelos de IA y las herramientas externas. Actúa como conector universal, permitiendo que los grandes modelos lingüísticos (LLM) interactúen dinámicamente con las API, las bases de datos y las aplicaciones empresariales.

Creado originalmente para mejorar la capacidad de Claude de interactuar con sistemas externos, Anthropic decidió abrir el código MCP a principios de 2024 para fomentar su adopción en toda la industria. Al poner MCP a disposición del público, pretendían crear un marco estandarizado para la comunicación entre la IA y las herramientas, reduciendo la dependencia de las integraciones patentadas y permitiendo una mayor modularidad e interoperabilidad entre las aplicaciones de IA.

MCP sigue una arquitectura cliente-servidor en la que:

• Los clientes MCP (por ejemplo, Claude Desktop) solicitan información y ejecutan tareas.
• Los servidores MCP proporcionan acceso a herramientas y fuentes de datos externas.
• Las aplicaciones anfitrionas utilizan MCP para comunicarse entre modelos y herramientas.

Fuente: Modelo de Protocolo de Contexto

He aquí por qué querrías utilizar MCP para tus proyectos:

• Integración estandarizada de la IA: MCP proporciona una forma estructurada de conectar los modelos de IA con las herramientas.
• Flexibilidad: Permite cambiar fácilmente entre distintos modelos de IA y proveedores.
• Seguridad: Mantiene tus datos dentro de tu infraestructura mientras interactúas con la IA.
• Escalabilidad: MCP admite varios transportes como stdio, WebSockets, HTTP SSE y sockets UNIX.

Visión general del proyecto de demostración MCP: Servidor de revisión PR

El sistema de revisión PR automatiza el análisis del código y la documentación utilizando Claude Desktop y Notion.

Aquí tienes un desglose conciso de la tubería:

1. Configuración del entorno: Carga las credenciales de GitHub y Notion.
2. Inicialización del servidor: Inicia un servidor MCP para comunicarte con Claude Desktop.
3. Obtención de datos PR: Recupera los cambios y metadatos del RP de GitHub.
4. Análisis de código: Claude Desktop analiza directamente los cambios en el código (no se necesita ninguna herramienta aparte).
5. Documentación de nociones: Guarda los resultados del análisis en Notion para su seguimiento.

Paso 1: Configurar el entorno

Antes de empezar, asegúrate de que tienes instalado Python 3.10+. A continuación, configuramos nuestro entorno y empezamos instalando el gestor de paquetes uv. Para Mac o Linux: 

curl -LsSf https://astral.sh/uv/install.sh | sh  # Mac/Linux

Para Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

A continuación, creamos un nuevo directorio de proyecto y lo inicializamos con uv:

uv init pr_reviewer
cd pr_reviewer

Ahora podemos crear y activar un entorno virtual. Para Mac o Linux:

uv venv
source .venv/bin/activate

Para Windows:

.venv\Scripts\activate

Ahora instalamos las dependencias necesarias:

uv add "mcp[cli]" requests python-dotenv notion-client

Utilizaremos uv en lugar de conda para este proyecto porque es más rápido, ligero y está más centrado en la gestión de paquetes de Python. Recapitulemos lo que acabamos de hacer:

• Configuramos un entorno de desarrollo del servidor MCP de GitHub PR Review utilizando el gestor de paquetes uv
• Inicializamos un nuevo directorio de proyecto llamado pr_reviewer y navegamos hasta él.
• Creamos un entorno virtual y lo activamos para garantizar el aislamiento de las instalaciones de paquetes.

Paso 2: Instalar dependencias

Una vez configurado nuestro entorno, establecemos nuestras dependencias con las claves API y otros requisitos. Crea un archivo requirements.txt y añádele los siguientes paquetes de Python:

# Core dependencies for PR Analyzer
requests>=2.31.0          # For GitHub API calls
python-dotenv>=1.0.0      # For environment variables
mcp[cli]>=1.4.0          # For MCP server functionality
notion-client>=2.3.0      # For Notion integration

# Optional: Pin versions for stability
# requests==2.31.0
# python-dotenv==1.0.0
# mcp[cli]==1.4.0
# notion-client==2.3.0

El archivo requirements.txt contiene todas las dependencias básicas necesarias para el proyecto. Para configurar las dependencias, ejecuta cualquiera de los siguientes comandos (utiliza uv si lo has instalado antes).

uv pip install -r requirements.txt
pip install -r requirements.txt

Ahora, tu entorno tiene instaladas todas las dependencias necesarias.

Paso 3: Configurar las variables de entorno

A continuación, creamos un archivo .env que contiene todas las claves y tokens necesarios para este proyecto. 

Generar tokens de GitHub

Para generar tokens de GitHub:

• Accede a tu cuenta de GitHub y ve a la configuración.
• Ve a Configuración del desarrollador → Tokens de acceso personales.
• Haz clic en Generar nuevo token y selecciona la versión clásica.
• Proporciona un nombre para el token y habilita los siguientes permisos:
• leer:org
• read:repo_hook
• repo
• Haz clic en Generar para crear el token.
• Copia y guarda el token de forma segura, ya que se utilizará para la autenticación en las peticiones a la API.

Integraciones de nociones

• Accede a: https://www.notion.so/profile/integrations
• Crea una nueva integración y rellena el formulario. Mantén el "tipo" en Interno y añádelo a tu espacio de trabajo .

• Guarda la integración y copia el enlace de integración https://www.notion.so/profile/integrations/internal/UUID. El UUID al final de la URL es el Identificador Único Universal que debes anotar y utilizar comoID de la Página de Nociones .
• Una vez creada la integración, haz clic en ella, y en configuración, copia el Secreto interno de la integración, que será tu clave API de Notion.

Crear una .env archivo

Ahora, crea un archivo .env y añade el siguiente texto junto con las claves API y el token que generamos anteriormente.

GITHUB_TOKEN=your_github_token
NOTION_API_KEY=your_notion_api_key
NOTION_PAGE_ID=your_notion_page_id

Paso 4: Integración con GitHub

Vamos a configurar nuestro módulo de integración con GitHub para gestionar y recuperar los cambios en los RP de un repositorio de GitHub.

Crea un archivo github_integration.py y escribe el código siguiente (lo explicaremos dentro de un rato).

import os
import requests
import traceback
from dotenv import load_dotenv

# Load environment variables
load_dotenv()
GITHUB_TOKEN = os.getenv('GITHUB_TOKEN')

def fetch_pr_changes(repo_owner: str, repo_name: str, pr_number: int) -> list:
    """Fetch changes from a GitHub pull request.
    
    Args:
        repo_owner: The owner of the GitHub repository
        repo_name: The name of the GitHub repository
        pr_number: The number of the pull request to analyze
        
    Returns:
        A list of file changes with detailed information about each change
    """
    print(f" Fetching PR changes for {repo_owner}/{repo_name}#{pr_number}")
    
    # Fetch PR details
    pr_url = f"https://api.github.com/repos/{repo_owner}/{repo_name}/pulls/{pr_number}"
    files_url = f"{pr_url}/files"
    headers = {'Authorization': f'token {GITHUB_TOKEN}'}
    
    try:
        # Get PR metadata
        pr_response = requests.get(pr_url, headers=headers)
        pr_response.raise_for_status()
        pr_data = pr_response.json()
        
        # Get file changes
        files_response = requests.get(files_url, headers=headers)
        files_response.raise_for_status()
        files_data = files_response.json()
        
        # Combine PR metadata with file changes
        changes = []
        for file in files_data:
            change = {
                'filename': file['filename'],
                'status': file['status'],  # added, modified, removed
                'additions': file['additions'],
                'deletions': file['deletions'],
                'changes': file['changes'],
                'patch': file.get('patch', ''),  # The actual diff
                'raw_url': file.get('raw_url', ''),
                'contents_url': file.get('contents_url', '')
            }
            changes.append(change)
        
        # Add PR metadata
        pr_info = {
            'title': pr_data['title'],
            'description': pr_data['body'],
            'author': pr_data['user']['login'],
            'created_at': pr_data['created_at'],
            'updated_at': pr_data['updated_at'],
            'state': pr_data['state'],
            'total_changes': len(changes),
            'changes': changes
        }
        
        print(f"Successfully fetched {len(changes)} changes")
        return pr_info
        
    except Exception as e:
        print(f"Error fetching PR changes: {str(e)}")
        traceback.print_exc()
        return None

# Example usage for debugging
# pr_data = fetch_pr_changes('owner', 'repo', 1)
# print(pr_data) 

La función fetch_pr_changes() recupera y devuelve los cambios de una determinada solicitud de extracción de GitHub. Toma tres parámetros, a saber: repo_owner, repo_name, y pr_number, y devuelve una lista estructurada de los cambios del archivo junto con los metadatos PR.

El código utiliza la biblioteca requests para enviar peticiones HTTP GET autenticadas, obteniendo tanto los metadatos generales del RP como los cambios detallados a nivel de archivo:

• La primera petición a la API recupera información de alto nivel del RP, incluyendo su título, descripción, detalles del autor, marcas de tiempo y estado actual.
• La segunda petición de la API obtiene detalles sobre cada archivo modificado en el RP, como el nombre del archivo, el estado de modificación, el número de líneas añadidas o eliminadas y las URL para acceder al contenido del archivo.

Una vez recuperados los datos, la función estructura y combina los metadatos del RP con los cambios del archivo en un diccionario. Los cambios en los archivos se almacenan en una lista, y cada entrada contiene información detallada sobre un archivo. La estructura final de los datos incluye el título del RP, la descripción, el autor, las marcas de tiempo, el estado, el recuento total de archivos modificados y un desglose detallado de las modificaciones de los archivos.

Paso 5: Implementar el Servidor MCP

Ahora que ya tenemos todas las dependencias y funciones adicionales, configuramos nuestro servidor MCP. Creamos un archivo pr_anayzer.py, que:

• Inicializar un servidor MCP.
• Define herramientas para obtener detalles del RP, analizar el código y almacenar los resultados en Notion.
• Expón estas herramientas a Claude Desktop para resumirlas, encontrar posibles soluciones y mucho más.

Añadamos primero el código y expliquémoslo después 

import sys
import os
import traceback
from typing import Any, List, Dict
from mcp.server.fastmcp import FastMCP
from github_integration import fetch_pr_changes
from notion_client import Client
from dotenv import load_dotenv

class PRAnalyzer:
    def __init__(self):
        # Load environment variables
        load_dotenv()
        
        # Initialize MCP Server
        self.mcp = FastMCP("github_pr_analysis")
        print("MCP Server initialized", file=sys.stderr)
        
        # Initialize Notion client
        self._init_notion()
        
        # Register MCP tools
        self._register_tools()
    
    def _init_notion(self):
        """Initialize the Notion client with API key and page ID."""
        try:
            self.notion_api_key = os.getenv("NOTION_API_KEY")
            self.notion_page_id = os.getenv("NOTION_PAGE_ID")
            
            if not self.notion_api_key or not self.notion_page_id:
                raise ValueError("Missing Notion API key or page ID in environment variables")
            
            self.notion = Client(auth=self.notion_api_key)
            print(f"Notion client initialized successfully", file=sys.stderr)
            print(f"Using Notion page ID: {self.notion_page_id}", file=sys.stderr)
        except Exception as e:
            print(f"Error initializing Notion client: {str(e)}", file=sys.stderr)
            traceback.print_exc(file=sys.stderr)
            sys.exit(1)
    
    def _register_tools(self):
        """Register MCP tools for PR analysis."""
        @self.mcp.tool()
        async def fetch_pr(repo_owner: str, repo_name: str, pr_number: int) -> Dict[str, Any]:
            """Fetch changes from a GitHub pull request."""
            print(f"Fetching PR #{pr_number} from {repo_owner}/{repo_name}", file=sys.stderr)
            try:
                pr_info = fetch_pr_changes(repo_owner, repo_name, pr_number)
                if pr_info is None:
                    print("No changes returned from fetch_pr_changes", file=sys.stderr)
                    return {}
                print(f"Successfully fetched PR information", file=sys.stderr)
                return pr_info
            except Exception as e:
                print(f"Error fetching PR: {str(e)}", file=sys.stderr)
                traceback.print_exc(file=sys.stderr)
                return {}
        
        @self.mcp.tool()
        async def create_notion_page(title: str, content: str) -> str:
            """Create a Notion page with PR analysis."""
            print(f"Creating Notion page: {title}", file=sys.stderr)
            try:
                self.notion.pages.create(
                    parent={"type": "page_id", "page_id": self.notion_page_id},
                    properties={"title": {"title": [{"text": {"content": title}}]}},
                    children=[{
                        "object": "block",
                        "type": "paragraph",
                        "paragraph": {
                            "rich_text": [{
                                "type": "text",
                                "text": {"content": content}
                            }]
                        }
                    }]
                )
                print(f"Notion page '{title}' created successfully!", file=sys.stderr)
                return f"Notion page '{title}' created successfully!"
            except Exception as e:
                error_msg = f"Error creating Notion page: {str(e)}"
                print(error_msg, file=sys.stderr)
                traceback.print_exc(file=sys.stderr)
                return error_msg
    
    def run(self):
        """Start the MCP server."""
        try:
            print("Running MCP Server for GitHub PR Analysis...", file=sys.stderr)
            self.mcp.run(transport="stdio")
        except Exception as e:
            print(f"Fatal Error in MCP Server: {str(e)}", file=sys.stderr)
            traceback.print_exc(file=sys.stderr)
            sys.exit(1)

if __name__ == "__main__":
    analyzer = PRAnalyzer()
    analyzer.run() 

El código anterior configura un Servidor MCP para obtener los cambios del RP de GitHub y almacena los resultados del análisis en Notion. Repasemos los componentes clave:

1. Configuración e inicialización del entorno
• El módulo dotenv carga variables de entorno, garantizando el acceso seguro a las claves y credenciales de la API. 
• A continuación, la clase PRAnalyzer inicializa un servidor MCP mediante la función FastMCP(), que inicializa el servidor MCP con el nombre github_pr_analysis y permite la interacción con la aplicación Claude Desktop.
• El cliente Notion también se configura mediante el paquete notion-client, que utiliza la clave API de Notion y el ID de página almacenados en el archivo .env.
2. Herramienta MCP: recuperar cambios de RP
• La función fetch_pr() recupera metadatos de solicitudes pull de GitHub utilizando el método fetch_pr_changes() del archivo github_integration.py. Si tiene éxito, devuelve un diccionario con los detalles del RP.
• Puedes automatizar este proceso utilizando Webhooks integrada en GitHub, de forma que cualquier nuevo RP creado en tu repositorio será procesado automáticamente por el servidor.
3. Herramienta MCP: crear una página Notion
• La función create_notion_page() genera una página Notion con los resultados del análisis del RP.
• Utiliza la API de Notion para crear una nueva página en el espacio de trabajo de Notion especificado.
4. Ejecución del servidor
• El método run() inicia el servidor MCP utilizando mcp.run(transport="stdio"), lo que permite la interacción entre Claude Desktop y las herramientas de revisión del RP.

Paso 6: Ejecuta el Servidor MCP

Ahora que tenemos todas las piezas de código en su sitio, ejecutamos nuestro servidor con el siguiente comando de terminal:

python pr_analyzer.py

Una vez que el servidor esté en funcionamiento, abre la aplicación Claude Desktop, y verás un icono de un enchufe (🔌) en el cuadro de texto. Esta clavija indica la presencia de un MCP en el entorno Claude. En el mismo cuadro de texto, verás un icono en forma de martillo (🔨) que muestra todos los MCP disponibles, como se muestra a continuación.

Ahora, pasa el enlace al RP que quieres analizar y Claude hará el resto de cosas por ti.

Claude analizará primero el RP y luego ofrecerá un resumen y una reseña del mismo. Preguntará a los usuarios si quieren subir los datos a la página Notion. Aunque puedes automatizar ese proceso, el código actual te permite revisar el resumen antes de crear una nueva página Notion.

La página actualizada de Notion tiene este aspecto:

Conclusión

Nuestro servidor basado en PR Review MCP mejora el análisis del código y la documentación, aumentando la eficacia y la organización del proceso de revisión. Mediante el uso de MCP, la API de GitHub y la integración con Notion, este sistema permite el análisis automatizado de las relaciones públicas, una colaboración sencilla y una documentación estructurada. Con esta configuración, los desarrolladores pueden recuperar rápidamente los detalles del RP, analizar los cambios en el código mediante Claude y almacenar la información en Notion para futuras consultas.

Para explorar herramientas de IA más recientes, te recomiendo estos blogs:

• Cómo configurar y ejecutar Gemma 3 localmente con Ollama
• Mistral OCR: Una guía con ejemplos prácticos
• Tutorial del SDK de Agentes de OpenAI: Crear sistemas de IA que actúen
• ERNIE 4.5 y X1 de Baidu: Características, Acceso, Comparación DeepSeek