Skip to content

Latest commit

 

History

History
188 lines (163 loc) · 4.39 KB

AGENT_TOOL_REFERENCE.md

File metadata and controls

188 lines (163 loc) · 4.39 KB

🛠️ MCP Tool API Reference for AI Agents

Formal JSON Schema definitions, input parameter specifications, and response payloads for all Model Context Protocol (MCP) tools provided by the DreamBees MLX MCP Server.


1. dreambees_generate_image

Execute local Apple Silicon Metal GPU image generation with real-time TAESD preview and step telemetry.

Input Schema

{
  "type": "object",
  "properties": {
    "prompt": {
      "type": "string",
      "description": "The textual prompt description for the image to generate"
    },
    "model_id": {
      "type": "string",
      "default": "flux2-klein-4b",
      "description": "MLX model ID (e.g. z-image-turbo, flux2-klein-4b, sana-2-sprint, wan2.1-1.3b)"
    },
    "width": {
      "type": "integer",
      "default": 512,
      "description": "Image width in pixels"
    },
    "height": {
      "type": "integer",
      "default": 512,
      "description": "Image height in pixels"
    },
    "steps": {
      "type": "integer",
      "default": 2,
      "description": "Number of inference diffusion steps"
    },
    "seed": {
      "type": "integer",
      "description": "Optional entropy seed integer"
    }
  },
  "required": ["prompt"]
}

Output Response Example

{
  "status": "success",
  "output_path": "/tmp/dreambees_mcp_1721815000000_42.png",
  "duration_ms": 15847,
  "model_id": "flux2-klein-4b",
  "seed": 42,
  "width": 512,
  "height": 512,
  "metal_accelerated": true,
  "preview_data_url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
}

2. dreambees_list_models

List available Apple Silicon MLX models, readiness status, precision, and VRAM requirements.

Input Schema

{ "type": "object", "properties": {} }

Output Response Example

{
  "models": [
    {
      "id": "flux2-klein-4b",
      "name": "FLUX.2 Klein 4B",
      "provider": "Black Forest Labs / MLX",
      "precision": "4-bit Quantized",
      "status": "ready",
      "vram_required_gb": 3.1
    },
    {
      "id": "sana-2-sprint",
      "name": "Sana 2.0 Sprint",
      "provider": "SceneWorks / MLX",
      "precision": "4-bit Quantized",
      "status": "ready",
      "vram_required_gb": 2.8
    }
  ]
}

3. dreambees_run_benchmark

Run the 12-test MLX Metal benchmark suite for a target model ID or fetch recent benchmark results report.

Input Schema

{
  "type": "object",
  "properties": {
    "model_id": {
      "type": "string",
      "default": "flux2-klein-4b",
      "description": "Target model ID to benchmark (e.g. flux2-klein-4b, z-image-turbo)"
    },
    "run_fresh": {
      "type": "boolean",
      "default": false,
      "description": "Run fresh benchmark suite or return cached report"
    }
  }
}

4. dreambees_get_metal_diagnostics

Fetch Apple Silicon Metal GPU hardware diagnostics, active VRAM, peak memory, and cache limits.

Input Schema

{ "type": "object", "properties": {} }

Output Response Example

{
  "status": "ready",
  "diagnostics": {
    "mlx_available": true,
    "metal_available": true,
    "device": "metal",
    "backend": "apple_mlx",
    "active_vram_mb": 2087,
    "peak_vram_mb": 3569,
    "cache_vram_mb": 3047
  }
}

5. dreambees_rewrite_prompt

Transform raw user prompt intent into a target model-card-optimized image generation prompt using the packaged onboard Gemma 4 Prompt Rewriter Engine.

Input Schema

{
  "type": "object",
  "properties": {
    "intent": {
      "type": "string",
      "description": "Raw user prompt intent (e.g. 'cyberpunk street at night')"
    },
    "target_model_id": {
      "type": "string",
      "default": "sana-2-sprint",
      "description": "Target image model card ID (e.g. sana-2-sprint, flux2-klein-4b, wan2.1-t2i-1.3b, sd-3.5-large)"
    }
  },
  "required": ["intent"]
}

Output Response Example

{
  "id": "gemma_1721815000000_12",
  "original_intent": "cyberpunk street at night",
  "rewritten_prompt": "Expansive wide-angle landscape depicting cyberpunk street at night, hyper-aesthetic artwork, vibrant studio lighting, crisp subject isolation, pristine color grading",
  "reasoning": "Gemma 4 evaluated target model card specs for 'Sana 2.0 Sprint'. Applied spatial composition and high aesthetic clarity.",
  "target_model_id": "sana-2-sprint",
  "model_card_name": "Sana 2.0 Sprint",
  "duration_ms": 34,
  "timestamp": 1721815000000
}