# 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

```bash
# 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:

```bash
cp .env.example .env
```

Required environment variables:
- `FAL_KEY` - Your Fal API key (get one from [Fal.ai](https://fal.ai))
- `HF_TOKEN` - Optional Hugging Face API token for increased rate limits

## Development

```bash
# 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](https://github.com/modelcontextprotocol/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

```typescript
// 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

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

console.log(loras.results);
```

### Save an Image

```typescript
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:

- [Implementation Plan](IMPLEMENTATION-PLAN.md)

## Dependencies

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

## License

MIT