devctl-mcp

# devctl-mcp An MCP (Model Context Protocol) server that lets Claude manage long-running dev processes seamlessly — across Flutter, Next.js, Spring Boot, Vite, and any custom stack. **The problem it solves:** When Claude spawns `flutter run`, `next dev`, or `gradle bootRun` via bash, it immediately loses control. No hot reload, no log access, no restart. This server runs as a persistent daemon that owns all dev processes and exposes simple tools Claude can call. --- ## Features - **Flutter** — auto-detect FVM, target specific devices, hot reload & hot restart via Dart VM service - **Next.js** — auto-detect package manager (npm / pnpm / yarn / bun) from lockfiles - **Spring Boot** — auto-detect Maven or Gradle, use `mvnw`/`gradlew` wrappers when present - **Vite / React** — detect `vite.config.*` or `react-scripts` in `package.json` - **Generic** — run any custom command with full log capture - **Log streaming** — circular buffer (1000 lines), filter by string, timestamps on demand - **Full process lifecycle** — start, stop, restart with status tracking (starting → running → stopped/crashed) --- ## Installation ### Prerequisites - Node.js 20+ - Claude Code CLI ### Setup ```bash git clone git@github.com:adarsh-devappsys/devctl-mcp.git cd devctl-mcp npm install npm run build ``` ### Register globally with Claude Code ```bash claude mcp add -s user devctl -- node /absolute/path/to/devctl-mcp/dist/index.js ``` Verify it's connected: ```bash claude mcp list # devctl: node .../dist/index.js - ✓ Connected ``` > The server will be available in all your Claude Code sessions globally. ### Project-level (alternative) The repo ships with a `.mcp.json` — if you open this repo in Claude Code, it's auto-loaded without any extra setup. --- ## Available Tools ### Core — works for all frameworks | Tool | Description | |---|---| | `list_processes` | List all managed processes with status, uptime, PID | | `start_process` | Start a dev server — auto-detects the framework | | `stop_process` | Gracefully stop a process (SIGTERM → SIGKILL after 5s) | | `restart_process` | Stop + restart with original configuration | | `get_logs` | Get recent log output, with optional line count and filter | | `clear_logs` | Clear the log buffer for a process | | `send_input` | Send raw text to process stdin (escape hatch) | ### Flutter-specific | Tool | Description | |---|---| | `flutter_hot_reload` | Hot reload via Dart VM service, falls back to stdin `r` | | `flutter_hot_restart` | Hot restart via Dart VM service, falls back to stdin `R` | | `list_devices` | List connected Flutter devices and emulators | --- ## Usage Examples ### Flutter ``` List my connected Flutter devices ``` ``` Start my Flutter app at /Users/me/projects/myapp, name it "myapp", on my Pixel device ``` ``` Hot reload myapp ``` ``` Hot restart myapp ``` ``` Get the last 100 logs from myapp, filter by "error" ``` **With FVM (auto-detected):** If your project has `.fvm/flutter_sdk` or `fvm_config.json`, FVM is used automatically. You can also force it: ``` Start myapp at /path/to/project with use_fvm true, device id "32211JEHN06807" ``` ### Next.js ``` Start the Next.js project at /Users/me/projects/website, name it "web" ``` Package manager is auto-detected from lockfiles (`bun.lockb` → bun, `pnpm-lock.yaml` → pnpm, `yarn.lock` → yarn, else npm). Override with `package_manager: "pnpm"`. ### Spring Boot ``` Start /Users/me/projects/api, name it "api" ``` Maven vs Gradle auto-detected from `pom.xml` / `build.gradle`. Uses `./mvnw` or `./gradlew` wrappers when present. ### Any other stack ``` Start /Users/me/projects/backend, name it "django", command "python manage.py runserver" ``` ### Checking logs ``` Show me the logs for myapp ``` ``` Get last 50 lines from api, filter by "Exception" ``` ``` Get logs from web with timestamps ``` --- ## Framework Auto-Detection The adapter is chosen automatically based on what's in your project directory: | Framework | Detection | |---|---| | Flutter | `pubspec.yaml` exists | | Spring Boot | `pom.xml` or `build.gradle` / `build.gradle.kts` | | Next.js | `package.json` with `next` in dependencies | | Vite | `vite.config.*` file, or `vite`/`react-scripts` in `package.json` | | Generic | Fallback — requires `command` option | Priority: Flutter → Spring Boot → Next.js → Vite → Generic ### FVM Auto-Detection (Flutter) FVM is auto-enabled when **both** are true: 1. `fvm` binary is in `PATH` 2. Project has `.fvm/flutter_sdk`, `fvm_config.json`, or `.fvmrc` Override: pass `use_fvm: true` or `use_fvm: false` explicitly. ### Package Manager Auto-Detection (JS projects) Detected from lockfiles in priority order: 1. `bun.lockb` → bun 2. `pnpm-lock.yaml` → pnpm 3. `yarn.lock` → yarn 4. Fallback → npm --- ## How Flutter Hot Reload Works The server uses a two-tier system for maximum reliability: **Tier 1 — Dart VM service (preferred)** When `flutter run` starts, it prints a line like: ``` A Dart VM Service on Pixel 7a is available at: http://127.0.0.1:56789/TOKEN=/ ``` The server captures this URL and derives a WebSocket endpoint. Hot reload/restart is sent as JSON-RPC over WebSocket — the same protocol Flutter DevTools uses. Hot reload sequence: `getVM` → `reloadSources` → `callServiceExtension('ext.flutter.reassemble')` Hot restart sequence: `getVM` → `callService('hotRestart')` **Tier 2 — stdin fallback** If the VM service URL isn't available yet (app still starting up), the server sends `r` or `R` to the process stdin — Flutter's interactive keyboard commands. --- ## Development ```bash # Run without building (tsx watches for changes) npm run dev # Build npm run build # Type-check only npm run typecheck ``` --- ## Project Structure ``` src/ index.ts ← MCP server entry, stdio transport types.ts ← Shared TypeScript interfaces process-manager.ts ← Process registry, spawn, lifecycle, VM service URL parsing log-store.ts ← Circular buffer (1000 lines, stdout + stderr + timestamps) adapters/ flutter.ts ← Flutter + FVM detection nextjs.ts ← Next.js + package manager detection spring-boot.ts ← Maven/Gradle + wrapper detection vite.ts ← Vite/React-scripts detection generic.ts ← Fallback for custom commands registry.ts ← Ordered detection chain tools/ process-tools.ts ← 7 core MCP tools flutter-tools.ts ← Flutter hot reload/restart + list_devices ``` --- ## Important Notes - **Session persistence:** Managed processes live as long as the Claude Code session is open. If you close the session, running processes are stopped. This is a fundamental constraint of the stdio MCP transport. - **stdout is reserved:** The MCP protocol uses `process.stdout` for JSON-RPC messages. All internal server logs go to `stderr`. - **PATH inheritance:** The server inherits your shell `PATH`, so `fvm`, `flutter`, `mvn`, `gradle`, etc. must be on your PATH as they would be in a terminal.