https://github.com/bloopai/dev-manager-mcp
Make it easy to launch multiple dev servers in parallel
https://github.com/bloopai/dev-manager-mcp
Last synced: 18 days ago
JSON representation
Make it easy to launch multiple dev servers in parallel
- Host: GitHub
- URL: https://github.com/bloopai/dev-manager-mcp
- Owner: BloopAI
- Created: 2025-11-01T10:27:40.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2025-11-06T20:16:28.000Z (7 months ago)
- Last Synced: 2026-04-05T06:00:07.068Z (2 months ago)
- Language: Rust
- Size: 66.4 KB
- Stars: 129
- Watchers: 0
- Forks: 9
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# MCP Dev Server Manager
A daemon that accepts requests from MCP clients to start dev servers, allocating unique ports to avoid collisions and shutting down idle connections after 120s of inactivity.
## Example
- User starts daemon
- User's first MCP client (eg coding CLI) requests to run a dev server
- Dev server is started on PORT 3010
- User's second MCP client (eg coding CLI) requests to run a dev server
- Dev server is started on PORT 3011
## Features
- **Run multiple dev servers in parallel**: useful if you want to use automated testing tools eg [Playwright](https://github.com/microsoft/playwright-mcp) or [Google Dev Tools MCP](https://developer.chrome.com/blog/chrome-devtools-mcp)
- **Avoid port collisions**: when working with websites, it's often necessary to specify different ports if you want to run multiple dev servers
- **Automatic port allocation** starting at 3010 with reuse
- **Log capture** with 512KB ring buffers per server
- **Auto-cleanup** of idle sessions after 120 seconds (configurable via `--idle-timeout`)
## Installation & Usage
**Requirements:** Node.js >= 18
The recommended way to use dev-manager-mcp is via `npx`:
### Quick Start
Make sure the daemon is running in a terminal somewhere:
```bash
npx -y dev-manager-mcp
```
Add this MCP config to your coding CLI:
```bash
{
"mcpServers": {
"dev-manager": {
"command": "npx",
"args": ["dev-manager-mcp", "stdio"]
}
}
}
```
Finally, ask your coding CLI to start a dev server. You should see it use the MCP server.
## MCP Tools
### `start`
Start a development server. Auto-generates a unique 4-character session key.
**Parameters:**
- `command` (string): Shell command to execute (e.g., "npm run dev", "python -m http.server 8080")
- `cwd` (optional string): Working directory for the command. When using STDIO transport, defaults to client's working directory.
**Returns:**
```json
{
"status": "started",
"port": 3010,
"session_key": "A3X9"
}
```
### `stop`
Stop a running development server session.
**Parameters:**
- `session_key` (string): Session identifier
**Returns:**
```json
{
"status": "stopped",
"session_key": "A3X9"
}
```
### `status`
Get status of one or all development server sessions.
**Parameters:**
- `session_key` (optional string): Specific session to query, or omit for all sessions
**Returns:**
```json
{
"sessions": [
{
"session_key": "B7K2",
"port": 3010,
"running": true
}
]
}
```
### `tail`
Get stdout/stderr logs for a development server session.
**Parameters:**
- `session_key` (string): Session identifier (e.g., "A3X9")
**Returns:**
```json
{
"session_key": "A3X9",
"stdout": "Server started on port 3010...",
"stderr": ""
}
```
## Architecture
### Modules
- **port_allocator.rs** - Sequential port allocation from 3010 with free list
- **log_buffer.rs** - Bounded 512KB ring buffer with Clone support
- **server_entry.rs** - Process wrapper with async log capture
- **manager.rs** - Shared state manager with auto-cleanup sweeper
- **service.rs** - MCP service with tool definitions
- **main.rs** - HTTP/SSE daemon server
### State Management
- Single `Arc` shared across all client connections
- Each connection gets a fresh `DevManagerService` instance
- Mutex-protected HashMap for session storage
- Background sweeper runs every 5 seconds to clean up idle sessions (>120s by default)
### Session Keys
- Auto-generated 4-character uppercase alphanumeric codes (e.g., "A3X9", "K7M2")
- Guaranteed unique across active sessions
- 1,679,616 possible combinations (36^4)
### Port Allocation
- Starts at 3010 and increments sequentially
- Maintains free list for reused ports
- Probes availability with TcpListener before assignment
### Log Capture
- Each server spawns two async tasks for stdout/stderr
- Logs stored in bounded VecDeque with byte tracking
- Oldest entries evicted when 512KB limit reached
- Non-blocking reads with line buffering
## Testing Multi-Client Behavior
1. Start daemon: `npx -y dev-manager-mcp daemon`
2. Connect Client A and start a server session
3. Connect Client B and query status - should see Client A's session
4. Client B can stop Client A's session
5. All clients share the same session state
## Building from Source
If you prefer to build from source or need offline/advanced usage:
```bash
cargo build --release
```
The binary will be at `target/release/dev-manager-mcp`.
To use the built binary, replace `npx dev-manager-mcp` with `./target/release/dev-manager-mcp` in all examples above.
## License
MIT