check_port
Check if a specific port (1-65535) is currently in use on your local system to identify available ports for applications.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| port | Yes | Port number to check (1-65535) |
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 }