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

git clone git@github.com:adarsh-devappsys/devctl-mcp.git
cd devctl-mcp
npm install
npm run build

Register globally with Claude Code

claude mcp add -s user devctl -- node /absolute/path/to/devctl-mcp/dist/index.js

Verify it's connected:

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

# 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.