MCP Flux Studio

Instructions

Implementation Reference

• src/index.ts:292-313 (handler)

  MCP tool handler for 'generate': validates args, builds CLI command, executes Python fluxcli.py generate, returns output.

  case 'generate': {
      const args = request.params.arguments as GenerateArgs;
      // Validate required fields
      const prompt = this.validateRequiredString(args.prompt, 'prompt');
  
      // Validate optional numeric fields
      const width = this.validateNumber(args.width, 'width', 256, 2048);
      const height = this.validateNumber(args.height, 'height', 256, 2048);
  
      const cmdArgs = ['generate'];
      cmdArgs.push('--prompt', prompt);
      if (args.model) cmdArgs.push('--model', args.model);
      if (args.aspect_ratio) cmdArgs.push('--aspect-ratio', args.aspect_ratio);
      if (width) cmdArgs.push('--width', width.toString());
      if (height) cmdArgs.push('--height', height.toString());
      if (args.output) cmdArgs.push('--output', args.output);
  
      const output = await this.runPythonCommand(cmdArgs);
      return {
          content: [{ type: 'text', text: output }],
      };
  }

• src/index.ts:131-168 (registration)

  Registration of the 'generate' tool in ListTools response, including name, description, and input schema.

  {
      name: 'generate',
      description: 'Generate an image from a text prompt',
      inputSchema: {
          type: 'object',
          properties: {
              prompt: {
                  type: 'string',
                  description: 'Text prompt for image generation',
              },
              model: {
                  type: 'string',
                  description: 'Model to use for generation',
                  enum: ['flux.1.1-pro', 'flux.1-pro', 'flux.1-dev', 'flux.1.1-ultra'],
                  default: 'flux.1.1-pro',
              },
              aspect_ratio: {
                  type: 'string',
                  description: 'Aspect ratio of the output image',
                  enum: ['1:1', '4:3', '3:4', '16:9', '9:16'],
              },
              width: {
                  type: 'number',
                  description: 'Image width (ignored if aspect-ratio is set)',
              },
              height: {
                  type: 'number',
                  description: 'Image height (ignored if aspect-ratio is set)',
              },
              output: {
                  type: 'string',
                  description: 'Output filename',
                  default: 'generated.jpg',
              },
          },
          required: ['prompt'],
      },
  },

• src/types.ts:37-44 (schema)

  TypeScript interface defining the input arguments for the 'generate' tool.

  export interface GenerateArgs {
    prompt: string;
    model?: FluxModel;
    aspect_ratio?: AspectRatio;
    width?: number;
    height?: number;
    output?: string;
  }

• src/index.ts:45-85 (helper)

  Helper method to execute the Python CLI script (fluxcli.py) with given arguments, capturing output or error.

  private async runPythonCommand(args: string[]): Promise<string> {
      return new Promise((resolve, reject) => {
          // Validate arguments
          if (!args || args.length === 0) {
              reject(new Error('No command arguments provided'));
              return;
          }
  
          // Use python from virtual environment if available
          const pythonPath = process.env.VIRTUAL_ENV ?
              `${process.env.VIRTUAL_ENV}/bin/python` : 'python3';
  
          const childProcess = spawn(pythonPath, ['fluxcli.py', ...args], {
              cwd: this.fluxPath,
              env: process.env, // Pass through all environment variables
          });
  
          let output = '';
          let errorOutput = '';
  
          childProcess.stdout?.on('data', (data) => {
              output += data.toString();
          });
  
          childProcess.stderr?.on('data', (data) => {
              errorOutput += data.toString();
          });
  
          childProcess.on('error', (error) => {
              reject(new Error(`Failed to spawn Python process: ${error.message}`));
          });
  
          childProcess.on('close', (code) => {
              if (code === 0) {
                  resolve(output);
              } else {
                  reject(new Error(`Flux command failed (exit code ${code}): ${errorOutput}`));
              }
          });
      });
  }

• src/cli/fluxcli.py:76-126 (helper)

  Core image generation logic in Python CLI: constructs payload for FLUX API endpoint based on model, submits request, polls for result URL.

  def generate_image(self, prompt: str, model: str = "flux.1.1-pro", width: int = None, height: int = None, aspect_ratio: str = None) -> Optional[str]:
      """Generate an image using any FLUX model."""
      endpoint = {
          "flux.1.1-pro": "/v1/flux-pro-1.1",
          "flux.1-pro": "/v1/flux-pro",
          "flux.1-dev": "/v1/flux-dev",
          "flux.1.1-ultra": "/v1/flux-pro-1.1-ultra",
      }.get(model)
      
      if not endpoint:
          raise ValueError(f"Unknown model: {model}")
      
      # Set default dimensions based on aspect ratio if provided
      if aspect_ratio:
          if aspect_ratio == '1:1':
              width, height = 1024, 1024
          elif aspect_ratio == '4:3':
              width, height = 1024, 768
          elif aspect_ratio == '3:4':
              width, height = 768, 1024
          elif aspect_ratio == '16:9':
              width, height = 1024, 576
          elif aspect_ratio == '9:16':
              width, height = 576, 1024
      else:
          # Use defaults if neither aspect ratio nor dimensions are provided
          width = width or 1024
          height = height or 768
      
      payload = {
          "prompt": prompt,
          "width": width,
          "height": height,
          "aspect_ratio": aspect_ratio if aspect_ratio else None
      }
      response = requests.post(
          f"{self.base_url}{endpoint}",
          json=payload,
          headers=self.headers
      )
      
      task_id = response.json().get('id')
      if not task_id:
          print("Failed to start generation task")
          return None
          
      result = self.get_task_result(task_id)
      if result and result.get('result', {}).get('sample'):
          return result['result']['sample']
      return None