Demo MCP Server

A Python MCP (Model Context Protocol) server that demonstrates core capabilities: tools, resources, prompts, and completions.

Características

Arquitectura

El servidor usa el transporte Streamable HTTP (mcp.run(transport="streamable-http")), lo que permite conexiones concurrentes sin el overhead de STDIO.

Cliente MCP (Kilo, VS Code, Inspector)
        │
        │ HTTP/SSE
        │
├─► demo://welcome          [resource estático]
├─► demo://greeting/{name}  [resource template]
├─► add(a, b)               [tool]
├─► send_demo_log()         [tool + logging]
├─► draft_greeting()        [prompt]
├─► complete()              [completions]

Instalación

Prerequisitos

• Python 3.10+
• pip

Setup

# Clonar el repositorio
git clone https://github.com/tu-usuario/mi-mcp.git
cd mi-mcp

# Crear y activar entorno virtual
python -m venv .venv
source .venv/bin/activate  # Linux/macOS
# .venv\Scripts\activate     # Windows

# Instalar dependencias
pip install -r requirements.txt

# Configurar el puerto (opcional)
cp .env.example .env
# Editar .env si necesitas un puerto diferente

Configuración

Uso Rápido

# 1. Iniciar el servidor
.venv/bin/python server.py

# 2. En otra terminal, ejecutar tests
.venv/bin/python test_client.py

Ejemplos de Uso

Tools

User: ¿Cuál es la suma de 15 y 27?
MCP: add(a=15, b=27) → 42

User: Envíame un log al cliente
MCP: send_demo_log() → "Sent an informational log message to the client."

Resources

User: Lee el recurso demo://greeting/Ana
MCP: "Hello, Ana!"

Prompts

User: Crea un prompt de saludo formal para Maya
MCP: "Write a formal greeting for Maya."

Completions

Autocompletado para argumentos de prompts y recursos:

• draft_greeting: name (Ana, Luis, Maya), style (friendly, formal, funny)
• demo://greeting/{name}: name (Ana, Luis, Maya)

Logging

El servidor usa logging estándar de Python. El nivel se configura vía LOG_LEVEL en .env:

# .env
LOG_LEVEL=debug    # debug, info, warning, error, critical

El capability deprecado logging/setLevel (que permitía cambiar el nivel en caliente desde el cliente) fue removido en versión 2.0+ por deprecación de MCP (SEP-2577).

Testing

# Tests end-to-end (requiere el servidor corriendo)
.venv/bin/python test_client.py

Verifica:

• ✅ Inicialización del protocolo (2025-11-25)
• ✅ Tools (list + call)
• ✅ Resources (list, templates, read)
• ✅ Prompts (list + get)
• ✅ Completions (prompt + resource template)

Integración con Clientes MCP

VS Code

El archivo .vscode/mcp.json registra el servidor. Si usas la extensión Kilo Code, abre VS Code en este directorio y el MCP aparecerá en la lista de servidores.

Kilo CLI

El archivo .kilo/kilo.jsonc configura el MCP. En la TUI, usa /mcps para activar/desactivar.

MCP Inspector

⚠️ El Inspector MCP (npx @modelcontextprotocol/inspector) puede solicitar autenticación vía naveador. Si falla, usa la URL directa:

npx @modelcontextprotocol/inspector --cli http://127.0.0.1:8001/mcp --method tools/list

Para modo interactivo (navegador):

npx @modelcontextprotocol/inspector
# Luego conectar a: http://127.0.0.1:8001/mcp

Estructura del Proyecto

mi-mcp/
├── server.py              # Servidor MCP principal
├── test_client.py         # Tests end-to-end
├── requirements.txt       # Dependencias
├── .env.example           # Template de variables de entorno
├── .env                   # Configuración local (no versionada)
├── README.md              # Este archivo
├── LICENSE                # MIT
├── .vscode/
│   └── mcp.json           # Configuración MCP para VS Code
└── .kilo/
    └── kilo.jsonc         # Configuración MCP para Kilo CLI

Protocolos y Versiones