DevTools MCP

Un pequeño servidor MCP de utilidades para desarrolladores, construido para aprender el Model Context Protocol de principio a fin: implementación de un servidor, pruebas locales, uso de un MCP existente, despliegue público y publicación en Smithery.

1. Descripción general

DevTools MCP expone cuatro pequeñas herramientas de desarrollo a través del Model Context Protocol: explicar un mensaje de error, validar/formatear JSON, generar una regex a partir de una descripción y resumir texto con un LLM (Groq). Un panel minimalista en TypeScript/Vite permite probar las herramientas desde un navegador, conectándose como un cliente MCP real.

Related MCP server: Log Analyzer MCP

2. Por qué MCP

MCP estandariza cómo un host de LLM (Claude Desktop, un IDE, un agente) descubre y llama herramientas, en lugar de que cada proyecto invente su propia API propietaria de invocación de herramientas. El objetivo principal de aprendizaje de este proyecto era construir un servidor MCP real —no una API REST con la etiqueta de MCP pegada—.

3. Arquitectura

MCP Client
    |
MCP Protocol
    |
DevTools MCP Server
    |-- explain_error    (local/deterministic)
    |-- format_json      (local/deterministic)
    |-- generate_regex   (local/deterministic)
    `-- summarize_text
            |
        Groq API
            |
        GPT-OSS 120B

El servidor (server/server.py) es un mcp.server.MCPServer (MCP Python SDK v2). Se ejecuta sobre stdio para las pruebas locales (MCP Inspector, Client(mcp)) y sobre Streamable HTTP (/mcp) para el acceso remoto o desde el navegador. El frontend en TypeScript (frontend/) es un cliente MCP genuino: usa el Client y StreamableHTTPClientTransport de @modelcontextprotocol/sdk para comunicarse con el servidor directamente mediante Streamable HTTP (con CORS habilitado en el servidor), no en un puente REST creado a mano.

4. Herramientas

5. Estructura del proyecto

devtools-mcp/
├── server/
│   ├── server.py               # MCPServer + tool registration + ASGI app
│   ├── tools.py                # explain_error / format_json / generate_regex logic
│   ├── ai.py                   # Groq-backed summarize_text logic
│   └── tests/
│       └── test_server.py      # pytest suite using the SDK's in-memory Client
├── frontend/
│   ├── index.html
│   ├── src/
│   │   ├── main.ts             # real MCP client (StreamableHTTPClientTransport)
│   │   └── style.css
│   ├── package.json
│   ├── tsconfig.json
│   └── vite.config.ts
├── .env.example
├── .gitignore
├── requirements.txt
├── render.yaml                 # optional Render Blueprint
├── README.md
└── EXISTING_MCP_EXPERIENCE.md

6. Prerrequisitos

• Python 3.10+

• Node.js 18+ y npm (para el frontend, y para ejecutar MCP Inspector mediante npx)

• Una clave de API de Groq (solo es necesaria para summarize_text)

• (Opcional, para el despliegue) una cuenta de Render y una de Smithery

7. Instalación

git clone <this-repo>
cd devtools-mcp
python3 -m venv .venv
. .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install -r requirements.txt

8. Variables de entorno

Copia .env.example a .env y rellena lo que necesites:

GROQ_API_KEY=            # required for summarize_text
GROQ_MODEL=openai/gpt-oss-120b
MCP_ALLOWED_HOSTS=        # only needed when deployed behind a real hostname
MCP_ALLOWED_ORIGINS=      # comma-separated browser origins allowed via CORS

.env está en git-ignored. No hagas commit nunca de secretos reales.

9. Configuración local

Stdio (por defecto, para clientes MCP locales):

python -m server.server

Streamable HTTP (para el frontend, o cualquier cliente MCP por HTTP), solo local:

uvicorn server.server:app --host 127.0.0.1 --port 8000

MCP_ALLOWED_HOSTS puede quedarse sin definir en local: la protección integrada del SDK contra DNS rebinding solo en localhost es suficiente para 127.0.0.1/localhost automáticamente. Health check: curl http://127.0.0.1:8000/health.

10. Pruebas con MCP Inspector

# Against stdio:
uv run mcp dev server/server.py     # requires uv; or: npx @modelcontextprotocol/inspector
# Against a running Streamable HTTP server:
npx @modelcontextprotocol/inspector --cli http://127.0.0.1:8000/mcp --method tools/list

Esto se ejecutó contra el servidor Streamable HTTP local de desarrollo y verificó que las cuatro herramientas son localizables con esquemas de entrada/salida correctos (consulta «Testing» más abajo para los resultados concretos).

11. Configuración del frontend

cd frontend
npm install
npm run dev          # http://localhost:5173

En el cockpit en ejecución, configura el campo de la URL del servidor con el endpoint /mcp de tu servidor MCP (por defecto http://localhost:8000/mcp), haz clic en Connect, elige una herramienta, rellena el formulario y haz clic en Run. Para usarlo en local, inicia el backend con MCP_ALLOWED_ORIGINS=http://localhost:5173 para que CORS esté permitido. Construcción para producción: npm run build (genera el resultado en frontend/dist/).

12. Configuración de Groq

1. Crea una clave de API en console.groq.com.

2. Define GROQ_API_KEY (y, opcionalmente, GROQ_MODEL, por defecto openai/gpt-oss-120b) en tu .env o en las variables de entorno de tu plataforma de despliegue.

3. En este proyecto no se utiliza ningún otro proveedor de LLM.

13. Experiencia con un MCP existente

Consulta el archivo EXISTING_MCP_EXPERIENCE.md para ver la demostración requerida de uso de un servidor MCP existente (Context7): qué es, cómo se conectó, la consulta real realizada y lo que se aprendió.

14. Despliegue en Render

Se usa el runtime de Python nativo de Render (no se necesita Docker).

Configuración desde el panel:

1. Haz push de este repositorio a GitHub.

2. En Render: New → Web Service → conecta el repositorio.

3. Runtime: Python 3. Comando de compilación: pip install -r requirements.txt. Comando de inicio: uvicorn server.server:app --host 0.0.0.0 --port $PORT.

4. Configura las variables de entorno: GROQ_API_KEY, GROQ_MODEL, MCP_ALLOWED_HOSTS=<your-service>.onrender.com,<your-service>.onrender.com:*, y MCP_ALLOWED_ORIGINS=<your-frontend-origin> (si también despliegas el frontend).

5. Despliega. El endpoint de MCP será https://<your-service>.onrender.com/mcp.

Se incluye un archivo render.yaml Blueprint como comodidad para la misma configuración.

Se requiere un paso manual de verificación: el despliegue real requiere tu cuenta de Render y no se realizó como parte de esta respuesta; consulta el informe de finalización para ver qué continúa siendo un paso manual.

15. Publicación en Smithery

La CLI actual de Smithery permite publicar directamente la URL de un servidor MCP remoto ya alojado (no hace falta empaquetar Docker/contenedor para esta vía):

npm install -g smithery
smithery auth login
smithery mcp publish "https://<your-service>.onrender.com/mcp" -n "<your-org>/devtools-mcp"

Después de publicar, verifica que las cuatro herramientas quedan expuestas:

smithery mcp add "https://<your-service>.onrender.com/mcp" --id devtools-mcp
smithery tool list devtools-mcp

Paso manual requerido: primero se necesita una cuenta de Smithery y un despliegue de Render en vivo y accesible públicamente; no se realizó como parte de esta respuesta.

16. Uso público del MCP

Una vez desplegado, cualquier cliente MCP mediante Streamable HTTP puede conectarse a:

https://<your-service>.onrender.com/mcp

Ejemplo con el Client del SDK:

from mcp import Client
from mcp.client.streamable_http import streamable_http_client

async with streamable_http_client("https://<your-service>.onrender.com/mcp") as (r, w, _):
    async with Client(r, w) as client:
        await client.initialize()
        print(await client.list_tools())

17. Pruebas

Realmente ejecutado en este entorno:

pytest server/tests/ -v

Resultado: 11 aprobadas — descubrimiento de herramientas; entrada válida, malformada y vacía de format_json; patrones de explain_error coincidentes y no coincidentes (incluida la entrada vacía); generate_regex para un patrón conocido (con una comprobación de coincidencia real de la regex) y una descripción no coincidente; summarize_text con GROQ_API_KEY ausente y con entrada vacía.

También se ejecutó de forma manual (fuera de pytest):

• uvicorn server.server:app se inició correctamente; /health devolvió {"status":"ok",...}.

• Una solicitud initialize POST JSON-RPC sin procesar a /mcp devolvió 200.

• La CLI real del MCP Inspector (npx @modelcontextprotocol/inspector --cli) se conectó por Streamable HTTP, enumeró las cuatro herramientas con esquemas correctos y llamó con éxito a generate_regex, explain_error, format_json (tanto JSON bueno como malo) y a summarize_text (que informó correctamente del error de que no existía la clave de API, porque no había clave real de Groq en este entorno).

• Seguridad del transporte verificada: una solicitud con cabecera suplantada Host recibió correctamente 421 Misdirected Request.

• Preflight CORS verificado: una solicitud OPTIONS /mcp con Origin: http://localhost:5173 devolvió 200 con las cabeceras access-control-* correctas una vez se definió MCP_ALLOWED_ORIGINS.

• Frontend: npx tsc --noEmit pasó sin errores; npm run build tuvo éxito y generó frontend/dist/.

No verificado (requiere cuentas/credenciales externas no disponibles en este entorno): una llamada real de summarize_text con una clave de Groq activa, el despliegue estate en Render y la publicación/el listado en Smithery.

18. Limitaciones

• summarize_text solo se probó de extremo a extremo para sus rutas de error; no se ha llamado con credenciales reales de Groq.

• El despliegue en Render y la publicación en Smithery requieren pasos manuales con tus propias cuentas (consulta las secciones 14 y 15) y no se han representado aquí.

• explain_error y generate_regex usan bibliotecas de patrones pequeños y escritos a mano, no una LLM. Son deliberadamente simples/deterministas, conforme al alcance del proyecto, por lo que no reconocerán todos los errores posibles ni todas las descripciones de patrones.

• El frontend no tiene autenticación y está pensado para uso local/demo, se economización rige proyecto de no usar cuentas ni autenticación.

19. Resultados del aprendizaje

• Qué es el MCP: un protocolo estandarizado que separa “proporcionar contexto/acciones a un LLM” de “la interacción con el propio LLM”, de modo que un servidor creado una vez (como este) funcione con cualquier cliente compatible.

• Host / cliente / servidor: el host es la aplicación LLM (Claude Desktop, o la app detrás del dashboard en navegador); el cliente es el componente que habla MCP dentro de él (el Client del SDK o el cliente basado en StreamableHTTPClientTransport de nuestro frontend); el servidor es lo que hemos construido: nunca habla con un modelo directamente.

• Herramientas vs. recursos vs. prompts: las herramientas están controladas por el modelo (a LLM decide si iniciar format_json); los recursos son cargas de datos controladas por la aplicación; los prompts son plantillas invocadas por el usuario. Este proyecto solo necesitó herramientas.

• Descubrimiento e invocación de herramientas: un cliente llama a tools/list para aprender qué está disponible (nombre, descripción, entrada/salida con JSON Schema, todo derivado automáticamente de los type hints y docstrings), y a continuación llama a tools/call para invocar una por nombre con argumentos.

• Por qué usar MCP y no una API REST simple: una API REST necesita una integración a medida para cada cliente; un servidor MCP describe sus propias capacidades y esquemas, de modo que cualquier host compatible lo puede usar sin pegamento personalizado. Se demostró directamente conectando el mismo servidor tanto a MCP Inspector como a nuestro frontend hecho a mano, sin cambios en el código del servidor.

• Dónde interviene el LLM: solo dentro de summarize_text, que llama a Groq. El resto del servidor es código determinista puro —, un recordatorio útil de que “servidor MCP” no es lo mismo que “aplicación de IA”.

• Realidades del despliegue: los servidores Streamable HTTP usan por defecto una lista blanca de hosts/orígenes restringida solo a localhost como medida de seguridad, y hay que abrirla explícitamente (TransportSecuritySettings) cuando se despliegan detrás de un nombre de host real. Esto se pudo comprobar de primera mano provocando y luego arreglando un 421.