dev-tools-mcp

Un servidor stdio MCP (Model Context Protocol) que le da a Claude Code — o a cualquier cliente MCP — cinco herramientas de desarrollo estructuradas:

Requisitos previos

• Node.js ≥ 18

• Claude Code instalado

• Para la herramienta RLS: psql en tu PATH y una instancia de Supabase/Postgres en ejecución

Inicio rápido

# 1. Clone the repo
git clone https://github.com/briancox730/dev-tools-mcp.git
cd dev-tools-mcp

# 2. Install dependencies
npm install

# 3. Build
npm run build

# 4. Register with Claude Code (local scope — this project only)
claude mcp add --transport stdio dev-tools -- node /absolute/path/to/dev-tools-mcp/build/index.js

# OR register globally (available in all projects)
claude mcp add --transport stdio --scope user dev-tools -- node /absolute/path/to/dev-tools-mcp/build/index.js

Alternativa: editar .claude.json directamente

Añade esto a la clave mcpServers en ~/.claude.json (global) o .claude.json en la raíz de tu proyecto:

{
  "mcpServers": {
    "dev-tools": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/dev-tools-mcp/build/index.js"]
    }
  }
}

Luego reinicia Claude Code.

Verifica que funciona

Dentro de Claude Code, ejecuta /mcp — deberías ver dev-tools: connected con 5 herramientas listadas.

Detalles de las herramientas

1. run_e2e_tests — Ejecutor de E2E de Playwright

Ejecuta Playwright con el reporter JSON y analiza los resultados en una salida estructurada.

Entradas:

• project_dir (obligatorio) — ruta absoluta a tu proyecto

• test_pattern — glob o ruta de archivo para filtrar, p. ej. "tests/auth.spec.ts"

• headed — ejecutar en modo con ventana (por defecto: false)

• start_server — usar la configuración webServer de Playwright (por defecto: true)

• timeout_seconds — terminar después de esta cantidad de segundos (por defecto: 120)

Lo que obtienes:

{
  "success": true,
  "summary": { "passed": 8, "failed": 1, "skipped": 0, "total": 9 },
  "tests": [
    { "name": "Auth > should redirect unauthenticated users", "status": "passed", "duration_ms": 1200 },
    { "name": "Auth > should show dashboard after login", "status": "failed", "duration_ms": 3400, "error": "Expected element to be visible..." }
  ]
}

Consejo: Asegúrate de que tu playwright.config.ts tenga una sección webServer para que Playwright inicie automáticamente tu servidor de desarrollo:

export default defineConfig({
  webServer: {
    command: 'npm run dev',
    port: 3000,
    reuseExistingServer: !process.env.CI,
  },
});

2. execute_sql_as_role — Probador de RLS de Supabase

Ejecuta SQL como un rol específico de Postgres con claims JWT y luego revierte. Nunca muta datos.

Entradas:

• connection_string (obligatorio) — p. ej. "postgresql://postgres:postgres@localhost:54322/postgres"

• sql (obligatorio) — la consulta a ejecutar

• role — rol de Postgres (por defecto: "authenticated")

• user_id — UUID establecido como auth.uid()

• claims — claims JWT adicionales, p. ej. { "app_role": "parent" }

Ejemplo de prompt para Claude Code:

"Ejecuta SELECT * FROM children como un usuario padre autenticado con id abc-123 y confirma que solo pueden ver a sus propios hijos."

Lo que obtienes:

{
  "success": true,
  "role": "authenticated",
  "user_id": "abc-123",
  "query": "SELECT * FROM children",
  "rows": [["id-1", "abc-123", "Alice"], ["id-2", "abc-123", "Bob"]],
  "row_count": 2
}

3. typecheck — Comprobador de TypeScript

Ejecuta tsc --noEmit y analiza la salida en errores estructurados.

Entradas:

• project_dir (obligatorio)

• tsconfig — ruta relativa a tsconfig (por defecto: "tsconfig.json")

• files — comprobar solo archivos específicos

Lo que obtienes:

{
  "success": false,
  "error_count": 2,
  "errors": [
    { "file": "src/utils.ts", "line": 42, "column": 5, "code": "TS2345", "message": "Argument of type 'string' is not assignable..." },
    { "file": "src/api.ts", "line": 18, "column": 12, "code": "TS2339", "message": "Property 'foo' does not exist on type..." }
  ]
}

4. npm_run — Ejecutor estructurado de scripts npm

Ejecuta cualquier script npm con CI=true y FORCE_COLOR=0, y luego analiza la salida de Vitest/Jest.

Entradas:

• project_dir (obligatorio)

• script (obligatorio) — p. ej. "test", "test:unit", "lint"

• args — argumentos adicionales pasados después de --

• env — variables de entorno adicionales

Lo que obtienes:

{
  "success": false,
  "exit_code": 1,
  "script": "test",
  "summary": { "total_tests": 14, "passed_tests": 12, "failed_tests": 2 },
  "file_results": [
    { "file": "src/auth.test.ts", "status": "failed", "tests_failed": 2 },
    { "file": "src/utils.test.ts", "status": "passed", "tests_passed": 5 }
  ],
  "raw_stdout": "..."
}

5. nextjs_build — Validador de build de Next.js

Ejecuta next build en modo producción y analiza errores y salida de páginas.

Entradas:

• project_dir (obligatorio)

• env — variables de entorno adicionales para el build

• timeout_seconds — (por defecto: 180)

Lo que obtienes:

{
  "success": true,
  "error_count": 0,
  "errors": [],
  "pages": [
    { "path": "/", "size_kb": 5.42, "type": "static" },
    { "path": "/dashboard", "size_kb": 12.1, "type": "dynamic" },
    { "path": "/api/auth", "size_kb": 0, "type": "ssr" }
  ],
  "build_duration_ms": 24500
}

Desarrollo

# Watch mode
npm run watch

# Run the unit tests (Vitest)
npm test

# Test interactively with the MCP Inspector
npm run inspect

Pruebas

Los analizadores de salida son la parte más complicada y propensa a regresiones del código base — convierten la salida de consola de formato libre de Vitest/Jest/tsc/next build en JSON estructurado. Esas funciones puras se prueban unitariamente con Vitest en test/; ejecútalas con npm test. CI (ver .github/workflows/ci.yml) ejecuta npm ci, la compilación de TypeScript y la suite de pruebas en Node 20 y 22 para cada push y pull request.

Ideas de personalización

• Añade una herramienta lint que analice la salida JSON de ESLint

• Añade una herramienta prisma_migrate para el estado estructurado de migraciones

• Añade una herramienta docker_compose para gestionar contenedores de prueba

• Conecta la herramienta RLS a Supabase CLI (supabase db test) en lugar de psql directo

Licencia

MIT © 2026 Brian Cox