control

Instructions

Implementation Reference

• src/index.ts:359-382 (handler)

  The main handler for the MCP 'control' tool. It validates the input arguments according to ControlArgs type, constructs CLI arguments, spawns the fluxcli.py process with 'control' command, captures output, and returns it as tool response.

  case 'control': {
      const args = request.params.arguments as ControlArgs;
      // Validate required fields
      const type = this.validateRequiredString(args.type, 'type') as ControlType;
      const image = this.validateRequiredString(args.image, 'image');
      const prompt = this.validateRequiredString(args.prompt, 'prompt');
  
      // Validate optional numeric fields
      const steps = this.validateNumber(args.steps, 'steps', 1, 100);
      const guidance = this.validateNumber(args.guidance, 'guidance', 0, 100);
  
      const cmdArgs = ['control'];
      cmdArgs.push('--type', type);
      cmdArgs.push('--image', image);
      cmdArgs.push('--prompt', prompt);
      if (steps) cmdArgs.push('--steps', steps.toString());
      if (guidance !== undefined) cmdArgs.push('--guidance', guidance.toString());
      if (args.output) cmdArgs.push('--output', args.output);
  
      const output = await this.runPythonCommand(cmdArgs);
      return {
          content: [{ type: 'text', text: output }],
      };
  }

• src/index.ts:250-285 (registration)

  Registration of the 'control' tool in the MCP server's listTools response, including name, description, and detailed inputSchema matching the ControlArgs interface.

  {
      name: 'control',
      description: 'Generate an image using structural control',
      inputSchema: {
          type: 'object',
          properties: {
              type: {
                  type: 'string',
                  description: 'Type of control to use',
                  enum: ['canny', 'depth', 'pose'],
              },
              image: {
                  type: 'string',
                  description: 'Input control image path',
              },
              prompt: {
                  type: 'string',
                  description: 'Text prompt for generation',
              },
              steps: {
                  type: 'number',
                  description: 'Number of inference steps',
                  default: 50,
              },
              guidance: {
                  type: 'number',
                  description: 'Guidance scale',
              },
              output: {
                  type: 'string',
                  description: 'Output filename',
              },
          },
          required: ['type', 'image', 'prompt'],
      },
  },

• src/types.ts:74-81 (schema)

  TypeScript interface defining the structure of arguments expected by the 'control' tool handler.

  export interface ControlArgs {
    type: ControlType;
    image: string;
    prompt: string;
    steps?: number;
    guidance?: number;
    output?: string;
  }

• src/types.ts:22-22 (schema)

  Type definition for valid control types used in ControlArgs.

  export type ControlType = 'canny' | 'depth' | 'pose';

• src/cli/fluxcli.py:195-236 (helper)

  Underlying Python helper method invoked by the CLI 'control' command, which makes the actual API call to BFL for control-guided image generation (canny, depth, pose). Called indirectly by the MCP handler via subprocess.

  def control_generate(self, control_type: str, control_image: str, prompt: str, **kwargs) -> Optional[str]:
      """Generate an image using any supported control type."""
      endpoints = {
          'canny': '/v1/flux-pro-1.0-canny',
          'depth': '/v1/flux-pro-1.0-depth',
          'pose': '/v1/flux-pro-1.0-pose'
      }
      
      default_params = {
          'canny': {'guidance': 30},
          'depth': {'guidance': 15},
          'pose': {'guidance': 25}
      }
      
      if control_type not in endpoints:
          raise ValueError(f"Unsupported control type: {control_type}")
          
      payload = {
          "prompt": prompt,
          "control_image": self.encode_image(control_image),
          "steps": kwargs.get('steps', 50),
          "output_format": kwargs.get('output_format', 'jpeg'),
          "safety_tolerance": kwargs.get('safety_tolerance', 2)
      }
      
      payload.update(default_params.get(control_type, {}))
      payload.update(kwargs)
      
      response = requests.post(
          f"{self.base_url}{endpoints[control_type]}",
          json=payload,
          headers=self.headers
      )
      
      task_id = response.json().get('id')
      if not task_id:
          return None
          
      result = self.get_task_result(task_id)
      if result and result.get('result', {}).get('sample'):
          return result['result']['sample']
      return None