Local Utilities MCP Server

Implementation Reference

• src/mcp/port-checker.ts:100-111 (handler)

  The inline handler function registered for the 'check_port' tool. It invokes checkPort with the input port and formats the result as a JSON text response.
  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/mcp/port-checker.ts:81-94 (schema)

  Zod schema definition for the 'port' input parameter, supporting both number and string inputs validated to 1-65535 range.
  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:96-113 (registration)

  The registration function that adds the 'check_port' tool to the MCP server using server.tool, including schema and handler.
  export function registerPortCheckerTool(server: McpServer): void { server.tool( "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/mcp/port-checker.ts:20-78 (helper)

  Core helper function that executes platform-specific shell commands (netstat/lsof) to check processes using the given port and parses the output into a structured result.
  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; } } }