simplify server discovery (#96)

Author: gaojude

CLAUDE.md

@@ -62,14 +62,14 @@ All tools, prompts, and resources are explicitly imported and registered in `src
 - Tools are manually imported and registered in `src/index.ts`
 - `nextjs_docs`: Search Next.js documentation and knowledge base
 - `browser_eval`: Playwright browser automation (via `playwright-mcp` server)
-- `nextjs_runtime`: Connect to Next.js dev server MCP endpoint for runtime diagnostics
+- `nextjs_index`: Discover all running Next.js dev servers and list their available MCP tools
+- `nextjs_call`: Execute specific MCP tools on a running Next.js dev server
 - `upgrade_nextjs_16`: Automated Next.js 16 upgrade guidance
 - `enable_cache_components`: Complete Cache Components setup with error detection
 
 **MCP Client Library** (`src/_internal/mcp-client.ts`):
 - Connects to external MCP servers via stdio transport
 - Used by `browser_eval` to communicate with `playwright-mcp`
-- Used by `nextjs_runtime` to communicate with Next.js dev server MCP endpoint
 
 **Runtime Managers** (`src/_internal/`):
 - `browser-eval-manager.ts`: Manages Playwright MCP server lifecycle
@@ -127,7 +127,7 @@ This server can:
 - Command: `npx @playwright/mcp@latest` (with optional `--browser` and `--headless` flags)
 - Used for browser automation and testing
 
-**Next.js Runtime MCP** (`nextjs_runtime` tool):
+**Next.js Runtime MCP** (`nextjs_index` and `nextjs_call` tools):
 - Built into Next.js 16+ (enabled by default)
 - Endpoint: `http://localhost:<port>/_next/mcp`
 - Provides runtime diagnostics, errors, routes, and build status

README.md

@@ -182,7 +182,7 @@ Next Devtools, show me the structure of my routes
 Next Devtools, what's in the development server logs?
 ```
 
-Your coding agent will use the `nextjs_runtime` tool to query your running application's actual state.
+Your coding agent will use the `nextjs_index` and `nextjs_call` tools to query your running application's actual state.
 
 ### For All Next.js Projects
 
@@ -355,7 +355,7 @@ Automate and test web applications using Playwright browser automation.
 - Detecting runtime errors, hydration issues, and client-side problems
 - Capturing browser console errors and warnings
 
-**Important:** For Next.js projects, prioritize using the `nextjs_runtime` tool instead of browser console log forwarding. Only use browser_eval's `console_messages` action as a fallback when `nextjs_runtime` tools are not available.
+**Important:** For Next.js projects, prioritize using the `nextjs_index` and `nextjs_call` tools instead of browser console log forwarding. Only use browser_eval's `console_messages` action as a fallback when these tools are not available.
 
 **Available actions:**
 - `start` - Start browser automation (automatically installs if needed)
@@ -383,21 +383,17 @@ Automate and test web applications using Playwright browser automation.
 </details>
 
 <details>
-<summary><code>nextjs_runtime</code></summary>
+<summary><code>nextjs_index</code></summary>
 
-Connect to your running Next.js dev server's built-in MCP endpoint to access live application state, runtime diagnostics, and internal information.
+Discover all running Next.js dev servers and list their available MCP tools.
 
 **What this tool does:**
 
-This tool acts as a bridge between your coding agent and Next.js 16's built-in MCP endpoint at `/_next/mcp`. It provides three key actions:
+Automatically discovers all running Next.js 16+ dev servers on your machine and lists the runtime diagnostic tools available from each server's built-in MCP endpoint at `/_next/mcp`.
 
-1. **`discover_servers`**: Find all running Next.js dev servers on your machine
-2. **`list_tools`**: See what runtime diagnostic tools are available from Next.js
-3. **`call_tool`**: Execute a specific Next.js runtime tool (e.g., get errors, query routes, fetch logs)
+**No parameters required** - Just call the tool and it will scan for servers.
 
-**Available Next.js Runtime Tools** (accessed via `call_tool`):
-
-Once connected to a Next.js 16+ dev server, you can access these built-in tools:
+**Available Next.js Runtime Tools** (varies by Next.js version):
 - `get_errors` - Get current build, runtime, and type errors
 - `get_logs` - Get path to development log file (browser console + server output)
 - `get_page_metadata` - Query application routes, pages, and component metadata
@@ -408,38 +404,52 @@ Once connected to a Next.js 16+ dev server, you can access these built-in tools:
 - Next.js 16+ (MCP enabled by default)
 - Running dev server (`npm run dev`)
 
+**Output:**
+- JSON with list of discovered servers, each containing:
+  - Port, PID, URL
+  - Available tools with descriptions and input schemas
+
+**Example prompts:**
+- "Next Devtools, what servers are running?"
+- "Next Devtools, show me available diagnostic tools"
+
+</details>
+
+<details>
+<summary><code>nextjs_call</code></summary>
+
+Execute a specific MCP tool on a running Next.js dev server.
+
+**What this tool does:**
+
+Calls a specific runtime diagnostic tool on a Next.js 16+ dev server's built-in MCP endpoint at `/_next/mcp`.
+
+**Input Parameters:**
+- `port` (required) - Dev server port (use `nextjs_index` first to discover)
+- `toolName` (required) - Name of the Next.js tool to invoke
+- `args` (optional) - Arguments object for the tool (only if required by that tool)
+
+**Requirements:**
+- Next.js 16+ (MCP enabled by default)
+- Running dev server (`npm run dev`)
+- Use `nextjs_index` first to discover available servers and tools
+
 **Typical workflow:**
 
 ```javascript
-// Step 1: Discover running servers (optional - auto-discovery works in most cases)
-{
-  "action": "discover_servers"
-}
+// Step 1: Discover servers and tools
+// (call nextjs_index first)
 
-// Step 2: List available runtime tools
+// Step 2: Call a specific tool
 {
-  "action": "list_tools",
-  "port": 3000  // optional if only one server is running
-}
-
-// Step 3: Call a specific tool
-{
-  "action": "call_tool",
   "port": 3000,
   "toolName": "get_errors"
   // args is optional and only needed if the tool requires parameters
 }
 ```
 
-**Input Parameters:**
-- `action` (required) - `discover_servers`, `list_tools`, or `call_tool`
-- `port` (optional) - Dev server port (auto-discovers if not provided)
-- `toolName` (required for `call_tool`) - Name of the Next.js tool to invoke
-- `args` (optional) - Arguments object for the tool (only if required by that tool)
-- `includeUnverified` (optional) - For `discover_servers`: include servers even if MCP verification fails
-
 **Output:**
-- JSON with discovered servers, available tools list, or tool execution results
+- JSON with tool execution results
 
 **Example prompts that use this tool:**
 - "Next Devtools, what errors are in my Next.js app?"
@@ -515,7 +525,7 @@ With other agents or programmatically:
 
 `next-devtools-mcp` collects anonymous usage telemetry to help improve the tool. The following data is collected:
 
-- **Tool usage**: Which MCP tools are invoked (e.g., `nextjs_runtime`, `browser_eval`, `upgrade_nextjs_16`)
+- **Tool usage**: Which MCP tools are invoked (e.g., `nextjs_index`, `nextjs_call`, `browser_eval`, `upgrade_nextjs_16`)
 - **Error events**: Anonymous error messages when tools fail
 - **Session metadata**: Session ID, timestamps, and basic environment info (OS, Node.js version)
 
@@ -616,7 +626,7 @@ Coding Agent
 
 2. **For all Next.js projects**: Provides development automation tools (upgrades, Cache Components setup), documentation access, and browser testing capabilities that work independently of the runtime connection.
 
-3. **Auto-discovery**: The `nextjs_runtime` tool scans common ports (3000, 3001, etc.) to find running Next.js servers, so you don't need to manually specify ports in most cases.
+3. **Simple workflow**: Call `nextjs_index` to see all servers and available tools, then call `nextjs_call` with the specific port and tool name you want to execute.
 
 
 ## License

src/index.ts

@@ -25,7 +25,8 @@ import * as browserEval from "./tools/browser-eval.js"
 import * as enableCacheComponents from "./tools/enable-cache-components.js"
 import * as init from "./tools/init.js"
 import * as nextjsDocs from "./tools/nextjs-docs.js"
-import * as nextjsRuntime from "./tools/nextjs-runtime.js"
+import * as nextjsIndex from "./tools/nextjs_index.js"
+import * as nextjsCall from "./tools/nextjs_call.js"
 import * as upgradeNextjs16 from "./tools/upgrade-nextjs-16.js"
 
 import * as upgradeNextjs16Prompt from "./prompts/upgrade-nextjs-16.js"
@@ -48,14 +49,15 @@ import * as nextjs16BetaToStable from "./resources/(nextjs16)/migration/beta-to-
 import * as nextjs16Examples from "./resources/(nextjs16)/migration/examples.js"
 import * as nextjsDocsLlmsIndex from "./resources/(nextjs-docs)/llms-index.js"
 
-const tools = [browserEval, enableCacheComponents, init, nextjsDocs, nextjsRuntime, upgradeNextjs16]
+const tools = [browserEval, enableCacheComponents, init, nextjsDocs, nextjsIndex, nextjsCall, upgradeNextjs16]
 
 const toolNameToTelemetryName: Record<string, McpToolName> = {
   browser_eval: "mcp/browser_eval",
   enable_cache_components: "mcp/enable_cache_components",
   init: "mcp/init",
   nextjs_docs: "mcp/nextjs_docs",
-  nextjs_runtime: "mcp/nextjs_runtime",
+  nextjs_index: "mcp/nextjs_index",
+  nextjs_call: "mcp/nextjs_call",
   upgrade_nextjs_16: "mcp/upgrade_nextjs_16",
 }
 

src/telemetry/mcp-telemetry-tracker.ts

@@ -3,7 +3,8 @@ export type McpToolName =
   | "mcp/enable_cache_components"
   | "mcp/init"
   | "mcp/nextjs_docs"
-  | "mcp/nextjs_runtime"
+  | "mcp/nextjs_index"
+  | "mcp/nextjs_call"
   | "mcp/upgrade_nextjs_16"
 
 export interface McpToolUsage {

src/tools/browser-eval.ts

@@ -93,10 +93,10 @@ in a real browser instead of curl or simple HTTP requests. This is because:
 - Captures browser console errors and warnings via console_messages action
 
 IMPORTANT FOR NEXT.JS PROJECTS:
-If working with a Next.js application, PRIORITIZE using the 'nextjs_runtime' tool instead of browser console log forwarding.
+If working with a Next.js application, PRIORITIZE using the 'nextjs_index' and 'nextjs_call' tools instead of browser console log forwarding.
 Next.js has built-in MCP integration that provides superior error reporting, build diagnostics, and runtime information
-directly from the Next.js dev server. Only use browser_eval's console_messages action as a fallback when nextjs_runtime
-tools are not available or when you specifically need to test client-side browser behavior that Next.js runtime cannot capture.
+directly from the Next.js dev server. Only use browser_eval's console_messages action as a fallback when these Next.js tools
+are not available or when you specifically need to test client-side browser behavior that Next.js runtime cannot capture.
 
 Available actions:
 - start: Start browser automation (automatically installs if needed). Verbose logging is always enabled.
@@ -106,7 +106,7 @@ Available actions:
 - fill_form: Fill multiple form fields at once
 - evaluate: Execute JavaScript in browser context
 - screenshot: Take a screenshot of the page
-- console_messages: Get browser console messages (for Next.js, prefer nextjs_runtime tool instead)
+- console_messages: Get browser console messages (for Next.js, prefer nextjs_index/nextjs_call tools instead)
 - close: Close the browser
 - drag: Perform drag and drop
 - upload_file: Upload files

src/tools/init.ts

@@ -20,7 +20,7 @@ Key Points:
 - Fetches latest Next.js LLM documentation from nextjs.org
 - Establishes MANDATORY requirement to use nextjs_docs for ALL Next.js concepts
 - Instructs AI to forget any prior Next.js knowledge and always query docs
-- Documents all available MCP tools (nextjs_docs, nextjs_runtime, browser_eval, upgrade_nextjs_16, enable_cache_components)
+- Documents all available MCP tools (nextjs_docs, nextjs_index, nextjs_call, browser_eval, upgrade_nextjs_16, enable_cache_components)
 
 Use this tool at the beginning of a Next.js session to:
 - Reset AI's Next.js knowledge baseline
@@ -165,12 +165,19 @@ You MUST still use the \`nextjs_docs\` tool with GET to retrieve the full detail
 - **REQUIRED** for ALL Next.js-related questions
 - **OPTIMIZATION:** For batch operations, fetch the \`nextjs-docs://llms-index\` resource to look up multiple paths
 
-### 2. **nextjs_runtime** - Live Next.js Dev Server Integration
-- Get real-time errors and logs from running dev server
-- Inspect routes, components, and runtime diagnostics
-- Requires Next.js 16+ (or experimental.mcpServer in older versions)
+### 2. **nextjs_index** - Discover Running Next.js Servers
+- Lists all running Next.js dev servers with MCP enabled
+- Shows available runtime tools for each server
+- Takes no parameters - automatically discovers servers
+- Requires Next.js 16+
 
-### 3. **browser_eval** - Browser Automation
+### 3. **nextjs_call** - Execute Next.js Runtime Tools
+- Calls specific MCP tools on a running Next.js dev server
+- Get real-time errors, logs, routes, and diagnostics
+- Requires port and toolName (use nextjs_index first to discover)
+- Requires Next.js 16+
+
+### 4. **browser_eval** - Browser Automation
 - Test Next.js pages with Playwright
 - Verify functionality and capture runtime errors
 - Use after implementing features to verify behavior
@@ -191,7 +198,7 @@ You MUST still use the \`nextjs_docs\` tool with GET to retrieve the full detail
 2. **ALWAYS** use \`nextjs_docs\` for ANY Next.js concept (even if you think you know it)
    - Start with search action for most queries: \`{ action: "search", query: "..." }\`
    - For batch operations or multiple lookups, fetch \`nextjs-docs://llms-index\` resource to find paths directly
-3. Use \`nextjs_runtime\` for debugging running applications
+3. Use \`nextjs_index\` to discover servers, then \`nextjs_call\` to debug running applications
 4. Use \`browser_eval\` to verify implementations
 5. Use specialized tools (\`upgrade_nextjs_16\`, \`enable_cache_components\`) as needed