list_dev_servers

Instructions

Implementation Reference

• src/dev-servers.ts:19-42 (handler)

  The core handler function that implements the 'list_dev_servers' tool logic. It calls scanListeningPorts(), filters processes via isDevProcess(), detects frameworks, and returns a sorted array of DevServer objects with port, pid, framework, project name, cwd, uptime, memory, and CPU info.

  export async function listDevServers(): Promise<DevServer[]> {
    const listeners = await scanListeningPorts();
    const out: DevServer[] = [];
    for (const l of listeners) {
      const info = await getProcessInfo(l.pid);
      if (!info) continue;
      if (!isDevProcess(l.process, info.cmdline)) continue;
      const fw = await detectFramework(info.cmdline, info.cwd);
      out.push({
        port: l.port,
        pid: l.pid,
        process: l.process,
        cmdline: info.cmdline,
        cwd: info.cwd,
        project_name: fw.project_name,
        framework: fw.framework,
        uptime_seconds: info.uptime_seconds,
        memory_mb: info.memory_mb,
        cpu_pct: info.cpu_pct,
        user: l.user,
      });
    }
    return out.sort((a, b) => a.port - b.port);
  }

• src/index.ts:16-21 (registration)

  Tool registration in the TOOLS array. Defines 'list_dev_servers' with its name, description, and empty inputSchema (no required params).

  const TOOLS = [
    {
      name: "list_dev_servers",
      description: "List all local dev servers (next, vite, rails, django, etc) listening on TCP ports. Returns port, pid, framework, project name, cwd, uptime, memory, cpu.",
      inputSchema: { type: "object", properties: {}, additionalProperties: false },
    },

• src/index.ts:86-89 (handler)

  MCP CallToolRequestSchema handler that dispatches 'list_dev_servers' to the listDevServers() function and returns the result wrapped in a text content block.

  case "list_dev_servers": {
    const data = await listDevServers();
    return ok({ count: data.length, servers: data });
  }

• src/types.ts:1-13 (schema)

  The DevServer interface type definition that defines the shape of the output returned by list_dev_servers: port, pid, process, cmdline, cwd, project_name, framework, uptime_seconds, memory_mb, cpu_pct, user.

  export interface DevServer {
    port: number;
    pid: number;
    process: string;
    cmdline: string;
    cwd: string | null;
    project_name: string | null;
    framework: string | null;
    uptime_seconds: number;
    memory_mb: number;
    cpu_pct: number;
    user: string;
  }

• src/dev-servers.ts:104-109 (helper)

  Helper function isDevProcess() called within listDevServers to filter which listening TCP ports correspond to actual dev servers (node, python, ruby, etc.) based on a whitelist and regex fallback.

  function isDevProcess(processName: string, cmdline: string): boolean {
    const base = processName.split("/").pop() ?? processName;
    if (DEV_PROCESS_WHITELIST.has(base)) return true;
    // fallback: cmdline contains a dev runner
    return /\b(next|vite|nuxt|remix|astro|webpack|rails|django|flask|uvicorn|gunicorn|deno|bun)\b/.test(cmdline);
  }