Tutorial de Protocolo de contexto del modelo (MCP): cree su primer servidor MCP en 6 pasos

Protocolo de contexto (MCP)?

Como resultado de la aparición de agentes de IA y aplicaciones basadas en RAG en los últimos años, existe una creciente demanda de personalización de modelos de idiomas grandes (LLM) al integrarse con recursos externos (por ejemplo, sistemas basados ​​en trapo) y herramientas (por ejemplo, sistemas basados ​​en agentes). Esto mejora las capacidades existentes de LLM al incorporar el conocimiento externo y habilitar la ejecución de tareas autónomas.

El Protocolo de contexto del modelo (MCP), introducido por primera vez en noviembre de 2024 por Anthrope, ha crecido en popularidad, ya que ofrece una forma más coherente y consistente de conectar LLM con herramientas y recursos externos, por lo que es una alternativa convincente para construir integraciones API personalizadas para cada caso de uso. MCP es un protocolo estandarizado y de código abierto que proporciona una interfaz consistente que permite a LLM interactuar con varias herramientas y recursos externos, por lo tanto, permite a los usuarios finales a MCP Server que ha sido encapsulado con funcionalidades mejoradas. En comparación con los patrones de diseño del sistema agente actuales, MCP ofrece varios beneficios clave:

• Aumente la escalabilidad y la mantenibilidad del sistema a través de integraciones estandarizadas.
• Reduzca el esfuerzo de desarrollo duplicado ya que una sola implementación del servidor MCP funciona con múltiples clientes MCP.
• Evite el bloqueo de los proveedores proporcionando flexibilidad para cambiar entre proveedores de LLM, ya que el LLM ya no está bien acoplado con el sistema de agente.
• Acelera el proceso de desarrollo significativamente al permitir la creación rápida de productos viables.

Este artículo tiene como objetivo guiarlo a través de los fundamentos del protocolo de contexto del modelo y los componentes esenciales de la construcción de un servidor MCP. Aplicaremos estos conceptos a través de un ejemplo práctico de construir un servidor MCP que permita a LLMS resumir y visualizar las bases de código GitHub simplemente proporcionando una URL como el ejemplo a continuación.

Entrada del usuario:

https://github.com/aws-samples/aws-cdk-examples/blob/main/python/codepipeline-docker-build/Base.py

Salida de MCP:

Comprender los componentes de MCP

Arquitectura MCP

MCP adopta una arquitectura de cliente cliente donde el cliente es un dispositivo o aplicación que solicita los servicios ofrecidos por un servidor centralizado. Una analogía útil para la relación cliente-servidor es la de un cliente y un restaurante. El cliente actúa como el lado del cliente, enviando solicitudes realizando pedidos desde el menú, mientras que el restaurante se asemeja al servidor, proporcionando servicios como platos y asientos. El restaurante posee recursos suficientes para servir a múltiples clientes en un corto período de tiempo, mientras que los clientes solo deben preocuparse por recibir sus pedidos.

La arquitectura MCP consta de tres componentes: MCP Server, MCP Client y MCP Host. Servidor MCP Ofrece herramientas y recursos, exponiendo funcionalidades que los modelos de IA pueden aprovechar a través de solicitudes estructuradas. Anfitrión de MCP Ofrece el entorno de tiempo de ejecución que administra la comunicación entre clientes y servidores, como Claude Desktop o IDES con extensiones respaldadas por MCP. Si continuamos con la misma analogía del cliente-restaurante anterior, el anfitrión de MCP puede considerarse como un sistema de gestión de restaurantes que coordina las comunicaciones entre los clientes (clientes) y los restaurantes, maneja la toma de pedidos y el procesamiento de pagos. Cliente de MCP generalmente está integrado en la aplicación host, lo que permite a los usuarios interactuar con el servidor a través de una interfaz. Sin embargo, existe la flexibilidad de desarrollar clientes de MCP personalizados para casos de uso especializados y requisitos, como construir una aplicación web de IA simple que use a Streamlit para admitir más funcionalidades front-end.

Componentes del servidor MCP

En este artículo, nos centraremos en comprender el servidor MCP y aplicar nuestro conocimiento para construir un servidor MCP simple y personalizado. MCP Server envuelve varias llamadas de API a las herramientas y recursos externos, lo que permite a los clientes que acceden a estas funcionalidades sin preocuparse por la configuración adicional. El servidor MCP admite la incorporación de tres tipos de componentes que se alinean con tres estrategias comunes de personalización de LLM.

• Recursos son datos, archivos y documentos que sirven como la base de conocimiento externa para enriquecer el conocimiento existente de LLM. Esto es particularmente útil en un sistema basado en trapo.
• Herramientas son funciones ejecutables e integraciones con otros programas para enriquecer el espacio de acción de LLM, por ejemplo, realizar una búsqueda en Google, crear un prototipo de figma, etc., que puede aprovecharse en un sistema basado en agentes.
• Indicaciones son plantillas de instrucción predefinidas para guiar la salida de LLM, por ejemplo, respuesta en un tono profesional o casual. Esto es útil en el sistema que se beneficia de técnicas de ingeniería rápidas.

Si está interesado en saber más sobre las estrategias de personalización de LLM, consulte mi artículo y video anteriores en “6 estrategias de personalización de LLM comunes explicadas brevemente“.

Construya su servidor MCP en 6 pasos

Usaremos un ejemplo simple para demostrar cómo construir su primer servidor MCP usando Python, que permite llamar a una personalización visualize_code herramienta para convertir los archivos de código sin procesar extraídos de los repositorios de GitHub en diagramas visuales como el siguiente ejemplo.

Para las personas con ciencia de datos, el aprendizaje de fondo para construir servidores MCP, existen varios conceptos de desarrollo de software que pueden ser desconocidos pero importantes de entender: programación asíncrona para manejar operaciones asíncronas, arquitectura de clientes/servidores y decoradores de Python para modificar el comportamiento de la función. Explicaremos estos conceptos con más detalle a medida que avanzamos en este ejemplo práctico.

Paso 1. Configuración del entorno

• Configuración de gerentes de paquetes: MCP usa uv como el administrador de paquete predeterminado. Para el sistema MacOS y Linux, instale uv y ejecutarlo usando sh con el comando shell:

• Iniciar un nuevo directorio de trabajo /visualactive el entorno virtual, cree la estructura del proyecto para almacenar el script principal visual.py:

# Create a new directory for our project
uv init visual
cd visual

# Create virtual environment and activate it
uv venv
source .venv/bin/activate

# Install dependencies
uv add "mcp[cli]" httpx

# Create our server file
touch visual.py

• Instalar dependencias requeridas: pip install mcp httpx fastapi uvicorn

Lectura adicional:

La publicación oficial de blog de Anthrope “Para desarrolladores de servidores – Protocolo de contexto del modelo“Proporciona una guía fácil de seguir para configurar el entorno de desarrollo del servidor MCP.

Paso 2: Configuración básica del servidor

En el visual.py Script, importe las bibliotecas requeridas e inicie nuestra instancia de servidor MCP y defina un agente de usuario para realizar solicitudes HTTP. Usaremos FastMCP Como el SDK oficial de Python MCP.

from typing import Any
import httpx
from mcp.server.fastmcp import FastMCP

# Initialize FastMCP server
mcp = FastMCP("visual_code_server")

Paso 3: Crear funciones auxiliares

Crearemos una función de ayudante get_code() Para obtener código de la URL GitHub.

async def get_code(url: str) -> str:
    """
    Fetch source code from a GitHub URL.
    
    Args:
        url: GitHub URL of the code file
    Returns:
        str: Source code content or error message
    """
    USER_AGENT = "visual-fastmcp/0.1"

    headers = {
        "User-Agent": USER_AGENT,
        "Accept": "text/html"
    }
    
    async with httpx.AsyncClient() as client:
        try:
            # Convert GitHub URL to raw content URL
            raw_url = url.replace("github.com", "raw.githubusercontent.com")\
                        .replace("/blob/", "/")
            response = await client.get(raw_url, headers=headers, timeout=30.0)
            response.raise_for_status()
            return response.text
        except Exception as e:
            return f"Error fetching code: {str(e)}"

Desglosemos el get_code() funcionar en algunos componentes.

Implementación asíncrona

La programación asincrónica permite que múltiples operaciones se ejecuten simultáneamente, mejorando la eficiencia al no bloquear la ejecución mientras se espera que las operaciones se completen. Por lo general, se usa para manejar las operaciones de E/S de manera eficiente, como la solicitud de red, las entradas de los usuarios y las llamadas de API. Por el contrario, las operaciones síncronas, típicamente utilizadas para tareas de aprendizaje automático, se ejecutan secuencialmente, con cada operación bloqueando hasta su finalización antes de pasar a la siguiente tarea. Se realizan los siguientes cambios para definir esta función de manera asincrónica:

• La función se declara con async def para permitir el manejo de múltiples operaciones simultáneamente.
• Usar async with gerente de contexto y httpx.AsyncClient() para solicitudes HTTP sin bloqueo.
• Manejar solicitudes HTTP asincrónicas agregando await palabra clave para client.get().

Procesamiento de URL

Configurar el encabezado Aceptar para el contenido HTML y establecer el agente de usuario apropiado para identificar al cliente que realiza las solicitudes HTTP, es decir visual-fastmcp/0.1 . Convierta las URL de GitHub regulares en formato de archivo sin procesar.

Manejo de errores

Capturar excepciones específicas de http (httpx.RequestError, httpx.HTTPStatusError) y atrapar otro manejo de excepciones genéricas como retroceso, luego devuelva los mensajes de error descriptivos para la depuración.

Lectura adicional:

Paso 4: Implemente la herramienta del servidor MCP

Usando algunas líneas de código adicionales, ahora podemos crear nuestra herramienta principal del servidor MCP visualize_code().

@mcp.tool()
async def visualize_code(url: str) -> str:
    """
    Visualize the code extracted from a Github repository URL in the format of SVG code.

    Args:
        url: The GitHub repository URL
    
    Returns:
        SVG code that visualizes the code structure or hierarchy.
    """

    code = await get_code(url)
    if "error" in code.lower():
        return code
    else:
        return "\n---\n".join(code)
    return "\n".join(visualization)

Decorador

Un decorador de Python es una función especial que modifica o mejora el comportamiento de otra función o método sin alterar su código original. FastMCP proporciona decoradores que envuelven funciones personalizadas para integrarlas en el servidor MCP. Por ejemplo, usamos @mcp.tool() Para crear una herramienta de servidor MCP decorando el visualize_code función. Del mismo modo, podemos usar @mcp.resource() para recursos y @mcp.prompt() para indicaciones.

Escriba sugerencias y documentos

La clase FastMCP aprovecha las sugerencias y las documentos de tipo Python para mejorar automáticamente las definiciones de herramientas, simplificando la creación y el mantenimiento de las herramientas MCP. Para nuestro caso de uso, creamos funciones de herramientas con sugerencias de tipo visualize_code(url: str) -> straceptando el parámetro de entrada url con formato de cadena y generando la salida como una cadena combinada de todo el código extraído del archivo de origen. Luego, agregue el documento a continuación para ayudar a la LLM a comprender el uso de la herramienta.

    """
    Visualize the code extracted from a Github repository URL in the format of SVG code.

    Args:
        url: The GitHub repository URL
    
    Returns:
        SVG code that visualizes the code structure or hierarchy.
    """

Comparemos cómo funciona la herramienta MCP con y sin documento proporcionado, llamando al servidor MCP a través del escritorio de Claude.

Salida del modelo sin DOCSTRING: solo se genera resumen de texto

Salida del modelo con Docstring proporcionado: se generan tanto el resumen del texto como el diagrama

Lectura adicional:

Paso 5: Configure el servidor MCP

Agregue el bloque de ejecución principal como el último paso en el visual.py guion. Ejecute el servidor localmente con transporte de E/S simple usando “STDIO”. Al ejecutar el código en su máquina local, el servidor MCP se encuentra en su máquina local y escucha las solicitudes de herramientas de los clientes MCP. Para la implementación de producción, puede configurar diferentes opciones de transporte como “Streamable-HTTP” para implementaciones basadas en la web.

if __name__ == "__main__":
    mcp.run(transport='stdio')

Paso 6. Use el servidor MCP desde Claude Desktop

Sin embargo, demostraremos cómo usar este servidor MCP a través de Claude Desktop, tenga en cuenta que permite conectar el servidor a diferentes hosts (por ejemplo, cursor) ajustando ligeramente la configuración. Verificar “Para usuarios de escritorio de Claude – Protocolo de contexto del modelo“Para la guía oficial de Claude.

1. Descargar el Claude Desktop
2. Configurar el archivo de configuración para la configuración del servidor en su carpeta local ~/Library/Application\\ Support/Claude/claude_desktop_config.json (para macOS) y actualizar <PARENT_FOLDER_ABSOLUTE_PATH> a su propia ruta de carpeta de trabajo.

{
    "mcpServers": {
        "visual": {
            "command": "uv",
            "args": [
                "--directory",
                "<PARENT_FOLDER_ABSOLUTE_PATH>/visual",
                "run",
                "visual.py"
            ]
        }
    }
}

3. Ejecutarlo usando la línea de comandos uv --directory <PARENT_FOLDER_ABSOLUTE_PATH>/visual run visual.py
4. Iniciar (o reiniciar) Claude Desktop y seleccione “Búsqueda y herramientas” y luego “Visual”. Deberías poder alternar en el visualize_code herramienta que acabamos de crear.

5. Pruebe la herramienta de visualización proporcionando una URL GitHub, por ejemplo:

Mensaje para llevar a casa

Este artículo proporciona una visión general de MCP Architecture (MCP Cliente, Host y Server), con el enfoque principal en los componentes y aplicaciones del servidor MCP. Se guía a través del proceso de construcción de un servidor MCP personalizado que permita el código a diagrama de los repositorios de GitHub.

Pasos esenciales para construir un servidor MCP personalizado:

1. Configuración del medio ambiente
2. Configuración básica del servidor
3. Crear funciones auxiliares
4. Implementar la herramienta MCP
5. Configurar el servidor MCP
6. Use el servidor MCP desde Claude Desktop

Si está interesado en una exploración adicional, las instrucciones potenciales incluyen explorar servidores MCP remotos en el proveedor de la nube, implementar características de seguridad y manejo de errores sólidos.

Más contenidos como este