Fuente: Contenido adaptado de anthropics/skills (MIT).

Descripción general

Cree servidores MCP (Protocolo de contexto modelo) que permitan a los LLM interactuar con servicios externos a través de herramientas bien diseñadas. La calidad de un servidor MCP se mide por qué tan bien permite a los LLM realizar tareas del mundo real.

Proceso

Flujo de trabajo de alto nivel

La creación de un servidor MCP de alta calidad implica cuatro fases principales:

Fase 1: Investigación y planificación profundas

1.1 Comprender el diseño MCP moderno

Cobertura de API frente a herramientas de flujo de trabajo: Equilibre la cobertura integral de terminales API con herramientas de flujo de trabajo especializadas. Las herramientas de flujo de trabajo pueden ser más convenientes para tareas específicas, mientras que la cobertura integral brinda a los agentes flexibilidad para componer operaciones. El rendimiento varía según el cliente: algunos clientes se benefician de la ejecución de código que combina herramientas básicas, mientras que otros funcionan mejor con flujos de trabajo de nivel superior. Cuando no esté seguro, priorice la cobertura API integral.

Nombres de herramientas y visibilidad: Los nombres de herramientas claros y descriptivos ayudan a los agentes a encontrar las herramientas adecuadas rápidamente. Utilice prefijos consistentes (por ejemplo,github_create_issue,github_list_repos) y nombres orientados a la acción.

Gestión del contexto: Los agentes se benefician de descripciones concisas de las herramientas y de la capacidad de filtrar/paginar resultados. Diseñe herramientas que devuelvan datos relevantes y enfocados. Algunos clientes admiten la ejecución de código que puede ayudar a los agentes a filtrar y procesar datos de manera eficiente.

Mensajes de error procesables: Los mensajes de error deben guiar a los agentes hacia soluciones con sugerencias específicas y próximos pasos.

1.2 Estudiar la documentación del protocolo MCP

Navega por la especificación MCP:

Comience con el mapa del sitio para encontrar páginas relevantes:https://modelcontextprotocol.io/sitemap.xml

Luego busque páginas específicas con el sufijo.mdpara el formato de rebajas (por ejemplo,https://modelcontextprotocol.io/specification/draft.md).

Páginas clave para revisar:

• Descripción general y arquitectura de las especificaciones
• Mecanismos de transporte (HTTP transmitible, stdio)
• Definiciones de herramientas, recursos y mensajes

1.3 Documentación del marco de estudio

Pila recomendada:

• Idioma: TypeScript (soporte de SDK de alta calidad y buena compatibilidad en muchos entornos de ejecución, por ejemplo, MCPB. Además, los modelos de IA son buenos para generar código TypeScript y se benefician de su amplio uso, escritura estática y buenas herramientas de linting)
• Transporte: HTTP transmisible para servidores remotos, utilizando JSON sin estado (más sencillo de escalar y mantener, a diferencia de sesiones con estado y respuestas de transmisión). stdio para servidores locales.

Cargar documentación del marco:

• Prácticas recomendadas de MCP: Ver prácticas recomendadas: directrices básicas

Para TypeScript (recomendado):

• SDK de TypeScript: use WebFetch para cargarhttps://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md
• Guía de TypeScript - Patrones y ejemplos de TypeScript

Para Pitón:

• SDK de Python: use WebFetch para cargarhttps://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md
• Guía de Python - Patrones y ejemplos de Python

1.4 Planifique su implementación

Comprenda la API: Revise la documentación de la API del servicio para identificar puntos finales clave, requisitos de autenticación y modelos de datos. Utilice la búsqueda web y WebFetch según sea necesario.

Selección de herramientas: Priorice la cobertura integral de API. Enumere los puntos finales a implementar, comenzando con las operaciones más comunes.

Fase 2: Implementación

2.1 Configurar la estructura del proyecto

Consulte las guías específicas del idioma para la configuración del proyecto:

• Guía de TypeScript - Estructura del proyecto, package.json, tsconfig.json
• Guía de Python - Organización del módulo, dependencias

2.2 Implementar la infraestructura central

Crear utilidades compartidas:

• Cliente API con autenticación
• Error al manejar ayudantes
• Formato de respuesta (JSON/Markdown)
• Soporte de paginación

2.3 Implementar herramientas

Para cada herramienta:

Esquema de entrada:

• Utilice Zod (TypeScript) o Pydantic (Python)
• Incluir restricciones y descripciones claras.
• Agregar ejemplos en las descripciones de los campos

Esquema de salida:

• DefinaoutputSchemasiempre que sea posible para datos estructurados.
• UtilicestructuredContenten las respuestas de la herramienta (función TypeScript SDK)
• Ayuda a los clientes a comprender y procesar los resultados de las herramientas.

Descripción de la herramienta:

• Resumen conciso de funcionalidad
• Descripciones de parámetros
• Esquema de tipo de retorno

Implementación:

• Asíncrono/espera para operaciones de E/S
• Manejo adecuado de errores con mensajes procesables
• Paginación de soporte cuando corresponda
• Devuelve tanto contenido de texto como datos estructurados cuando se utilizan SDK modernos

Anotaciones:

• readOnlyHint: verdadero/falso
• destructiveHint: verdadero/falso
• idempotentHint: verdadero/falso
• openWorldHint: verdadero/falso

Fase 3: revisión y prueba

3.1 Calidad del código

Revisión de:

• Sin código duplicado (principio DRY)
• Manejo consistente de errores
• Cobertura de tipo completo
• Descripciones claras de herramientas

3.2 Construir y probar

Mecanografiado:

• Ejecutenpm run buildpara verificar la compilación.
• Prueba con MCP Inspector:npx @modelcontextprotocol/inspector

Pitón:

• Verificar la sintaxis:python -m py_compile your_server.py
• Prueba con MCP Inspector

Consulte las guías específicas del idioma para conocer enfoques de prueba detallados y listas de verificación de calidad.

Fase 4: Crear evaluaciones

Después de implementar su servidor MCP, cree evaluaciones integrales para probar su efectividad.

Cargue Guía de evaluación para obtener pautas de evaluación completas.

4.1 Comprender el propósito de la evaluación

Utilice evaluaciones para comprobar si los LLM pueden utilizar eficazmente su servidor MCP para responder preguntas realistas y complejas.

4.2 Crear 10 preguntas de evaluación

Para crear evaluaciones efectivas, siga el proceso descrito en la guía de evaluación:

1. Inspección de herramientas: enumere las herramientas disponibles y comprenda sus capacidades
2. Exploración de contenido: utilice operaciones de SÓLO LECTURA para explorar los datos disponibles
3. Generación de preguntas: cree 10 preguntas complejas y realistas
4. Verificación de respuestas: Resuelva cada pregunta usted mismo para verificar las respuestas

4.3 Requisitos de evaluación

Asegúrese de que cada pregunta sea:

• Independiente: No depende de otras preguntas
• Solo lectura: solo se requieren operaciones no destructivas
• Complejo: Requiere múltiples llamadas a herramientas y exploración profunda
• Realista: Basado en casos de uso reales que interesarían a los humanos
• Verificable: respuesta única y clara que se puede verificar mediante comparación de cadenas
• Estable: la respuesta no cambiará con el tiempo

4.4 Formato de salida

Cree un archivo XML con esta estructura:

<evaluation>
  <qa_pair>
    <question>Find discussions about AI model launches with animal codenames. One model needed a specific safety designation that uses the format ASL-X. What number X was being determined for the model named after a spotted wild cat?</question>
    <answer>3</answer>
  </qa_pair>
<!-- More qa_pairs... -->
</evaluation>

Archivos de referencia

Biblioteca de documentación

Cargue estos recursos según sea necesario durante el desarrollo:

Documentación principal de MCP (cargar primero)

• Protocolo MCP: comience con el mapa del sitio enhttps://modelcontextprotocol.io/sitemap.xml, luego busque páginas específicas con el sufijo.md
• [Mejores prácticas de MCP] (./reference/mcp_best_practices.md): pautas universales de MCP que incluyen:
  • Convenciones de nomenclatura de servidores y herramientas
  • Directrices de formato de respuesta (JSON frente a Markdown)
  • Mejores prácticas de paginación
  • Selección de transporte (HTTP transmitible frente a stdio)
  • Estándares de seguridad y manejo de errores.

Documentación del SDK (carga durante la fase 1/2)

• SDK de Python: Obtener desdehttps://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md
• SDK de TypeScript: Obtener dehttps://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md

Guías de implementación específicas del idioma (cargar durante la fase 2)

• Guía de implementación de Python - Guía completa de Python/FastMCP con:

  • Patrones de inicialización del servidor
  • Ejemplos de modelos Pydantic
  • Registro de herramientas con@mcp.tool
  • Ejemplos de trabajo completos
  • Lista de control de calidad

• Guía de implementación de TypeScript - Guía completa de TypeScript con:

  • Estructura del proyecto
  • Patrones de esquema Zod
  • Registro de herramientas conserver.registerTool
  • Ejemplos de trabajo completos
  • Lista de control de calidad

Guía de evaluación (carga durante la fase 4)

• Guía de evaluación - Guía completa de creación de evaluaciones con:
  • Pautas para la creación de preguntas
  • Estrategias de verificación de respuestas
  • Especificaciones de formato XML
  • Ejemplos de preguntas y respuestas
  • Ejecutar una evaluación con los scripts proporcionados

Archivos de recursos

LICENCIA.txt

Descargar LICENCIA.txt

Recurso binario

referencia/evaluación.md

Descargar referencia/evaluación.md

Recurso binario

referencia/mcp_best_practices.md

Descargar referencia/mcp_best_practices.md

Recurso binario

referencia/node_mcp_server.md

Descargar referencia/node_mcp_server.md

Recurso binario

referencia/python_mcp_server.md

Descargar referencia/python_mcp_server.md

Recurso binario

scripts/conexiones.py

Descargar scripts/connections.py

"""Lightweight connection handling for MCP servers."""

from abc import ABC, abstractmethod
from contextlib import AsyncExitStack
from typing import Any

from mcp import ClientSession, StdioServerParameters
from mcp.client.sse import sse_client
from mcp.client.stdio import stdio_client
from mcp.client.streamable_http import streamablehttp_client


class MCPConnection(ABC):
    """Base class for MCP server connections."""

    def __init__(self):
        self.session = None
        self._stack = None

    @abstractmethod
    def _create_context(self):
        """Create the connection context based on connection type."""

    async def __aenter__(self):
        """Initialize MCP server connection."""
        self._stack = AsyncExitStack()
        await self._stack.__aenter__()

        try:
            ctx = self._create_context()
            result = await self._stack.enter_async_context(ctx)

            if len(result) == 2:
                read, write = result
            elif len(result) == 3:
                read, write, _ = result
            else:
                raise ValueError(f"Unexpected context result: {result}")

            session_ctx = ClientSession(read, write)
            self.session = await self._stack.enter_async_context(session_ctx)
            await self.session.initialize()
            return self
        except BaseException:
            await self._stack.__aexit__(None, None, None)
            raise

    async def __aexit__(self, exc_type, exc_val, exc_tb):
        """Clean up MCP server connection resources."""
        if self._stack:
            await self._stack.__aexit__(exc_type, exc_val, exc_tb)
        self.session = None
        self._stack = None

    async def list_tools(self) -> list[dict[str, Any]]:
        """Retrieve available tools from the MCP server."""
        response = await self.session.list_tools()
        return [
            {
                "name": tool.name,
                "description": tool.description,
                "input_schema": tool.inputSchema,
            }
            for tool in response.tools
        ]

    async def call_tool(self, tool_name: str, arguments: dict[str, Any]) -> Any:
        """Call a tool on the MCP server with provided arguments."""
        result = await self.session.call_tool(tool_name, arguments=arguments)
        return result.content


class MCPConnectionStdio(MCPConnection):
    """MCP connection using standard input/output."""

    def __init__(self, command: str, args: list[str] = None, env: dict[str, str] = None):
        super().__init__()
        self.command = command
        self.args = args or []
        self.env = env

    def _create_context(self):
        return stdio_client(
            StdioServerParameters(command=self.command, args=self.args, env=self.env)
        )


class MCPConnectionSSE(MCPConnection):
    """MCP connection using Server-Sent Events."""

    def __init__(self, url: str, headers: dict[str, str] = None):
        super().__init__()
        self.url = url
        self.headers = headers or {}

    def _create_context(self):
        return sse_client(url=self.url, headers=self.headers)


class MCPConnectionHTTP(MCPConnection):
    """MCP connection using Streamable HTTP."""

    def __init__(self, url: str, headers: dict[str, str] = None):
        super().__init__()
        self.url = url
        self.headers = headers or {}

    def _create_context(self):
        return streamablehttp_client(url=self.url, headers=self.headers)


def create_connection(
    transport: str,
    command: str = None,
    args: list[str] = None,
    env: dict[str, str] = None,
    url: str = None,
    headers: dict[str, str] = None,
) -> MCPConnection:
    """Factory function to create the appropriate MCP connection.

    Args:
        transport: Connection type ("stdio", "sse", or "http")
        command: Command to run (stdio only)
        args: Command arguments (stdio only)
        env: Environment variables (stdio only)
        url: Server URL (sse and http only)
        headers: HTTP headers (sse and http only)

    Returns:
        MCPConnection instance
    """
    transport = transport.lower()

    if transport == "stdio":
        if not command:
            raise ValueError("Command is required for stdio transport")
        return MCPConnectionStdio(command=command, args=args, env=env)

    elif transport == "sse":
        if not url:
            raise ValueError("URL is required for sse transport")
        return MCPConnectionSSE(url=url, headers=headers)

    elif transport in ["http", "streamable_http", "streamable-http"]:
        if not url:
            raise ValueError("URL is required for http transport")
        return MCPConnectionHTTP(url=url, headers=headers)

    else:
        raise ValueError(f"Unsupported transport type: {transport}. Use 'stdio', 'sse', or 'http'")

scripts/evaluación.py

Descargar scripts/evaluación.py

Recurso binario

scripts/ejemplo_evaluación.xml

Descargar scripts/example_evaluación.xml

Recurso binario

scripts/requisitos.txt

Descargar scripts/requirements.txt

anthropic>=0.39.0
mcp>=1.1.0

Ver en GitHub

Ver en GitHub