🛠️ Servidor MCP DevTools

Un servidor ligero de Protocolo de Contexto de Modelo (MCP) que proporciona a cualquier cliente LLM compatible con MCP (Claude Desktop, Claude Code, Cursor, etc.) una caja de herramientas para desarrolladores: extracción web, inspección de registros, búsqueda web en vivo y consultas SQL de solo lectura contra SQLite o Postgres/Supabase, todo a través de un solo servidor.

🔗 Zona de juegos en vivo: Enlace MCP de Glama — prueba las herramientas directamente en el navegador una vez que esté listado (consulta Implementación).

📖 Descripción general

DevTools MCP expone cuatro herramientas a través de MCP para que un asistente LLM pueda:

• Extraer texto limpio y legible de cualquier página web

• Revisar el final de tus archivos de registro locales para depurar errores

• Buscar en la web en vivo documentación actual antes de escribir código

• Ejecutar consultas SELECT de solo lectura contra un archivo SQLite local o una base de datos Postgres/Supabase en vivo

Cada herramienta es una función de Python simple y comprobable; nada aquí depende de APIs de pago excepto tu propio proyecto Supabase opcional.

Related MCP server: FireScrape MCP Server

✨ Características

🏗️ Arquitectura

┌──────────────────────┐
│    MCP Client         │   (Claude Desktop / Claude Code / Cursor / etc.)
└──────────┬────────────┘
           │ MCP protocol (stdio)
┌──────────▼────────────┐
│  DevTools MCP Server   │   FastMCP("DevTools")   — server.py
│                        │
│  ┌──────────────────┐  │
│  │ fetch_markdown    │  │──▶ requests + BeautifulSoup ──▶ any URL
│  ├──────────────────┤  │
│  │ read_log          │  │──▶ local filesystem
│  ├──────────────────┤  │
│  │ search_web        │  │──▶ DDGS (DuckDuckGo, key-free)
│  ├──────────────────┤  │
│  │ query_database     │  │──▶ _is_safe_select()  (SQL safety gate)
│  │                    │  │      │
│  │                    │  │      ├──▶ _query_sqlite()   ──▶ local .db file
│  │                    │  │      └──▶ _query_postgres() ──▶ Postgres / Supabase
│  └──────────────────┘  │
└────────────────────────┘

Cómo query_database decide dónde enviar una consulta

query_database(db_path_or_url, sql_query, limit)
        │
        ▼
  _is_safe_select(sql_query)?
        │
   ┌────┴────┐
   NO         YES
   │           │
 reject   does db_path_or_url start with
 query    "postgres://" or "postgresql://" ?
              │
        ┌─────┴─────┐
        YES           NO
        │             │
 _query_postgres()  _query_sqlite()

_is_safe_select es una puerta estricta que solo permite sentencias SELECT simples y únicas, sin INSERT/UPDATE/DELETE/DROP/ALTER/etc., y sin consultas encadenadas con ;. Esto es importante porque el texto SQL lo genera un LLM, no se escribe a mano: la puerta existe para que una consulta alucinada o manipulada no pueda mutar o destruir tus datos.

Pila tecnológica:

• fastmcp — marco de servidor MCP; convierte funciones de Python en herramientas MCP mediante @mcp.tool

• requests + beautifulsoup4 — extracción web

• ddgs — búsqueda web en vivo sin clave (anteriormente duckduckgo-search)

• sqlite3 — integrado en Python, se usa para consultas de bases de datos locales

• psycopg2 — cliente de Postgres/Supabase, se importa de forma diferida solo cuando se usa una URL de Postgres

• python-dotenv — carga variables .env locales

• pytest + pytest-mock — suite de pruebas

📂 Estructura del proyecto

.
├── venv/                # Local virtual environment (not committed)
├── .env                 # Local secrets — real keys/paths, never committed
├── .gitignore
├── README.md
├── requirements.txt      # Runtime + dev/test dependencies
├── server.py             # Main MCP server — all 4 tools live here
├── test_server.py        # Pytest suite covering all 4 tools
├── Dockerfile             # Optional — only needed for Glama's hosted deployment
├── glama.json             # Optional — repo attribution for Glama's listing
└── smithery.yaml         # Optional — only relevant if also listing on Smithery

🚀 Primeros pasos

1. Clona el repositorio

git clone https://github.com/YOUR_USERNAME/YOUR_REPO.git
cd YOUR_REPO

2. Crea un entorno virtual e instala las dependencias

python -m venv venv
source venv/bin/activate   # On Windows: venv\Scripts\activate

pip install -r requirements.txt

3. Configura las variables de entorno (opcional)

server.py llama a load_dotenv() al iniciar, por lo que cualquier variable en un archivo .env local se recoge automáticamente. Ninguna de las herramientas actuales requiere variables de entorno: query_database toma su información de conexión como parámetro directo, pero es posible que quieras un .env por conveniencia local:

# Only needed if you want a default connection string handy locally.
# Real credentials should live here and nowhere else.
SUPABASE_DB_URL=postgresql://postgres:your-password@db.xxxxxxxx.supabase.co:5432/postgres

⚠️ Nunca subas tu archivo .env. Ya está excluido mediante .gitignore.

Nota: esto es diferente de SUPABASE_URL / SUPABASE_KEY de un proyecto de Supabase (usado por el cliente REST/JS). query_database se comunica con Postgres directamente a través de psycopg2, por lo que necesita la cadena de conexión de Postgres desde tu panel de Supabase en Configuración → Base de datos → Cadena de conexión, no la URL de API/par de claves.

4. Ejecuta el servidor localmente

python server.py

Esto inicia el servidor MCP a través de stdio, listo para conectarse a cualquier cliente MCP.

🔌 Conexión a Claude Desktop / Claude Code

Añade el servidor a la configuración de tu cliente MCP (por ejemplo, claude_desktop_config.json):

{
  "mcpServers": {
    "devtools": {
      "command": "python",
      "args": ["/absolute/path/to/server.py"]
    }
  }
}

Reinicia tu cliente: las cuatro herramientas (fetch_markdown, read_log, search_web, query_database) aparecerán como funciones que el asistente puede llamar.

🧰 Referencia de herramientas

fetch_markdown(url: str) -> str

Obtiene una página web, elimina las etiquetas <script>, <style>, <nav> y <footer>, y devuelve texto plano limpio (limitado a 8,000 caracteres).

fetch_markdown("https://docs.python.org/3/library/asyncio.html")

read_log(file_path: str, lines: int = 50) -> str

Lee las últimas lines líneas de un archivo de texto/registro local.

read_log("/var/log/app/error.log", lines=100)

search_web(query: str, max_results: int = 3) -> str

Busca en DuckDuckGo la consulta dada y devuelve título, enlace y fragmento para cada resultado.

search_web("fastapi background tasks example")

query_database(db_path_or_url: str, sql_query: str, limit: int = 50) -> str

Ejecuta un SELECT de solo lectura contra:

• un archivo SQLite local (pasa una ruta de archivo), o

• una base de datos Postgres/Supabase (pasa una cadena de conexión que comience con postgres:// o postgresql://)

Los resultados se devuelven como una lista de diccionarios {columna: valor}, limitada a limit filas.

query_database("app.db", "SELECT * FROM users WHERE status = 'active'", limit=5)
query_database("postgresql://user:pass@host:5432/db", "SELECT id, email FROM users", limit=10)

Garantías de seguridad:

• Solo se permiten consultas que comiencen con SELECT

• Se rechazan consultas que contengan INSERT, UPDATE, DELETE, DROP, ALTER, TRUNCATE, GRANT, REVOKE, CREATE o ATTACH en cualquier parte

• Se rechazan consultas apiladas (SELECT ...; DROP TABLE ...)

• Limitación conocida: la verificación es una coincidencia de subcadena, no un analizador SQL completo; una consulta inofensiva como SELECT * FROM updates_log también se rechazará, ya que contiene la subcadena update. Esto es un equilibrio deliberado entre falsos positivos y falsos negativos.

🧪 Pruebas

El proyecto incluye una suite de 27 pruebas pytest que cubre las cuatro herramientas, ejecutadas completamente sin conexión mediante llamadas de red simuladas y accesorios tmp_path desechables; nada toca un archivo, base de datos o sitio web real.

pip install -r requirements.txt
pytest test_server.py -v

Lo que se cubre:

• _is_safe_select — más de 10 casos que abarcan selecciones válidas, cada palabra clave prohibida, consultas apiladas y el comportamiento conocido de falsos positivos

• query_database (SQLite) — selección básica, limit, filtrado con WHERE, consultas no seguras bloqueadas, archivo faltante, tabla faltante, conjunto de resultados vacío y enrutamiento de URL de Postgres (simulado)

• read_log — comportamiento de cola, archivo faltante, número de líneas predeterminado

• fetch_markdown — eliminación de HTML y manejo de errores (red simulada)

• search_web — formato de resultados, resultados vacíos, manejo de errores (red simulada)

_query_postgres en sí no se prueba contra una base de datos en vivo en esta suite; solo se prueba la lógica de enrutamiento que decide si llamarla. Probarla en vivo requiere una cadena de conexión real de Postgres/Supabase, que nunca debe codificarse en archivos de prueba ni subirse al repositorio.

🌐 Implementación

Opción A — Glama (listado gratuito + inspector en navegador)

Envía la URL de GitHub de este repositorio en glama.ai/mcp — Glama indexa tus herramientas directamente desde el código fuente, sin necesidad de compilación ni manifiesto. Los visitantes obtienen un inspector en el navegador para probar fetch_markdown, read_log, search_web y query_database sin instalar nada localmente.

Opcional: añade glama.json (ya incluido) para reclamar/atribuir el listado a tu cuenta de GitHub.

Opción B — Alojamiento gestionado por Glama (Glama lo ejecuta por ti, 24/7)

Conecta la aplicación de GitHub de Glama a este repositorio y compilará el Dockerfile incluido en una instancia en ejecución detrás de la puerta de enlace de Glama (TLS gestionado, autenticación, registro). Consulta glama.ai/mcp/hosting para conocer los detalles del plan actual antes de comprometerte con esta vía.

Opción C — Smithery

⚠️ A principios de 2026, Smithery ya no acepta nuevas implementaciones gratuitas alojadas a través de GitHub; eso ahora requiere un plan de pago. La vía gratuita en Smithery es registrar este servidor como servidor externo (es decir, tú lo alojas tú mismo, por ejemplo, mediante la opción alojada de Glama anterior, y solo apuntas el listado de Smithery a esa URL). smithery.yaml todavía está incluido en este repositorio por si eliges esa ruta; consulta smithery.ai para obtener detalles actuales, ya que su modelo de alojamiento está cambiando activamente.

🔐 Variables de entorno

query_database es intencionalmente sin estado con respecto a las credenciales: no se lee nada de las variables de entorno dentro de la propia herramienta, por lo que no se almacenan credenciales de base de datos en el servidor de forma predeterminada.

🗺️ Hoja de ruta

• Añadir una prueba de integración real contra una instancia desechable de Postgres/Supabase (solo CI, credenciales nunca subidas)

• Reemplazar la verificación de palabras clave SQL basada en subcadenas con un analizador SQL adecuado (por ejemplo, sqlparse) para eliminar falsos positivos

• Añadir caché para search_web y fetch_markdown

• Añadir una capa de autenticación para implementaciones alojadas en Smithery

🤝 Contribuciones

Las contribuciones, problemas y solicitudes de funciones son bienvenidos: no dudes en abrir un PR o un issue.

📄 Licencia

Este proyecto está licenciado bajo la Licencia MIT.