dev-tools-mcp

MCP-сервер (Model Context Protocol) на stdio, который даёт Claude Code — или любому MCP-клиенту — пять структурированных инструментов разработки:

Предварительные требования

• Node.js ≥ 18

• Установленный Claude Code

• Для инструмента RLS: psql в PATH и запущенный экземпляр Supabase/Postgres

Быстрый старт

# 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 напрямую

Добавьте это в ключ mcpServers в ~/.claude.json (глобально) или в .claude.json в корне проекта:

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

Затем перезапустите Claude Code.

Проверка работы

Внутри Claude Code выполните /mcp — вы должны увидеть dev-tools: connected со списком из 5 инструментов.

Детали инструментов

1. run_e2e_tests — запуск Playwright E2E

Запускает Playwright с JSON-репортером и разбирает результаты в структурированный вывод.

Входные параметры:

• project_dir (обязательно) — абсолютный путь к вашему проекту

• test_pattern — glob или путь к файлу для фильтрации, например "tests/auth.spec.ts"

• headed — запуск в режиме с окном (по умолчанию: false)

• start_server — использовать конфигурацию webServer из Playwright (по умолчанию: true)

• timeout_seconds — завершить процесс через это количество секунд (по умолчанию: 120)

Что вы получите:

{
  "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..." }
  ]
}

Совет: Убедитесь, что в вашем playwright.config.ts есть секция webServer, чтобы Playwright автоматически запускал ваш dev-сервер:

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

2. execute_sql_as_role — тестирование Supabase RLS

Выполняет SQL от имени конкретной роли Postgres с JWT-claims, затем откатывает изменения. Никогда не изменяет данные.

Входные параметры:

• connection_string (обязательно) — например "postgresql://postgres:postgres@localhost:54322/postgres"

• sql (обязательно) — запрос для выполнения

• role — роль Postgres (по умолчанию: "authenticated")

• user_id — UUID, устанавливаемый как auth.uid()

• claims — дополнительные JWT-claims, например { "app_role": "parent" }

Пример запроса для Claude Code:

"Выполни SELECT * FROM children от имени аутентифицированного родителя с id abc-123 и подтверди, что он видит только своих детей."

Что вы получите:

{
  "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 — проверка TypeScript

Запускает tsc --noEmit и разбирает вывод в структурированные ошибки.

Входные параметры:

• project_dir (обязательно)

• tsconfig — относительный путь к tsconfig (по умолчанию: "tsconfig.json")

• files — проверить только указанные файлы

Что вы получите:

{
  "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 — структурированный запуск npm-скриптов

Запускает любой npm-скрипт с CI=true и FORCE_COLOR=0, затем разбирает вывод Vitest/Jest.

Входные параметры:

• project_dir (обязательно)

• script (обязательно) — например "test", "test:unit", "lint"

• args — дополнительные аргументы, передаваемые после --

• env — дополнительные переменные окружения

Что вы получите:

{
  "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 — проверка сборки Next.js

Запускает next build в production-режиме и разбирает ошибки и вывод страниц.

Входные параметры:

• project_dir (обязательно)

• env — дополнительные переменные окружения для сборки

• timeout_seconds — (по умолчанию: 180)

Что вы получите:

{
  "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 inspect

Тесты

Парсеры вывода — самая сложная и подверженная регрессиям часть кодовой базы — они превращают свободный вывод Vitest/Jest/tsc/next build в структурированный JSON. Эти чистые функции покрыты юнит-тестами на Vitest в test/; запустите их с помощью npm test. CI (см. .github/workflows/ci.yml) выполняет npm ci, TypeScript-сборку и тестовый набор на Node 20 и 22 для каждого пуша и pull request.

Идеи для кастомизации

• Добавьте инструмент lint, который разбирает JSON-вывод ESLint

• Добавьте инструмент prisma_migrate для структурированного статуса миграций

• Добавьте инструмент docker_compose для управления тестовыми контейнерами

• Подключите RLS-инструмент к Supabase CLI (supabase db test) вместо сырого psql

Лицензия

MIT © 2026 Brian Cox