darekrossman/fluxlora-mcp

FluxLoRA MCP Server

An MCP (Model Context Protocol) server that lets users and autonomous agents generate high-quality images in a chosen artistic style by automatically discovering and applying open-source LoRA (Low-Rank Adaptation) models.

Features

• Tool: generate_image - Generate images with automatic LoRA selection based on style
• Tool: discover_loras - Search for LoRA models from HuggingFace Hub or local directories
• Tool: save_image_to_disk - Save generated images to the local filesystem
• Resource: lora://{name} - Access metadata for LoRA models
• Resource: config://defaults - View effective configuration defaults
• Prompts - Helper prompts for LLMs to use the tools effectively

Project Structure

fluxlora-mcp/
├── bin/                   # Executable scripts
├── scripts/               # Dev utility scripts
├── src/
│   ├── config/            # Environment configuration
│   ├── mcp/               # MCP server implementation
│   ├── prompts/           # System prompts for LLMs
│   ├── resources/         # MCP resources
│   ├── services/          # External service integrations
│   │   ├── fal/           # Fal.ai client for image generation
│   │   ├── fs/            # Filesystem operations
│   │   └── hf/            # HuggingFace Hub client
│   ├── tools/             # MCP tool implementations
│   │   ├── discover_loras.ts
│   │   ├── generate_image.ts
│   │   └── save_image_to_disk.ts
│   ├── types/             # TypeScript type definitions
│   └── utils/             # Utility functions
├── IMPLEMENTATION-PLAN.md # Current status and roadmap
└── README.md              # This file

Technology Stack

• TypeScript: Type-safe JavaScript for robust development
• Zod: Runtime validation for input/output schemas
• MCP SDK: Integration with the Model Context Protocol
• Fal.ai Client: API client for image generation
• HuggingFace Hub: API client for discovering LoRA models

Installation

# Clone the repository
git clone https://github.com/yourusername/fluxlora-mcp.git
cd fluxlora-mcp

# Install dependencies
npm install

Configuration

Copy the example environment file and update with your settings:

cp .env.example .env

Required environment variables:

• FAL_KEY - Your Fal API key (get one from Fal.ai)
• HF_TOKEN - Optional Hugging Face API token for increased rate limits

Development

# Start the server in development mode
npm run dev

# Build the project with TypeScript
npm run build

# Create an optimized bundle with esbuild
npm run bundle

# Run tests
npm test

# Run the MCP Inspector with your development server
npm run inspect

# Lint and typecheck your code
npm run lint
npm run typecheck

Using the MCP Inspector

The project includes integration with the MCP Inspector, an interactive developer tool for testing and debugging MCP servers.

With the Inspector, you can:

• Test your tools, resources, and prompts interactively
• Inspect server responses and error handling
• Subscribe to resources and observe real-time updates
• Verify tool schemas and input validation

To use the Inspector:

1. First build your project: npm run build
2. Run the inspector: npm run inspect
3. Use the web interface that opens automatically to interact with your server

Deployment

The project supports multiple build options:

1. TypeScript Build: Standard TypeScript compilation (npm run build)

   • Output: dist/
   • Usage: node dist/index.js

2. Optimized Bundle: Single-file bundle with esbuild (npm run bundle)

   • Output: dist/bundle/index.js
   • Usage: node dist/bundle/index.js
   • Benefits: Faster startup, smaller deployment size, simpler dependencies

Usage

The server exposes an MCP-compatible API that can be used with any MCP client. Here are some examples:

Generate an Image

// Using an MCP client
const response = await client.invokeTool('generate_image', {
  prompt: 'A watercolor portrait of a cyberpunk cat',
  style: 'watercolor',
  width: 512,
  height: 512
});

console.log(response.image.url);

Discover LoRA Models

const loras = await client.invokeTool('discover_loras', {
  style: 'anime',
  limit: 10
});

console.log(loras.results);

Save an Image

const result = await client.invokeTool('save_image_to_disk', {
  url: 'https://example.com/image.png'
});

console.log(result.filePath);

Project Roadmap

Completed

• ✅ MCP server with protocol integration
• ✅ Fal.ai client implementation
• ✅ Image generation with parameter validation
• ✅ HuggingFace Hub integration for LoRA discovery
• ✅ Image storage utilities with security checks
• ✅ Configuration resource implementation
• ✅ System prompts for LLMs

In Progress

• 🔄 Testing infrastructure
• 🔄 Enhanced LoRA discovery with better style mapping
• 🔄 Local .safetensor file scanning

Planned

• ⏳ LoRA resource implementation
• ⏳ API response caching
• ⏳ Logging infrastructure
• ⏳ Performance optimization
• ⏳ Documentation site
• ⏳ Release automation

Future Enhancements

• Batch image generation
• Grid view outputs
• ControlNet integration
• Video and audio generation
• Optional web UI

Documentation

For more detailed documentation, see:

Dependencies

• MCP TypeScript SDK: @modelcontextprotocol/sdk
• Fal Client: @fal-ai/client
• HuggingFace Hub: @huggingface/hub
• Zod: zod

License

MIT