start_server

Instructions

Implementation Reference

• src/services/ProcessService.ts:85-155 (handler)

  Main handler for start_server tool. Spawns a child process with the given command, optionally sets PORT env var, captures stdout/stderr output, and resolves after a startup delay or on process exit.

  async startServer(args: StartServerArgs): Promise<ToolResult> {
    const { command, port, name, cwd } = args;
    ValidationUtils.validateRequired({ command, name }, ['command', 'name']);
    
    return new Promise((resolve, reject) => {
      const workDir = cwd ? this.workspaceService.resolvePath(cwd) : this.workspaceService.getCurrentWorkspace();
      
      try {
        const proc = spawn(command, [], {
          shell: true,
          cwd: workDir,
          env: { ...process.env, PORT: port?.toString() },
          detached: false,
          stdio: ['pipe', 'pipe', 'pipe']
        });
        
        const processInfo = ProcessUtils.createProcessInfo(proc, command, port, workDir);
        this.activeProcesses.set(name, processInfo);
        
        let output = '';
        let hasResolved = false;
        
        // Set up timeout for process startup
        const startupTimeout = setTimeout(() => {
          if (!hasResolved) {
            hasResolved = true;
            resolve({
              content: [{
                type: 'text',
                text: `Server "${name}" started\nCommand: ${command}\nPort: ${port || 'default'}\nWorkspace: ${workDir}\nPID: ${proc.pid}\n\nInitial output:\n${output}`,
              }],
            });
          }
        }, this.startupDelay);
        
        proc.stdout?.on('data', (data) => {
          output += data.toString();
        });
        
        proc.stderr?.on('data', (data) => {
          output += data.toString();
        });
        
        proc.on('error', (error) => {
          clearTimeout(startupTimeout);
          this.activeProcesses.delete(name);
          if (!hasResolved) {
            hasResolved = true;
            reject(new Error(`Failed to start server "${name}": ${error.message}`));
          }
        });
        
        proc.on('exit', (code) => {
          clearTimeout(startupTimeout);
          this.activeProcesses.delete(name);
          if (!hasResolved) {
            hasResolved = true;
            resolve({
              content: [{
                type: 'text',
                text: `Server "${name}" exited with code ${code}\nOutput:\n${output}`,
              }],
            });
          }
        });
        
      } catch (error) {
        reject(new Error(`Failed to spawn process: ${error instanceof Error ? error.message : 'Unknown error'}`));
      }
    });
  }

• src/services/ProcessService.ts:15-20 (schema)

  TypeScript interface defining the input schema for start_server: command (string), port (optional number), name (string), cwd (optional string).

  export interface StartServerArgs {
    command: string;
    port?: number;
    name: string;
    cwd?: string;
  }

• src/index.ts:241-242 (registration)

  Registration/dispatch in the main server class. Routes the 'start_server' tool name to processService.startServer(args).

  case 'start_server':
    return await this.processService.startServer(args as StartServerArgs);

• src/toolDefinitions.ts:376-390 (schema)

  Tool definition registration with name 'start_server', description, and inputSchema declaring command (string, required), port (number, optional), name (string, required), cwd (string, optional).

  // Process Management
  {
    name: 'start_server',
    description: 'Start a development server',
    inputSchema: {
      type: 'object',
      properties: {
        command: { type: 'string', description: 'Server command' },
        port: { type: 'number', description: 'Port number' },
        name: { type: 'string', description: 'Process name for reference' },
        cwd: { type: 'string', description: 'Working directory' },
      },
      required: ['command', 'name'],
    },
  },