Guía de Desarrollo de Servidores MCP
Resumen
Crea servidores MCP (Model Context Protocol) que permitan a los LLMs interactuar con servicios externos a través de herramientas bien diseñadas. La calidad de un servidor MCP se mide por lo bien que permite a los LLMs realizar tareas del mundo real.
Proceso
🚀 Flujo de Trabajo de Alto Nivel
Crear un servidor MCP de alta calidad implica cuatro fases principales:
Fase 1: Investigación y Planificación Profunda
1.1 Comprender el Diseño MCP Moderno
Cobertura de API vs. Herramientas de Flujo de Trabajo: Equilibra la cobertura completa de endpoints de 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 completa 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 alto nivel. Cuando tengas dudas, prioriza la cobertura completa de la API.
Nomenclatura y Descubrimiento de Herramientas:
Los nombres de herramientas claros y descriptivos ayudan a los agentes a encontrar las herramientas adecuadas rápidamente. Usa prefijos consistentes (por ejemplo, github_create_issue, github_list_repos) y nombres orientados a la acción.
Gestión de Contexto: Los agentes se benefician de descripciones de herramientas concisas y la capacidad de filtrar/paginar resultados. Diseña herramientas que devuelvan datos enfocados y relevantes. Algunos clientes admiten la ejecución de código, lo que puede ayudar a los agentes a filtrar y procesar datos de manera eficiente.
Mensajes de Error Accionables: 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:
Comienza con el mapa del sitio para encontrar páginas relevantes: https://modelcontextprotocol.io/sitemap.xml
Luego, obtén páginas específicas con el sufijo .md para formato markdown (por ejemplo, https://modelcontextprotocol.io/specification/draft.md).
Páginas clave a revisar:
- Resumen de especificación y arquitectura
- Mecanismos de transporte (HTTP transmisible, stdio)
- Definiciones de herramientas, recursos y prompts
1.3 Estudiar la Documentación del Framework
Stack recomendado:
- Lenguaje: 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 generando código TypeScript, beneficiándose de su amplio uso, tipado estático y buenas herramientas de linting)
- Transporte: HTTP transmisible para servidores remotos, usando JSON sin estado (más simple de escalar y mantener, en comparación con sesiones con estado y respuestas en streaming). stdio para servidores locales.
Carga la documentación del framework:
- Mejores Prácticas MCP: 📋 Ver Mejores Prácticas - Directrices principales
Para TypeScript (recomendado):
- SDK TypeScript: Usa WebFetch para cargar
https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md - ⚡ Guía de TypeScript - Patrones y ejemplos de TypeScript
Para Python:
- SDK Python: Usa WebFetch para cargar
https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md - 🐍 Guía de Python - Patrones y ejemplos de Python
1.4 Planificar tu Implementación
Comprender la API: Revisa la documentación de la API del servicio para identificar endpoints clave, requisitos de autenticación y modelos de datos. Usa la búsqueda web y WebFetch según sea necesario.
Selección de Herramientas: Prioriza la cobertura completa de la API. Enumera los endpoints a implementar, comenzando con las operaciones más comunes.
Fase 2: Implementación
2.1 Configurar la Estructura del Proyecto
Consulta las guías específicas del lenguaje para la configuración del proyecto:
- ⚡ Guía de TypeScript - Estructura del proyecto, package.json, tsconfig.json
- 🐍 Guía de Python - Organización de módulos, dependencias
2.2 Implementar la Infraestructura Principal
Crea utilidades compartidas:
- Cliente de API con autenticación
- Ayudantes de manejo de errores
- Formateo de respuestas (JSON/Markdown)
- Soporte de paginación
2.3 Implementar Herramientas
Para cada herramienta:
Esquema de Entrada:
- Usa Zod (TypeScript) o Pydantic (Python)
- Incluye restricciones y descripciones claras
- Añade ejemplos en las descripciones de los campos
Esquema de Salida:
- Define
outputSchemasiempre que sea posible para datos estructurados - Usa
structuredContenten las respuestas de las herramientas (característica del SDK TypeScript) - Ayuda a los clientes a entender y procesar las salidas de las herramientas
Descripción de la Herramienta:
- Resumen conciso de la funcionalidad
- Descripciones de los parámetros
- Esquema del tipo de retorno
Implementación:
- Async/await para operaciones de E/S
- Manejo de errores adecuado con mensajes accionables
- Soporte de paginación donde corresponda
- Devuelve tanto contenido de texto como datos estructurados cuando se usen SDKs modernos
Anotaciones:
readOnlyHint: true/falsedestructiveHint: true/falseidempotentHint: true/falseopenWorldHint: true/false
Fase 3: Revisión y Pruebas
3.1 Calidad del Código
Revisa lo siguiente:
- Sin código duplicado (principio DRY)
- Manejo de errores consistente
- Cobertura completa de tipos
- Descripciones de herramientas claras
3.2 Compilación y Pruebas
TypeScript:
- Ejecuta
npm run buildpara verificar la compilación - Prueba con MCP Inspector:
npx @modelcontextprotocol/inspector
Python:
- Verifica la sintaxis:
python -m py_compile tu_servidor.py - Prueba con MCP Inspector
Consulta las guías específicas del lenguaje para enfoques de prueba detallados y listas de verificación de calidad.
Fase 4: Crear Evaluaciones
Después de implementar tu servidor MCP, crea evaluaciones completas para probar su efectividad.
Carga la ✅ Guía de Evaluación para directrices completas de evaluación.
4.1 Comprender el Propósito de la Evaluación
Usa las evaluaciones para probar si los LLMs pueden usar tu servidor MCP de manera efectiva para responder preguntas realistas y complejas.
4.2 Crear 10 Preguntas de Evaluación
Para crear evaluaciones efectivas, sigue el proceso descrito en la guía de evaluación:
- Inspección de Herramientas: Enumera las herramientas disponibles y comprende sus capacidades
- Exploración de Contenido: Usa operaciones de SOLO LECTURA para explorar los datos disponibles
- Generación de Preguntas: Crea 10 preguntas complejas y realistas
- Verificación de Respuestas: Resuelve cada pregunta tú mismo para verificar las respuestas
4.3 Requisitos de Evaluación
Asegúrate de que cada pregunta sea:
- Independiente: No dependiente de otras preguntas
- Solo lectura: Solo se requieren operaciones no destructivas
- Compleja: Requiere múltiples llamadas a herramientas y exploración profunda
- Realista: Basada en casos de uso reales que importarían a los humanos
- Verificable: Una única respuesta clara que se pueda verificar mediante comparación de cadenas
- Estable: La respuesta no cambiará con el tiempo
4.4 Formato de Salida
Crea un archivo XML con esta estructura:
<evaluation>
<qa_pair>
<question>Encuentra discusiones sobre lanzamientos de modelos de IA con nombres en clave de animales. Un modelo necesitaba una designación de seguridad específica que usa el formato ASL-X. ¿Qué número X se estaba determinando para el modelo con nombre de un gato salvaje manchado?</question>
<answer>3</answer>
</qa_pair>
<!-- Más qa_pairs... -->
</evaluation>
Archivos de Referencia
📚 Biblioteca de Documentación
Carga estos recursos según sea necesario durante el desarrollo:
Documentación Principal de MCP (Cargar Primero)
- Protocolo MCP: Comienza con el mapa del sitio en
https://modelcontextprotocol.io/sitemap.xml, luego obtén páginas específicas con el sufijo.md - 📋 Mejores Prácticas MCP - Directrices universales de MCP que incluyen:
- Convenciones de nomenclatura de servidores y herramientas
- Directrices de formato de respuesta (JSON vs Markdown)
- Mejores prácticas de paginación
- Selección de transporte (HTTP transmisible vs stdio)
- Estándares de seguridad y manejo de errores
Documentación del SDK (Cargar Durante la Fase 1/2)
- SDK Python: Obtener de
https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md - SDK TypeScript: Obtener de
https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md
Guías de Implementación Específicas del Lenguaje (Cargar Durante la Fase 2)
-
🐍 Guía de Implementación en Python - Guía completa de Python/FastMCP con:
- Patrones de inicialización de servidores
- Ejemplos de modelos Pydantic
- Registro de herramientas con
@mcp.tool - Ejemplos completos funcionales
- Lista de verificación de calidad
-
⚡ Guía de Implementación en TypeScript - Guía completa de TypeScript con:
- Estructura del proyecto
- Patrones de esquema Zod
- Registro de herramientas con
server.registerTool - Ejemplos completos funcionales
- Lista de verificación de calidad
Guía de Evaluación (Cargar Durante la Fase 4)
- ✅ Guía de Evaluación - Guía completa de creación de evaluaciones con:
- Directrices de creación de preguntas
- Estrategias de verificación de respuestas
- Especificaciones de formato XML
- Ejemplos de preguntas y respuestas
- Ejecución de una evaluación con los scripts proporcionados