Local Utilities MCP Server

Implementation Reference

• src/mcp/port-checker.ts:20-78 (handler)

  Core implementation of port checking logic: executes platform-specific shell commands (netstat on Windows, lsof on Unix/macOS), parses output to list processes or connections using the port.

  export async function checkPort(port: number): Promise<PortCheckResult> { // Export and use specific type
    let command = '';
    if (process.platform === 'win32') {
      command = `netstat -ano | findstr :${port}`;
    } else if (process.platform === 'darwin') {
      command = `lsof -i :${port} -P -n -sTCP:LISTEN`;
    } else {
      command = `lsof -i :${port} -P -n | grep LISTEN`;
    }
  
    try {
      const { stdout } = await execPromise(command);
      
      if (!stdout.trim()) {
        return { message: `No process found using port ${port}` };
      }
      
      // Parse the output based on the platform
      let result: PortCheckResult;
      if (process.platform === 'win32') {
        const lines = stdout.trim().split('\n');
        result = {
          raw: lines,
          message: `Found ${lines.length} connection(s) on port ${port}`
        };
      } else {
        const lines = stdout.trim().split('\n');
        const processes = lines.map(line => {
          const parts = line.trim().split(/\s+/);
          // Basic parsing, might need adjustment based on actual lsof output variations
          return {
            command: parts[0] || 'N/A',
            pid: parts[1] || 'N/A',
            user: parts[2] || 'N/A',
            fd: parts[3] || 'N/A',
            type: parts[4] || 'N/A',
            device: parts[5] || 'N/A',
            size: parts[6] || 'N/A',
            node: parts[7] || 'N/A',
            name: parts.slice(8).join(' ') || 'N/A' // Handle names with spaces
          };
        });
        
        result = {
          processes,
          message: `Found ${processes.length} process(es) using port ${port}`
        };
      }
      return result;
    } catch (error: any) {
      // If the command fails (e.g., port not used), lsof/netstat often exit with error code.
      // Check the error output or code if necessary, but often it just means no process found.
      // For simplicity, we assume command failure implies no process found.
      console.debug(`Port check command for ${port} failed (likely no process found):`, error.message);
      return { message: `No process found using port ${port}` };
      // Re-throw only if it's an unexpected error (optional)
      // if (!error.message.includes('Command failed')) { throw error; }
    }
  }

• src/mcp/port-checker.ts:81-94 (schema)

  Zod schema for the 'port' input parameter, accepting number or string (parsed to int between 1 and 65535).

  const PortSchema = z.union([
    z.number().int().min(1).max(65535),
    z.string().transform((val, ctx) => {
      const parsed = parseInt(val, 10);
      if (isNaN(parsed) || parsed < 1 || parsed > 65535) {
        ctx.addIssue({ 
          code: z.ZodIssueCode.custom, 
          message: "Port must be a number between 1 and 65535" 
        });
        return z.NEVER; // Indicates validation failure
      }
      return parsed;
    })
  ]).describe("Port number to check (1-65535)");

• src/mcp/port-checker.ts:98-112 (registration)

  Registers the 'check_port' tool with the MCP server, specifying input schema and handler function.

    "check_port",
    { port: PortSchema },
    async (params) => {
      // Let SDK handle errors from checkPort if they are re-thrown
      // and Zod handle parameter validation errors.
      const result = await checkPort(params.port);
        
      return {
        content: [{
          type: "text",
          text: JSON.stringify(result, null, 2)
        }]
      };
    }
  );

• src/index.ts:23-23 (registration)

  Invokes the registration function to add the 'check_port' tool to the main MCP server instance.

  registerPortCheckerTool(server);

• src/mcp/port-checker.ts:9-13 (helper)

  TypeScript interface defining the structure of the port check result.

  interface PortCheckResult {
    message: string;
    processes?: Array<{ [key: string]: string }>;
    raw?: string[]; // For Windows
  }