Un servidor stdio MCP (Model Context Protocol) que le da a Claude Code — o a cualquier cliente MCP — cinco herramientas de desarrollo estructuradas:
# | Herramienta | Qué hace |
1 |
| Ejecuta pruebas de Playwright, inicia el servidor de desarrollo y devuelve aprobado/fallido por prueba |
2 |
| Ejecuta SQL como un rol de Postgres con claims JWT — verifica Supabase RLS |
3 |
| Ejecuta |
4 |
| Ejecuta cualquier script de npm, analiza la salida de Vitest/Jest en resultados estructurados |
5 |
| Ejecuta |
Node.js ≥ 18
Claude Code instalado
Para la herramienta RLS: psql en tu PATH y una instancia de Supabase/Postgres en ejecución
Related MCP server: groundtruth-mcp
# 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.claude.json directamenteAñ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.
Dentro de Claude Code, ejecuta /mcp — deberías ver dev-tools: connected con 5 herramientas listadas.
run_e2e_tests — Ejecutor de E2E de PlaywrightEjecuta 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,
},
});execute_sql_as_role — Probador de RLS de SupabaseEjecuta 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 childrencomo un usuario padre autenticado con idabc-123y 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
}typecheck — Comprobador de TypeScriptEjecuta 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..." }
]
}npm_run — Ejecutor estructurado de scripts npmEjecuta 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": "..."
}nextjs_build — Validador de build de Next.jsEjecuta 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
}# Watch mode
npm run watch
# Run the unit tests (Vitest)
npm test
# Test interactively with the MCP Inspector
npm run inspectLos 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.
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
MIT © 2026 Brian Cox
Executes a SQL query as a specific Postgres role with JWT claims set, so you can verify RLS policies. Runs inside a ROLLBACK transaction — never mutates data.
| Name | Required | Description | Default |
|---|---|---|---|
| sql | Yes | The SQL query to execute | |
| role | No | Postgres role to SET ROLE to, e.g. 'authenticated', 'anon', 'service_role' | authenticated |
| claims | No | Additional JWT claims to set, e.g. { "role": "parent" }. Merged into request.jwt.claims. | |
| user_id | No | UUID to set as request.jwt.claims sub (auth.uid()). Required for RLS policies that check auth.uid(). | |
| timeout_seconds | No | ||
| connection_string | Yes | Postgres connection string, e.g. postgresql://postgres:password@localhost:54322/postgres |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must disclose behavior. It explicitly states the tool runs inside a ROLLBACK transaction and never mutates data—a critical safety guarantee. It also mentions setting JWT claims. It does not cover error handling or timeout behavior, but the core safety trait is transparently disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no fluff: the first states what and why, the second highlights the safety behavior. The purpose is front-loaded, making it easy for an agent to quickly grasp the tool's value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (role switching, nested claims) and no output schema, the description covers purpose and safety well. It does not mention return values (e.g., query results) or prerequisites like a running database, but these are implied. Slightly more context on expected output would make it fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 83%, so most parameters are already documented. The description adds no extra parameter meaning beyond the schema. The uncovered parameter (timeout_seconds) is not mentioned, but with high schema coverage, the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (Executes), the resource (SQL query), and the purpose (verify RLS policies). It adds specificity with role and JWT claims, and the purpose distinguishes it from unrelated sibling tools like run_e2e_tests or typecheck.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The usage is implied: 'so you can verify RLS policies' indicates when to use. The ROLLBACK safety note suggests it's safe for testing. However, it does not explicitly state when not to use it or mention alternatives, though siblings are irrelevant. The guidance is clear but not exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Runs next build and returns structured errors (TypeScript, module, page-level) plus a list of generated pages with their render types and sizes.
| Name | Required | Description | Default |
|---|---|---|---|
| env | No | Extra env vars for the build, e.g. { NEXT_PUBLIC_API_URL: '...' } | |
| project_dir | Yes | Absolute path to the Next.js project root | |
| timeout_seconds | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are completely absent, so the description must disclose behavioral traits. It mentions running a build and returning errors, but omits side effects like the creation/modification of build artifacts (e.g., .next directory), potential long execution time (timeout parameter exists), and that a failed build may still return partial output. The description does not fully cover the tool's impact or failure modes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, concise sentence that front-loads the core command and lists key outputs with no filler. Efficiently communicates essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description provides some return-value detail (structured error types and page list) but lacks full context: no output schema, no mention of side effects, environment requirements, or how to interpret the results. It gives a reasonable overview but is incomplete for a tool that runs a full build without annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 67% of parameters (env and project_dir have descriptions; timeout_seconds does not). The description adds no extra parameter context beyond what the schema provides, though the missing timeout parameter is self-explanatory. Since coverage is moderate but the description adds no value, a score of 3 is appropriate—adequate but not insightful.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Runs next build') and the specific outcomes (structured errors and generated pages list). It distinguishes itself from siblings like typecheck and npm_run by being Next.js-specific and producing build validation output. No ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives (e.g., typecheck, npm_run). It does not state prerequisites, like that a Next.js project must exist, or when it should be preferred over other validation tools. The agent is left to infer usage from the name and output description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Runs any npm script (test, lint, etc.) and parses Vitest/Jest output into structured pass/fail results per file. Falls back to raw output for non-test scripts.
| Name | Required | Description | Default |
|---|---|---|---|
| env | No | Extra environment variables | |
| args | No | Extra args passed after --, e.g. ['--coverage', '--verbose'] | |
| script | Yes | npm script name to run, e.g. 'test', 'lint', 'test:unit' | |
| project_dir | Yes | Absolute path to the project root | |
| timeout_seconds | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly discloses that Vitest/Jest output is parsed into structured per-file results and falls back to raw output for non-test scripts, which shapes agent expectations. It omits side effects like dependency installation or exit-code behavior, but the core behavior is adequately revealed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core purpose and output behavior, with zero redundancy. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description's explanation of structured output and raw fallback provides sufficient context for invocation. It could elaborate on error handling or exit codes, but the essential information for calling the tool correctly is present, and sibling tools are clearly separated by their purposes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 80% (4/5 parameters have descriptions), so the schema already documents the parameters well. The description adds no additional meaning beyond the schema, meeting the baseline for high coverage without compensating for any gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb (runs) and resource (npm script) and explicitly differentiates from siblings like run_e2e_tests and typecheck by focusing on arbitrary npm scripts. The mention of parsing test output adds specificity, making it unmistakable which tool to use for unit tests.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies the tool is for running any npm script, particularly tests, and distinguishes it from e2e, typecheck, and build tools. However, it does not explicitly name alternatives or state when not to use this tool, leaving exclusions to inference rather than explicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Spins up the dev server (if configured in playwright.config), runs Playwright tests, and returns structured pass/fail results per test with error messages.
| Name | Required | Description | Default |
|---|---|---|---|
| headed | No | Run in headed mode (useful for debugging) | |
| project_dir | Yes | Absolute path to the project root | |
| start_server | No | Whether to let Playwright use the webServer config in playwright.config to start the dev server automatically | |
| test_pattern | No | Glob or file path to filter tests, e.g. 'tests/auth.spec.ts' | |
| timeout_seconds | No | Max seconds before the run is killed |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry behavioral disclosure. It transparently states that it starts a dev server if configured and returns structured results, which is the core behavior. However, it does not disclose potential side effects such as file modifications, server teardown, or environmental requirements like locally installed Playwright, leaving some transparency gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the main action and then details the conditional server startup and output format. There is no redundancy or unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a test runner with five parameters, the description covers the overall flow and return format sufficiently. The schema handles parameter details, and the description clarifies the conditional server startup. It lacks some environmental prerequisites, but overall it is adequate for an agent to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Because the input schema already provides descriptions for all five parameters, the baseline is 3. The description adds a little context by linking the dev server startup to the Playwright config, but it does not add new parameter-specific semantics beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool runs Playwright tests and returns structured pass/fail results, with a clear verb and resource. It also mentions spinning up a dev server, which helps distinguish it from siblings like typecheck or npm_run.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies its usage by identifying Playwright E2E testing as the core function. However, it does not explicitly name alternatives or specify when not to use it, leaving some room for interpretation. The context is clear enough that an agent would know to use it for running E2E tests.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Runs tsc --noEmit and returns structured errors with file, line, column, error code, and message.
| Name | Required | Description | Default |
|---|---|---|---|
| files | No | Specific files to check (overrides tsconfig includes) | |
| tsconfig | No | Path to tsconfig file relative to project_dir | tsconfig.json |
| project_dir | Yes | Absolute path to the project root (must contain tsconfig.json) | |
| timeout_seconds | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It discloses the read-only nature of tsc --noEmit implicitly and describes the return format, which is valuable given no output schema. However, it omits timeout behavior, exit-code/error-handling semantics, and the side-effect-free guarantee explicitly — gaps that annotations would otherwise cover.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence that packs the action, the exact command, and the output structure with zero filler. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 4 parameters, no annotations, and no output schema, so the description must compensate. It compensates well for the missing output schema by spelling out error fields, but it leaves gaps: timeout_seconds is undocumented in both schema and description, the files/tsconfig interplay is unaddressed, and failure behavior is unstated. Adequate but not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 75%, so the schema already documents files, tsconfig, and project_dir. The description adds the 'tsc --noEmit' context, which clarifies how tsconfig and project_dir are consumed, but it doesn't explain timeout_seconds (the one undocumented parameter) or the files-overrides-tsconfig behavior. Value added is marginal over the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb ('Runs'), a specific resource ('tsc --noEmit'), and states the output shape (structured errors with file, line, column, error code, and message). This clearly distinguishes it from siblings like run_e2e_tests, npm_run, and nextjs_build, which target different workflows.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no when-to-use or when-not-to-use guidance, and never mentions sibling tools. Context is only implied by the tool's name and the 'tsc --noEmit' detail; an agent receives no explicit direction on choosing it over the build/test siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0execute_sql_as_rolenextjs_buildnpm_runrun_e2e_teststypecheckScored across 5 tools
每个工具针对开发流程的不同方面: 端到端测试, SQL角色执行, 类型检查, 运行脚本, 构建。npm_run可以运行任意脚本, 包括测试, 但run_e2e_tests专门用于Playwright, 因此边界相对清晰。少数可能重叠, 但描述有帮助。
命名模式部分一致: 有些工具使用动词开头(run_e2e_tests, execute_sql_as_role), 而其他使用名词开头(npm_run, nextjs_build)或单词(typecheck)。虽然每个名称都具描述性, 但顺序和风格并不统一。
5个工具的数量非常适合开发工具服务器。每个工具都服务于核心开发任务, 没有冗余或过度精简, 范围恰当。
工具集覆盖了主要开发步骤: 测试, 类型检查, 构建, 运行脚本以及SQL安全验证。npm_run可以运行lint或单元测试等其他任务, 因此没有明显缺口, 但可能缺少如专门的格式或代码质量检查工具, 不过可通配。
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
A paid remote MCP for AI agent browser DevTools MCP, built to return verdicts, receipts, usage logs,
One PAT, any MCP agent: Vercel, GitHub, Cloudflare, Supabase, GCP — unified dev infra gateway.
OCR, transcription, file extraction, and image generation for AI agents via MCP.