# Fal.ai MCP Server

A Model Context Protocol (MCP) server for discovering and documenting Fal.ai models. This server provides tools for coding agents to learn about available models, their schemas, capabilities, and usage patterns.

## Features

- 🔍 **Model Discovery**: List and search Fal.ai models with comprehensive filtering and sorting
- 📋 **Model Information**: Get detailed metadata about specific models, including pricing (with API key)
- 📐 **Schema Retrieval**: Fetch OpenAPI schemas for model parameters
- 📚 **Documentation**: Generate comprehensive documentation with usage examples
- ⚡ **Caching**: Cloudflare KV-based caching for fast model lookups
- 🔑 **Optional Authentication**: Works without API keys, with optional auth for higher rate limits and pricing access
- 🎯 **Advanced Filtering**: Filter by category, status, tags, owner, highlighted, pinned, kind, and more
- 📊 **Flexible Sorting**: Sort by update date, name, category, or owner

## Available Tools

### `list_models`
List all available Fal.ai models with comprehensive filtering and sorting options.

**Filtering Parameters:**
- `category?` (optional): Filter by API category from metadata.category (e.g., `"text-to-image"`, `"image-to-video"`, `"training"`) or array of categories - models must match ANY specified category (e.g., `["text-to-image", "image-to-video"]`)
- `status?` (optional): Filter by status - `"active"` or `"deprecated"`
- `tags?` (optional): Array of tags - models must have ALL specified tags (e.g., `["new", "beta"]`)
- `owner?` (optional): Filter by model owner/organization (e.g., `"fal-ai"`, `"clarityai"`)
- `highlighted?` (optional): Filter to only highlighted models (boolean)
- `pinned?` (optional): Filter to only pinned models (boolean)
- `kind?` (optional): Filter by model kind - `"inference"` or `"training"`
- `search?` (optional): Free-text search across name, description, ID, and tags
- `limit?` (optional): Maximum number of results (1-100, default: 20)
- `sortBy?` (optional): Sort field - `"updated_at"` (most recent first), `"name"` (alphabetical), `"category"` (grouped), or `"owner"` (grouped)

**Common API Categories:**
- `"text-to-image"`, `"image-to-image"`, `"text-to-video"`, `"image-to-video"`, `"video-to-video"`, `"image-to-3d"`, `"text-to-audio"`, `"audio"`, `"audio-to-audio"`, `"speech-to-text"`, `"text-to-speech"`, `"training"`

**Examples:**
```json
// Basic search
{
  "category": "text-to-image",
  "search": "flux",
  "limit": 10
}

// Advanced filtering
{
  "category": ["text-to-image", "image-to-image"],
  "status": "active",
  "tags": ["new"],
  "sortBy": "updated_at",
  "limit": 20
}

// Find models from specific owner
{
  "owner": "fal-ai",
  "highlighted": true,
  "sortBy": "name"
}
```

### `get_model_info`
Get detailed information about a specific model including metadata, capabilities, description, and pricing (when API key is provided).

**Parameters:**
- `model_id` (required): Model endpoint ID (e.g., `"fal-ai/flux-pro"`) or alias (e.g., `"flux_pro"`)

**Returns:**
- Model metadata (name, description, category, owner, status, tags)
- Capabilities information
- Model URL and last updated timestamp
- **Pricing information** (when API key is provided via Authorization header)

**Example:**
```json
{
  "model_id": "fal-ai/flux-pro"
}
```

**Note:** Pricing information is only included when an API key is provided in the Authorization header. Without an API key, all other model information is still available.

### `get_model_schema`
Get the OpenAPI/JSON schema for a model's input and output parameters.

**Parameters:**
- `model_id` (required): Model endpoint ID or alias

**Example:**
```json
{
  "model_id": "fal-ai/flux/dev"
}
```

### `get_model_documentation`
Get comprehensive documentation including usage examples and best practices.

**Parameters:**
- `model_id` (required): Model endpoint ID or alias

**Example:**
```json
{
  "model_id": "fal-ai/flux-pro"
}
```

## Setup

### Prerequisites

- Node.js 18+ and npm
- Cloudflare account
- Wrangler CLI installed globally: `npm install -g wrangler`

### Installation

```bash
# Clone the repository
git clone <repository-url>
cd fal-mcp

# Install dependencies
npm install
```

### Configuration

1. **Create KV Namespace**

   Create a KV namespace for model caching:

   ```bash
   npx wrangler kv namespace create MODEL_CACHE
   ```

   This will output a namespace ID. Update `wrangler.jsonc` with the actual namespace ID:

   ```jsonc
   {
     "kv_namespaces": [
       {
         "binding": "MODEL_CACHE",
         "id": "your_actual_namespace_id_here"
       }
     ]
   }
   ```

2. **Login to Cloudflare**

   ```bash
   npx wrangler login
   ```

## Deployment

### Deploy to Cloudflare Workers

```bash
npm run deploy
```

This will deploy your MCP server to: `fal-mcp.<your-account>.workers.dev/mcp`

### Local Development

```bash
npm run dev
```

The server will be available at `http://localhost:8787/mcp`

## API Key Configuration (Optional)

API keys are **optional** but recommended to avoid rate limits. The server works without authentication, but authenticated requests have higher rate limits.

### How It Works

The server extracts API keys from the `Authorization` header in MCP client requests:

```
Authorization: Key <your-fal-api-key>
```

### Configuring MCP Clients

#### Claude Desktop

Add custom headers in your Claude Desktop configuration:

```json
{
  "mcpServers": {
    "fal-ai": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://fal-mcp.your-account.workers.dev/mcp"
      ],
      "env": {
        "FAL_API_KEY": "your-fal-api-key-here"
      }
    }
  }
}
```

**Note:** The exact method for passing headers depends on your MCP client. Some clients may require using a proxy or wrapper to inject headers.

#### Other MCP Clients

Check your MCP client's documentation for how to pass custom headers. The server expects:
- Header name: `Authorization`
- Header value: `Key <your-api-key>`

### Getting a Fal.ai API Key

1. Sign up at [fal.ai](https://fal.ai)
2. Navigate to your account settings
3. Generate an API key
4. Use it in the `Authorization` header format: `Key <your-api-key>`

## Connecting to MCP Clients

### Using mcp-remote

For local MCP clients like Claude Desktop, use the `mcp-remote` package:

```bash
npm install -g mcp-remote
```

Then configure your MCP client to use:

```
npx mcp-remote https://fal-mcp.your-account.workers.dev/mcp
```

### Direct Connection

If your MCP client supports streamable HTTP transport, connect directly to:

```
https://fal-mcp.your-account.workers.dev/mcp
```

## Architecture

### Components

- **MCP Server** (`src/index.ts`): Main entry point, handles HTTP requests and routes to MCP agent
- **Model Registry** (`src/registry/model-registry.ts`): Manages model cache with KV storage and alias resolution
- **API Client** (`src/utils/fal-api.ts`): Handles all Fal.ai Platform API calls
- **Tools** (`src/tools/fal-ai.tools.ts`): MCP tool implementations
- **Types** (`src/types/fal-model.ts`): TypeScript interfaces and Zod schemas

### Caching Strategy

- Models are cached in Cloudflare KV with a 1-hour TTL
- Cache is automatically refreshed when expired
- Falls back to stale cache if API calls fail
- Supports graceful degradation without API keys

### API Integration

The server uses the Fal.ai Platform API for:
- Model discovery with pagination (`GET /v1/models`)
- Model metadata retrieval
- OpenAPI schema expansion (`expand=openapi-3.0`)
- Pricing information (`GET /v1/models/pricing`) - requires authentication

All API calls are made server-side, so MCP clients don't need direct API access.

## Development

### Type Checking

```bash
npm run typecheck
```

### Linting

```bash
npm run lint:fix
```

### Formatting

```bash
npm run format
```

### Generate Cloudflare Types

```bash
npm run cf-typegen
```

## Project Structure

```
fal-mcp/
├── src/
│   ├── index.ts              # Main entry point, MCP agent
│   ├── registry/
│   │   └── model-registry.ts # Model cache and registry
│   ├── tools/
│   │   └── fal-ai.tools.ts   # MCP tool implementations
│   ├── types/
│   │   └── fal-model.ts      # TypeScript types and Zod schemas
│   └── utils/
│       └── fal-api.ts        # Fal.ai API client
├── wrangler.jsonc            # Cloudflare Workers configuration
├── package.json
└── README.md
```

## Error Handling

The server handles errors gracefully:

- **Rate Limit (429)**: Uses stale cache if available, provides helpful message about API keys
- **Authentication Error (401)**: Clear message about checking API key format
- **Not Found (404)**: Suggests using `list_models` to find available models
- **Network Errors**: Falls back to stale cache when possible

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Contributing

Contributions are welcome! Please read our [Contributing Guidelines](CONTRIBUTING.md) for details on our code of conduct and the process for submitting pull requests.

## References

- [Fal.ai Platform API Documentation](https://docs.fal.ai/model-apis)
- [Model Context Protocol](https://modelcontextprotocol.io)
- [Cloudflare Workers](https://developers.cloudflare.com/workers/)
- [Cloudflare Agents SDK](https://github.com/cloudflare/agents)