Fluvie MCP Server

Model Context Protocol server for the Fluvie video composition library. Provides AI-powered documentation search, code generation, and template suggestions.

📖 Documentation | 🔌 Live Server

Related Projects

Project	Description
📦 fluvie	Main Flutter package for programmatic video generation
🤖 fluvie_mcp_server	MCP server for AI-assisted development (this repo)
🌐 fluvie_website	Marketing website source code

Quick Start

Local Development

# Install dependencies
dart pub get

# Run the server
dart run bin/server.dart

Server starts at http://localhost:8080

Docker

# Build and run
docker-compose up -d

# With HTTPS (Traefik)
docker-compose --profile with-proxy up -d

Endpoints

Endpoint	Method	Description
/	GET	API documentation
/health	GET	Health check
/mcp	POST	MCP JSON-RPC endpoint
/mcp/sse	GET	Server-Sent Events stream
/resources/{path}	GET	Resource access

MCP Tools

searchDocs

Search Fluvie documentation with TF-IDF ranking.

{
  "query": "animate text opacity",
  "category": "widgets",
  "limit": 5
}

getTemplate

Get detailed information about a template.

{
  "category": "intro",
  "name": "TheNeonGate"
}

suggestTemplates

Get template recommendations based on use case.

{
  "useCase": "year-end summary",
  "contentType": "stats",
  "mood": "dramatic"
}

getWidgetReference

Get widget documentation and examples.

{
  "widgetName": "AnimatedProp"
}

generateCode

Generate Fluvie code from natural language.

{
  "description": "Create an intro with a neon portal effect",
  "type": "scene",
  "fps": 30,
  "aspectRatio": "16:9"
}

MCP Resources

URI	Description
fluvie://docs/ai-reference	Complete AI reference documentation
fluvie://templates	Template catalog JSON

Client Configuration

Claude Desktop

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "fluvie": {
      "url": "https://mcp.fluvie.dev/mcp",
      "transport": "http"
    }
  }
}

VS Code (Continue.dev)

{
  "models": [...],
  "mcpServers": {
    "fluvie": {
      "url": "https://mcp.fluvie.dev/mcp"
    }
  }
}

Self-Hosted

{
  "mcpServers": {
    "fluvie": {
      "url": "http://localhost:8080/mcp",
      "transport": "http"
    }
  }
}

Configuration

Copy .env.example to .env and configure:

# Server port
PORT=8080

# Documentation path
DOCS_PATH=../doc

# Logging level
LOG_LEVEL=info

Deployment

Production with Docker

# Build production image
docker build -t fluvie-mcp:latest .

# Run with documentation volume
docker run -d \
  -p 8080:8080 \
  -v /path/to/docs:/app/data/docs:ro \
  --name fluvie-mcp \
  fluvie-mcp:latest

With Traefik (HTTPS)

# Set your email for Let's Encrypt
export ACME_EMAIL=you@example.com

# Start with proxy profile
docker-compose --profile with-proxy up -d

Development

Project Structure

mcp-server/
├── bin/server.dart           # Main entry point
├── lib/
│   ├── mcp_server.dart       # Library exports
│   └── src/
│       ├── config/           # Server configuration
│       ├── mcp/              # MCP protocol handling
│       ├── tools/            # MCP tool implementations
│       ├── indexing/         # Documentation indexer
│       └── middleware/       # HTTP middleware
├── data/docs/                # Documentation files
├── Dockerfile
└── docker-compose.yml

Adding a New Tool

1. Create tool file in lib/src/tools/
2. Implement the tool function
3. Register in bin/server.dart

// lib/src/tools/my_tool.dart
ToolDefinition createMyTool() {
  return ToolDefinition(
    name: 'myTool',
    description: 'My custom tool',
    inputSchema: {...},
    handler: (args) async {
      // Implementation
      return {'result': 'data'};
    },
  );
}

License

MIT License - See LICENSE file for details.