From bb7562b47cfbcd4bfefff9ce41457e534849d677 Mon Sep 17 00:00:00 2001
From: Louis Knight-Webb <louis@bloop.ai>
Date: Sat, 1 Nov 2025 23:22:55 +0000
Subject: [PATCH] readme

---
 README.md         | 88 +++++++++--------------------------------------
 npx-cli/README.md | 51 ++++++---------------------
 2 files changed, 28 insertions(+), 111 deletions(-)

diff --git a/README.md b/README.md
index acb69db..ede2372 100644
--- a/README.md
+++ b/README.md
@@ -1,15 +1,22 @@
 # MCP Dev Server Manager
 
-A daemon process that runs continuously and accepts multiple concurrent MCP client connections, sharing dev server session state across all clients.
+A daemon that accepts requests from MCP clients to start dev servers, allocating unique ports to avoid collisions and shutting down idle connections after 60s 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
 
-- **Multi-client daemon** with shared global state
-- **STDIO and SSE transport** support
+- **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 60 seconds
-- **Process management** with stdout/stderr capture
 
 ## Installation & Usage
 
@@ -19,33 +26,15 @@ The recommended way to use dev-manager-mcp is via `npx`:
 
 ### Quick Start
 
+Make sure the daemon is running in a terminal somewhere:
+
 ```bash
-# STDIO mode (recommended for MCP clients)
-npx -y dev-manager-mcp stdio
-
-# Start daemon in foreground
-npx -y dev-manager-mcp daemon
-
-# Start daemon in background
-npx -y dev-manager-mcp daemon &
-
-# Custom port
-npx -y dev-manager-mcp daemon --port 3010
-# or via environment variable:
-PORT=3010 npx -y dev-manager-mcp daemon
+npx -y dev-manager-mcp
 ```
 
-**Note:** Use `-y` flag to skip npx prompts. First run downloads the binary (~5MB).
+Add this MCP config to your coding CLI:
 
-The daemon listens on `http://127.0.0.1:3009` by default.
-
-### Client Configuration
-
-#### STDIO Transport (Recommended)
-
-For Claude Desktop (`claude_desktop_config.json`):
-
-```json
+```bash
 {
   "mcpServers": {
     "dev-manager": {
@@ -56,50 +45,7 @@ For Claude Desktop (`claude_desktop_config.json`):
 }
 ```
 
-The STDIO proxy connects to the daemon at `http://127.0.0.1:3009/sse` by default. To use a different URL:
-
-```json
-{
-  "mcpServers": {
-    "dev-manager": {
-      "command": "npx",
-      "args": ["dev-manager-mcp", "stdio", "--daemon-url", "http://127.0.0.1:3010/sse"]
-    }
-  }
-}
-```
-
-Or use the environment variable:
-
-```json
-{
-  "mcpServers": {
-    "dev-manager": {
-      "command": "npx",
-      "args": ["dev-manager-mcp", "stdio"],
-      "env": {
-        "MCP_DAEMON_URL": "http://127.0.0.1:3009/sse"
-      }
-    }
-  }
-}
-```
-
-#### SSE Transport (Legacy)
-
-For Claude Desktop (`claude_desktop_config.json`):
-
-```json
-{
-  "mcpServers": {
-    "dev-manager": {
-      "url": "http://127.0.0.1:3009/sse"
-    }
-  }
-}
-```
-
-Multiple clients can use the same configuration and will share session state.
+Finally, ask your coding CLI to start a dev server. You should see it use the MCP server.
 
 ## MCP Tools
 
diff --git a/npx-cli/README.md b/npx-cli/README.md
index c29099f..d36fb6e 100644
--- a/npx-cli/README.md
+++ b/npx-cli/README.md
@@ -2,25 +2,23 @@
 
 MCP Dev Server Manager — manage development servers via npx.
 
-## Requirements
+## Installation & Usage
 
-Node.js >= 18
+**Requirements:** Node.js >= 18
 
-## Quick Start
+The recommended way to use dev-manager-mcp is via `npx`:
+
+### Quick Start
+
+Make sure the daemon is running in a terminal somewhere:
 
 ```bash
-# STDIO mode (recommended for MCP clients like Claude Desktop)
-npx -y dev-manager-mcp stdio
-
-# Start daemon (optional)
-npx -y dev-manager-mcp daemon
+npx -y dev-manager-mcp
 ```
 
-## Claude Desktop Configuration
+Add this MCP config to your coding CLI:
 
-Add to your `claude_desktop_config.json`:
-
-```json
+```bash
 {
   "mcpServers": {
     "dev-manager": {
@@ -31,34 +29,7 @@ Add to your `claude_desktop_config.json`:
 }
 ```
 
-### Custom Daemon URL
-
-```json
-{
-  "mcpServers": {
-    "dev-manager": {
-      "command": "npx",
-      "args": ["dev-manager-mcp", "stdio", "--daemon-url", "http://127.0.0.1:3010/sse"]
-    }
-  }
-}
-```
-
-Or via environment variable:
-
-```json
-{
-  "mcpServers": {
-    "dev-manager": {
-      "command": "npx",
-      "args": ["dev-manager-mcp", "stdio"],
-      "env": {
-        "MCP_DAEMON_URL": "http://127.0.0.1:3009/sse"
-      }
-    }
-  }
-}
-```
+Finally, ask your coding CLI to start a dev server. You should see it use the MCP server.
 
 ## Options