Plantilla de servidor MCP

Una implementación de servidor MCP (Model Context Protocol) mínima y bien documentada, diseñada para servir como base reutilizable para crear servidores MCP personalizados.

¿Qué es MCP?

El Model Context Protocol (MCP) es un protocolo estandarizado que permite a los asistentes de IA interactuar con servidores externos. Los servidores MCP pueden proporcionar:

• Herramientas (Tools): Funciones que la IA puede llamar para realizar acciones

• Recursos (Resources): Datos estáticos o dinámicos que la IA puede leer

• Prompts: Plantillas de prompts reutilizables para interacciones consistentes con la IA

Related MCP server: MCP Mingdao

Características

Esta plantilla proporciona:

• Estructura mínima: Base limpia que puede extenderse fácilmente

• Documentación extensa: Comentarios en línea y archivos de documentación separados

• Diagramas de arquitectura: Diagramas Mermaid que muestran las interacciones de los componentes

• Guía de escalado: Mejores prácticas para hacer crecer su servidor

• Sugerencias de tipo (Type hints): Anotaciones de tipo completas para un mejor soporte en el IDE

• Async/await: E/S sin bloqueo para operaciones concurrentes

Plantillas de Prompts Reutilizables

Los prompts son plantillas reutilizables que le permiten definir prompts estructurados con marcadores de posición. Permiten:

• Consistencia: Formatos de prompt estandarizados en diferentes interacciones con la IA

• Parametrización: Inserción de contenido dinámico a través de argumentos

• Reutilizabilidad: Definir una vez, usar múltiples veces con diferentes entradas

• Seguridad de tipos: Esquemas de argumentos definidos con validación

Una plantilla de prompt consiste en:

• Nombre: Identificador único para el prompt

• Descripción: Qué hace el prompt

• Argumentos: Parámetros opcionales que se pueden completar al usar el prompt

Ejemplos de casos de uso:

• Plantillas de revisión de código con niveles de severidad configurables

• Generación de documentación con tono personalizable

• Prompts de análisis con áreas de enfoque variables

• Generación de informes con diferentes formatos de salida

Estructura del Proyecto

windsurf-project-3/
├── mcp_server.py          # Main server implementation with extensive comments
├── pyproject.toml         # Project configuration for uv
├── ARCHITECTURE.md        # Architecture documentation with Mermaid diagrams
├── SCALING_GUIDE.md       # Scaling patterns and best practices
├── README.md              # This file
├── tools/                 # Placeholder for tool modules (create as needed)
├── resources/             # Placeholder for resource modules (create as needed)
├── prompts/               # Placeholder for prompt modules (create as needed)
└── utils/                 # Placeholder for utility modules (create as needed)

Instalación

Este proyecto utiliza uv para una gestión rápida de paquetes de Python.

1. Instale Python 3.10 o superior

2. Instale uv (si aún no está instalado):

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

3. Instale las dependencias:

uv sync

Inicio Rápido

1. Añada su primera herramienta

Edite mcp_server.py y añada una herramienta en la función list_tools():

@app.list_tools()
async def list_tools() -> list[Tool]:
    return [
        Tool(
            name="echo",
            description="Echo back the input text",
            inputSchema={
                "type": "object",
                "properties": {
                    "text": {"type": "string", "description": "Text to echo"}
                },
                "required": ["text"]
            }
        )
    ]

2. Implemente el manejador de la herramienta

Añada la lógica de la herramienta en la función call_tool():

@app.call_tool()
async def call_tool(name: str, arguments: Any) -> str:
    if name == "echo":
        text = arguments.get("text", "")
        return f"Echo: {text}"
    raise ValueError(f"Unknown tool: {name}")

3. Añada un prompt (Opcional)

Añada un prompt en la función list_prompts():

@app.list_prompts()
async def list_prompts() -> list[Prompt]:
    return [
        Prompt(
            name="example_prompt",
            description="An example prompt template",
            arguments=[
                PromptArgument(
                    name="topic",
                    description="The topic to write about",
                    required=True
                )
            ]
        )
    ]

Luego implemente el manejador en get_prompt():

@app.get_prompt()
async def get_prompt(name: str, arguments: dict[str, str] | None) -> str:
    if name == "example_prompt":
        topic = arguments.get("topic") if arguments else None
        if not topic:
            raise ValueError("Argument 'topic' is required")
        return f"Write a detailed explanation about {topic}."
    raise ValueError(f"Unknown prompt: {name}")

3. Ejecute el servidor

uv run python mcp_server.py

4. Configure su cliente MCP

Añada esto a la configuración de su cliente MCP:

{
  "mcpServers": {
    "your-server-name": {
      "command": "uv",
      "args": ["run", "python", "/path/to/mcp_server.py"]
    }
  }
}

Documentación

• ARCHITECTURE.md: Documentación detallada de la arquitectura con diagramas Mermaid que muestran:

  • Módulos de Python y sus propósitos

  • Interacciones de componentes

  • Flujos de solicitud (invocación de herramientas, lectura de recursos)

  • Patrones de diseño utilizados

• SCALING_GUIDE.md: Mejores prácticas para escalar su servidor:

  • Patrones de modularización

  • Estrategias de gestión de estado

  • Patrones de manejo de errores

  • Registro y monitoreo

  • Gestión de configuración

  • Estrategias de prueba

  • Optimización del rendimiento

  • Consideraciones de seguridad

Estructura del Código

El archivo principal del servidor (mcp_server.py) está organizado en secciones:

1. Inicialización del servidor: Crear la instancia del servidor MCP

2. Registro de herramientas: Definir las herramientas disponibles

3. Manejadores de herramientas: Implementar la lógica de ejecución de herramientas

4. Registro de recursos: Definir los recursos disponibles

5. Manejadores de recursos: Implementar la lógica de lectura de recursos

6. Punto de entrada: Iniciar el servidor con comunicación stdio

Cada sección incluye comentarios extensos en línea que explican el propósito y el uso de cada componente.

Puntos de Extensión

Añadir herramientas

1. Defina la herramienta en list_tools() con su esquema

2. Implemente el manejador en call_tool()

3. Para proyectos más grandes, muévalo a un módulo separado en el directorio tools/

Añadir prompts

1. Defina el prompt en list_prompts() con sus argumentos

2. Implemente el manejador en get_prompt()

3. Para proyectos más grandes, muévalo a un módulo separado en el directorio prompts/

Añadir recursos

1. Defina el recurso en list_resources() con sus metadatos

2. Implemente el manejador en read_resource()

3. Para proyectos más grandes, muévalo a un módulo separado en el directorio resources/

Añadir utilidades

Extraiga el código compartido en el directorio utils/:

• Funciones de validación

• Ayudantes de registro

• Gestión de configuración

• Utilidades de manejo de errores

Uso como base

Esta plantilla está diseñada para ser copiada y modificada para nuevos proyectos:

1. Copie todo el directorio del proyecto

2. Cambie el nombre del proyecto en pyproject.toml

3. Actualice el nombre del servidor en mcp_server.py

4. Añada sus herramientas, recursos y prompts

5. Personalice la documentación según sea necesario

Módulos de Python utilizados

• mcp.server.Server: Clase principal del servidor MCP

• mcp.types.Tool: Definición del tipo de herramienta

• mcp.types.Resource: Definición del tipo de recurso

• mcp.types.Prompt: Definición del tipo de prompt

• mcp.types.PromptArgument: Definición del tipo de argumento de prompt

• mcp.server.stdio: Flujos de comunicación stdio

• asyncio: Async/await para operaciones concurrentes

• typing: Sugerencias de tipo para mayor claridad del código

Consulte ARCHITECTURE.md para obtener explicaciones detalladas de cada módulo.

Desarrollo

Ejecución de pruebas

# Run with pytest (add tests first)
uv run pytest

Estilo de código

Este proyecto utiliza sugerencias de tipo de Python y sigue las convenciones de PEP 8. Considere usar:

• ruff para linting

• mypy para comprobación de tipos

Añadir dependencias

uv add <package-name>

Solución de problemas

• Error de importación: Ejecute uv sync para instalar las dependencias

• El servidor no responde: Compruebe la configuración del cliente MCP

• Errores de tipo: Asegúrese de que Python 3.10+ esté instalado

• Comando uv no encontrado: Instale uv desde https://github.com/astral-sh/uv

Recursos

• Especificación MCP

• SDK de Python para MCP

• Documentación de uv

Licencia

Esta plantilla se proporciona tal cual para fines educativos y de desarrollo. Siéntase libre de usarla y modificarla para sus proyectos.