{"id":32841166,"url":"https://github.com/brandonhenry/ffmcp","last_synced_at":"2026-05-06T02:39:50.554Z","repository":{"id":322927655,"uuid":"1091028245","full_name":"brandonhenry/ffmcp","owner":"brandonhenry","description":null,"archived":false,"fork":false,"pushed_at":"2025-11-07T05:22:18.000Z","size":3531,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-07T05:34:59.681Z","etag":null,"topics":["ai","artificial","claude","intelligence","mcp","openai"],"latest_commit_sha":null,"homepage":"https://ffmcp.org","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/brandonhenry.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-06T13:12:14.000Z","updated_at":"2025-11-07T05:22:22.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/brandonhenry/ffmcp","commit_stats":null,"previous_names":["brandonhenry/ffmcp"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/brandonhenry/ffmcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brandonhenry%2Fffmcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brandonhenry%2Fffmcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brandonhenry%2Fffmcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brandonhenry%2Fffmcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/brandonhenry","download_url":"https://codeload.github.com/brandonhenry/ffmcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brandonhenry%2Fffmcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":283238872,"owners_count":26803102,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-11-07T02:00:06.343Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","artificial","claude","intelligence","mcp","openai"],"created_at":"2025-11-08T02:01:10.605Z","updated_at":"2026-05-06T02:39:50.545Z","avatar_url":"https://github.com/brandonhenry.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ffmcp\n\n**ffmcp** - AI command-line tool inspired by ffmpeg. Access any AI service from the command line with a unified interface.\n\n[![PyPI version](https://img.shields.io/pypi/v/ffmcp.svg)](https://pypi.org/project/ffmcp/)\n[![PyPI downloads](https://img.shields.io/pypi/dm/ffmcp.svg)](https://pypi.org/project/ffmcp/)\n[![npm version](https://img.shields.io/npm/v/ffmcp.svg)](https://www.npmjs.com/package/ffmcp)\n[![npm downloads](https://img.shields.io/npm/dm/ffmcp.svg)](https://www.npmjs.com/package/ffmcp)\n\n**Install via pip:** `pip install ffmcp` | **Install via npm:** `npm install -g ffmcp` | **Install from source:** See [Installation](#installation) below\n\n## Features\n\n- 🚀 **Unified CLI**: Single command-line interface for multiple AI providers\n- 🔌 **11 AI Providers**: OpenAI, Anthropic, Google Gemini, Groq, DeepSeek, Mistral AI, Together AI, Cohere, Perplexity, AI33, and AIMLAPI\n- 📝 **Simple**: Works just like ffmpeg - simple, powerful, composable\n- 🔧 **Configurable**: Manage API keys and settings easily\n- 📊 **Streaming**: Real-time streaming support for responses\n- 🎨 **Full OpenAI Support**: All OpenAI features including vision, images, audio, embeddings, and assistants\n- 🧠 **Memory with Zep/LEANN (Brains)**: Create brains with Zep (cloud/self-hosted) or LEANN (local, 97% storage savings), store/retrieve chat memory, collections, and graph\n- 🤖 **Agents**: Named agents with model, instructions, brain, dynamic properties, and actions (web, images, vision, embeddings)\n- 👥 **Multi-Agent Teams**: Agents can work together in teams, delegate tasks, and collaborate to accomplish complex goals\n- 💬 **Threads**: Conversation history for both chat and agents - maintain context across multiple interactions\n- 🎤 **Voiceover/TTS**: Full text-to-speech support with multiple providers (ElevenLabs), voice management, and agent voice integration\n\n## Installation\n\n### Option 1: pip Installation (Recommended)\n\nThe easiest way to install ffmcp is via pip:\n\n```bash\n# Install the base package\npip install ffmcp\n\n# Or install with specific providers\npip install ffmcp[openai]\npip install ffmcp[anthropic]\npip install ffmcp[zep]      # Zep memory support\npip install ffmcp[leann]    # LEANN memory support (optional, requires system dependencies)\npip install ffmcp[all]      # All providers (does not include LEANN - install separately if needed)\n```\n\n**Note:** On macOS with Homebrew Python, you may encounter an \"externally-managed-environment\" error. Use a virtual environment:\n\n```bash\npython3 -m venv venv\nsource venv/bin/activate  # On Windows: venv\\Scripts\\activate\npip install ffmcp\n```\n\n### Option 2: npm Installation\n\n**Prerequisites:** You need both the Python package (via pip) and npm package installed.\n\n1. **Install Python package** (required):\n   ```bash\n   pip install ffmcp\n   ```\n\n2. **Install npm package**:\n   ```bash\n   # Install globally (for CLI usage)\n   npm install -g ffmcp\n   \n   # Or install locally in your project\n   npm install ffmcp\n   ```\n\n**Note:** The npm package is a wrapper around the Python CLI. Both packages must be installed for it to work.\n\n### Option 3: Install from Source (Development)\n\nFor development or to get the latest features:\n\n```bash\n# Clone the repository\ngit clone https://github.com/brandonhenry/ffmcp.git\ncd ffmcp\n\n# Create a virtual environment (recommended)\npython3 -m venv venv\nsource venv/bin/activate  # On Windows: venv\\Scripts\\activate\n\n# Install in development mode\npip install -e .\n\n# Or install with specific providers\npip install -e \".[openai]\"\npip install -e \".[anthropic]\"\npip install -e \".[all]\"\n```\n\n**Requirements:**\n- **Python Versions**: Supports Python 3.8 through 3.14.\n- **Node.js Versions**: npm package requires Node.js \u003e= 14.0.0.\n\n## Quick Start\n\n### 1. Configure API Keys\n\n```bash\n# Set OpenAI API key\nffmcp config -p openai -k YOUR_OPENAI_API_KEY\n\n# Set Anthropic API key\nffmcp config -p anthropic -k YOUR_ANTHROPIC_API_KEY\n\n# Set Google Gemini API key\nffmcp config -p gemini -k YOUR_GEMINI_API_KEY\n\n# Set Groq API key\nffmcp config -p groq -k YOUR_GROQ_API_KEY\n\n# Set DeepSeek API key\nffmcp config -p deepseek -k YOUR_DEEPSEEK_API_KEY\n\n# Set Mistral AI API key\nffmcp config -p mistral -k YOUR_MISTRAL_API_KEY\n\n# Set Together AI API key\nffmcp config -p together -k YOUR_TOGETHER_API_KEY\n\n# Set Cohere API key\nffmcp config -p cohere -k YOUR_COHERE_API_KEY\n\n# Set Perplexity API key\nffmcp config -p perplexity -k YOUR_PERPLEXITY_API_KEY\n\n# Set AI33 API key\nffmcp config -p ai33 -k YOUR_AI33_API_KEY\n\n# Set AIMLAPI API key\nffmcp config -p aimlapi -k YOUR_AIMLAPI_API_KEY\n\n# Set ElevenLabs API key (for voiceover/TTS)\nffmcp config -p elevenlabs -k YOUR_ELEVENLABS_API_KEY\n\n# Or use environment variables (provider name in uppercase)\nexport OPENAI_API_KEY=your_key\nexport ANTHROPIC_API_KEY=your_key\nexport GEMINI_API_KEY=your_key\nexport GROQ_API_KEY=your_key\nexport DEEPSEEK_API_KEY=your_key\nexport MISTRAL_API_KEY=your_key\nexport TOGETHER_API_KEY=your_key\nexport COHERE_API_KEY=your_key\nexport PERPLEXITY_API_KEY=your_key\nexport AI33_API_KEY=your_key\nexport AIMLAPI_API_KEY=your_key\nexport ELEVENLABS_API_KEY=your_key\n```\n\n### 2. Generate Text\n\n```bash\n# Basic generation\nffmcp generate \"Write a haiku about coding\"\n\n# With specific provider and model\nffmcp generate \"Explain quantum computing\" -p openai -m gpt-4\nffmcp generate \"Explain quantum computing\" -p gemini -m gemini-1.5-pro\nffmcp generate \"Explain quantum computing\" -p groq -m llama-3.1-70b-versatile\nffmcp generate \"Explain quantum computing\" -p deepseek -m deepseek-chat\nffmcp generate \"Explain quantum computing\" -p mistral -m mistral-large-latest\nffmcp generate \"Explain quantum computing\" -p together -m meta-llama/Llama-3-70b-chat-hf\nffmcp generate \"Explain quantum computing\" -p cohere -m command-r-plus\nffmcp generate \"Explain quantum computing\" -p perplexity -m llama-3.1-sonar-large-128k-online\n\n# Stream the response\nffmcp generate \"Tell me a story\" -s\n\n# With system message\nffmcp generate \"Solve this math problem\" --system \"You are a helpful math tutor\"\n\n# Read from file\nffmcp generate -i prompt.txt -o output.txt\n\n# Pipe input\necho \"Summarize this\" | ffmcp generate\n\n# Output as JSON\nffmcp generate \"Write a haiku\" --json\n\n# Output as array\nffmcp generate \"Write a haiku\" --array\n```\n\n### 3. Chat Mode\n\n```bash\n# Conversational chat\nffmcp chat \"Hello, how are you?\" -p anthropic\n\n# With system message\nffmcp chat \"What is 2+2?\" -s \"You are a helpful math tutor\"\n\n# Chat with thread (maintains conversation history)\nffmcp chat \"Hello\" -t conversation1\nffmcp chat \"What did I just say?\" -t conversation1  # Remembers previous messages\n\n# Output as JSON\nffmcp chat \"Write a haiku\" --json\n\n# Output as array\nffmcp chat \"Write a haiku\" --array\n\n# Thread management\nffmcp thread create conversation1\nffmcp thread list\nffmcp thread use conversation1\nffmcp thread current\nffmcp thread clear conversation1\nffmcp thread delete conversation1\n```\n\n### 4. Agents\n\n```bash\n# Create an agent (any provider, default actions enabled)\nffmcp agent create myagent -p openai -m gpt-4o-mini -i \"You are a helpful assistant\" --brain mybrain\nffmcp agent create gemini-agent -p gemini -m gemini-2.0-flash-exp -i \"You are a helpful assistant\"\nffmcp agent create groq-agent -p groq -m llama-3.1-70b-versatile -i \"You are a helpful assistant\"\n\n# Create an agent with voice (for TTS)\nffmcp agent create myagent -p openai -m gpt-4o-mini -i \"You are a helpful assistant\" --voice my-voice\n\n# Create an agent with instructions from a file\nffmcp agent create myagent -p openai -m gpt-4o-mini -f instructions.txt --brain mybrain\n\n# List and select the active agent\nffmcp agent list\nffmcp agent use myagent\n\n# Show details\nffmcp agent show\n\n# Thread Management (conversation history)\nffmcp agent thread create myagent thread1\nffmcp agent thread list myagent\nffmcp agent thread use myagent thread1\nffmcp agent thread current myagent\nffmcp agent thread clear myagent thread1\nffmcp agent thread delete myagent thread1\n\n# Run the agent (uses active thread automatically)\nffmcp agent run \"Plan a 3-day trip to Paris and fetch top sights\"\n\n# Run with specific thread\nffmcp agent run \"Continue planning\" --thread thread1\n\n# Output as JSON\nffmcp agent run \"Write a summary\" --json\n\n# Output as array\nffmcp agent run \"Write a summary\" --array\n\n# Manage properties and actions\nffmcp agent prop set myagent timezone UTC\nffmcp agent action enable myagent web_fetch\nffmcp agent action disable myagent generate_image\n```\n\n**See [Threads: Conversation History](#threads-conversation-history) section for detailed thread documentation.**\n\n### 5. Multi-Agent Teams (Hierarchical)\n\nAgents can work together in hierarchical teams to accomplish complex tasks. Teams use an orchestrator agent at the top that orchestrates collaboration by delegating tasks to members or sub-teams. All activity flows up through the hierarchy, and the top orchestrator has visibility into everything through shared brain/memory.\n\n```bash\n# Create specialized agents\nffmcp agent create researcher -p openai -m gpt-4o-mini -i \"You are a research specialist. Focus on finding and analyzing information.\"\nffmcp agent create writer -p openai -m gpt-4o-mini -i \"You are a writing specialist. Focus on creating clear, well-structured content.\"\nffmcp agent create orchestrator -p openai -m gpt-4o-mini -i \"You are a project orchestrator. Break down tasks and delegate to team members.\"\n\n# Enable delegation action for orchestrator (allows it to delegate to other agents)\nffmcp agent action enable orchestrator delegate_to_agent\n\n# Create a simple team with orchestrator and members\nffmcp team create research-team -o orchestrator -m researcher -m writer\n\n# Create a shared brain for team memory (flows up hierarchy)\nffmcp brain create team-brain\nffmcp team create project-team -o orchestrator -m researcher -m writer -b team-brain\n\n# Create nested teams (teams within teams)\n# First create sub-teams\nffmcp agent create sub-orchestrator-1 -p openai -m gpt-4o-mini -i \"You coordinate a research sub-team\"\nffmcp agent action enable sub-orchestrator-1 delegate_to_agent\nffmcp team create research-sub-team -o sub-orchestrator-1 -m researcher -b team-brain\n\nffmcp agent create sub-orchestrator-2 -p openai -m gpt-4o-mini -i \"You coordinate a writing sub-team\"\nffmcp agent action enable sub-orchestrator-2 delegate_to_agent\nffmcp team create writing-sub-team -o sub-orchestrator-2 -m writer -b team-brain\n\n# Create top-level team with sub-teams\nffmcp team create main-team -o orchestrator -s research-sub-team -s writing-sub-team -b team-brain\n\n# Run a task with the hierarchical team (orchestrator delegates as needed)\nffmcp team run \"Research and write a comprehensive report on quantum computing\" --team main-team\n\n# Output as JSON\nffmcp team run \"Create a report\" --team main-team --json\n\n# Output as array\nffmcp team run \"Create a report\" --team main-team --array\n\n# List teams\nffmcp team list\n\n# Show team details including hierarchy\nffmcp team show main-team\n\n# Add/remove members and sub-teams\nffmcp team add-member main-team analyst\nffmcp team add-sub-team main-team analysis-sub-team\nffmcp team remove-member main-team analyst\n\n# Set a different orchestrator\nffmcp team set-orchestrator main-team new-orchestrator\n```\n\n**How Hierarchical Teams Work:**\n- **Orchestrator**: One agent at the top level that receives tasks and orchestrates collaboration\n- **Members**: Direct agent members below the orchestrator\n- **Sub-teams**: Nested teams with their own orchestrators and members (supports multiple layers)\n- **Shared Brain**: Memory context that flows up the hierarchy - the top orchestrator sees all activity\n- **Delegation**: Orchestrators can delegate to members or sub-team orchestrators\n- **Visibility**: All activity flows up through the hierarchy, giving the top orchestrator complete visibility\n\n**Example Hierarchical Structure:**\n```\nmain-team (orchestrator: ceo)\n├── research-sub-team (orchestrator: research-manager)\n│   ├── researcher-1\n│   └── researcher-2\n├── writing-sub-team (orchestrator: writing-manager)\n│   ├── writer-1\n│   └── writer-2\n└── direct-member (analyst)\n```\n\n**Example Workflow:**\n```bash\n# 1. Create agents for different roles\nffmcp agent create ceo -p openai -m gpt-4o-mini -i \"You are a CEO orchestrating multiple teams\"\nffmcp agent create research-manager -p openai -m gpt-4o-mini -i \"You manage a research team\"\nffmcp agent create writing-manager -p openai -m gpt-4o-mini -i \"You manage a writing team\"\nffmcp agent create researcher-1 -p openai -m gpt-4o-mini -i \"You are a researcher\"\nffmcp agent create writer-1 -p openai -m gpt-4o-mini -i \"You are a writer\"\n\n# 2. Enable delegation for orchestrators\nffmcp agent action enable ceo delegate_to_agent\nffmcp agent action enable research-manager delegate_to_agent\nffmcp agent action enable writing-manager delegate_to_agent\n\n# 3. Create shared brain for team memory\nffmcp brain create org-brain\n\n# 4. Create sub-teams\nffmcp team create research-team -o research-manager -m researcher-1 -b org-brain\nffmcp team create writing-team -o writing-manager -m writer-1 -b org-brain\n\n# 5. Create top-level team with sub-teams\nffmcp team create org-team -o ceo -s research-team -s writing-team -b org-brain\n\n# 6. Run a complex task - CEO orchestrates, delegates to sub-teams, sees all activity\nffmcp team run \"Create a comprehensive market analysis report\" --team org-team\n```\n\n## OpenAI Features\n\n### Vision / Image Understanding\n\n```bash\n# Analyze images\nffmcp openai vision \"What's in this image?\" image1.jpg image2.png\n\n# With custom model and options\nffmcp openai vision \"Describe this\" photo.jpg -m gpt-4o -t 0.5\n```\n\n### Image Generation (DALL·E)\n\n```bash\n# Generate image with DALL·E 3\nffmcp openai image \"A futuristic cityscape at sunset\"\n\n# DALL·E 2 with custom size\nffmcp openai image \"A cat wearing sunglasses\" -m dall-e-2 --size 512x512\n\n# High quality with natural style\nffmcp openai image \"Abstract art\" --quality hd --style natural\n\n# Save URL to file\nffmcp openai image \"Beautiful landscape\" -o image_url.txt\n```\n\n### Audio Transcription (Whisper)\n\n```bash\n# Transcribe audio to text\nffmcp openai transcribe audio.mp3\n\n# With language hint\nffmcp openai transcribe audio.mp3 -l es\n\n# With prompt for better accuracy\nffmcp openai transcribe meeting.mp3 -p \"This is a technical meeting about AI\"\n\n# Output as JSON with timestamps\nffmcp openai transcribe audio.mp3 --json -o transcript.json\n```\n\n### Audio Translation\n\n```bash\n# Translate audio to English\nffmcp openai translate spanish_audio.mp3\n\n# With prompt\nffmcp openai translate audio.mp3 -p \"Technical presentation\"\n```\n\n### Text-to-Speech\n\n```bash\n# Convert text to speech\nffmcp openai tts \"Hello, world!\" output.mp3\n\n# With custom voice and speed\nffmcp openai tts \"Welcome to the future\" speech.mp3 -v nova -s 1.2\n\n# High quality model\nffmcp openai tts \"Important announcement\" announcement.mp3 -m tts-1-hd\n```\n\n### Voiceover/TTS System\n\nffmcp includes a comprehensive voiceover/TTS system with support for multiple providers (starting with ElevenLabs). You can create voice configurations, manage them, and associate them with agents.\n\n#### Setup\n\n```bash\n# Configure ElevenLabs API key\nffmcp config -p elevenlabs -k YOUR_ELEVENLABS_API_KEY\n\n# Or use environment variable\nexport ELEVENLABS_API_KEY=your_key\n```\n\n#### Discover Available Voices\n\n```bash\n# List all voices from ElevenLabs\nffmcp voiceover provider list --provider elevenlabs\n\n# Show details of a specific voice\nffmcp voiceover provider show --provider elevenlabs 21m00Tcm4TlvDq8ikWAM\n```\n\n#### Create Voice Configurations\n\n```bash\n# Create a voice configuration with default settings\nffmcp voiceover create my-voice \\\n  --provider elevenlabs \\\n  --voice-id 21m00Tcm4TlvDq8ikWAM \\\n  --description \"My favorite voice\"\n\n# Create with custom settings\nffmcp voiceover create narrator \\\n  --provider elevenlabs \\\n  --voice-id pNInz6obpgDQGcFmaJgB \\\n  --model-id eleven_multilingual_v2 \\\n  --stability 0.5 \\\n  --similarity-boost 0.75 \\\n  --style 0.0 \\\n  --use-speaker-boost \\\n  --output-format mp3_44100_128 \\\n  --description \"Narrator voice for stories\"\n```\n\n#### Manage Voice Configurations\n\n```bash\n# List all saved voices\nffmcp voiceover list\n\n# Show voice details\nffmcp voiceover show my-voice\n\n# Update voice settings\nffmcp voiceover update my-voice --stability 0.6 --similarity-boost 0.8\n\n# Delete a voice\nffmcp voiceover delete my-voice\n```\n\n#### Generate Speech\n\n```bash\n# Using a saved voice configuration\nffmcp tts \"Hello, this is a test\" output.mp3 --voice my-voice\n\n# Using provider and voice ID directly\nffmcp tts \"Direct voice usage\" output.mp3 \\\n  --provider elevenlabs \\\n  --voice-id 21m00Tcm4TlvDq8ikWAM\n\n# With custom parameters (overrides saved config)\nffmcp tts \"Custom settings\" output.mp3 \\\n  --voice my-voice \\\n  --stability 0.7 \\\n  --similarity-boost 0.9\n```\n\n#### Agent Voice Integration\n\n```bash\n# Create agent with voice\nffmcp agent create assistant \\\n  -p openai \\\n  -m gpt-4o-mini \\\n  -i \"You are a helpful assistant\" \\\n  --voice my-voice\n\n# Set voice for existing agent\nffmcp agent voice set assistant my-voice\n\n# Show agent's voice\nffmcp agent voice show assistant\n\n# Remove voice from agent\nffmcp agent voice remove assistant\n```\n\n**Voice Parameters:**\n- `--stability` (0.0-1.0): Controls voice stability (lower = more variation)\n- `--similarity-boost` (0.0-1.0): Controls similarity to original voice\n- `--style` (0.0-1.0): Controls style exaggeration\n- `--use-speaker-boost`: Enable speaker boost for clearer speech\n- `--output-format`: Audio format (e.g., `mp3_44100_128`, `pcm_16000`, etc.)\n- `--model-id`: TTS model (e.g., `eleven_multilingual_v2`, `eleven_turbo_v2`)\n\n**Supported Providers:**\n- **ElevenLabs**: High-quality multilingual TTS with voice cloning support\n- More providers coming soon!\n\n### Embeddings\n\n```bash\n# Create embeddings\nffmcp openai embed \"This is a sample text\"\n\n# With custom dimensions\nffmcp openai embed \"Vectorize this\" -d 256\n\n# Output full JSON with usage stats\nffmcp openai embed \"Text to embed\" --json -o embeddings.json\n```\n\n### Function Calling / Tools\n\n```bash\n# Chat with function calling\n# First, create a tools.json file:\ncat \u003e tools.json \u003c\u003c EOF\n[\n  {\n    \"type\": \"function\",\n    \"function\": {\n      \"name\": \"get_weather\",\n      \"description\": \"Get the current weather\",\n      \"parameters\": {\n        \"type\": \"object\",\n        \"properties\": {\n          \"location\": {\"type\": \"string\"}\n        }\n      }\n    }\n  }\n]\nEOF\n\n# Use with chat\nffmcp openai tools \"What's the weather in San Francisco?\" -t tools.json\n```\n\n### Assistants API\n\n```bash\n# Create an assistant\nffmcp openai assistant create \"Math Tutor\" \"You are a helpful math tutor\"\n\n# Create a conversation thread\nffmcp openai assistant thread -o thread_id.txt\n\n# Add a message to thread\nffmcp openai assistant message $(cat thread_id.txt) \"Solve 2x + 5 = 15\"\n\n# Run the assistant\nffmcp openai assistant run $(cat thread_id.txt) $(cat assistant_id.txt)\n\n# Get messages from thread\nffmcp openai assistant messages $(cat thread_id.txt)\n\n# Upload a file for the assistant\nffmcp openai assistant upload document.pdf\n```\n\n### 4. List Providers\n\n```bash\nffmcp providers\n```\n\nThis will show all available providers:\n- **openai** - OpenAI GPT models (GPT-4, GPT-3.5, DALL·E, Whisper, TTS, Embeddings)\n- **anthropic** - Anthropic Claude models (Claude 3.5 Sonnet, Claude 3 Opus, Claude 3 Haiku)\n- **gemini** - Google Gemini models (Gemini 2.0 Flash, Gemini 1.5 Pro, Gemini 1.5 Flash)\n- **groq** - Groq models (Llama 3.1, Mixtral, Gemma) - Ultra-fast inference\n- **deepseek** - DeepSeek models (DeepSeek Chat, DeepSeek Coder) - OpenAI-compatible\n- **mistral** - Mistral AI models (Mistral Large, Mistral Medium, Pixtral)\n- **together** - Together AI models (Access to many open-source models like Llama, Mixtral, Qwen)\n- **cohere** - Cohere models (Command R+, Command R) - Enterprise-focused\n- **perplexity** - Perplexity AI models (Sonar Large, Sonar Pro) - Built-in web search\n\n### 5. Daily Token Tracking\n\nffmcp automatically tracks total tokens used per UTC day across supported providers (e.g., OpenAI, Anthropic). Totals are stored in `~/.ffmcp/tokens.json`.\n\n```bash\n# Show today's total token count (UTC day)\nffmcp tokens\n\n# Filter by provider\nffmcp tokens -p openai\nffmcp tokens -p gemini\nffmcp tokens -p groq\n# ... any provider name\n\n# Specify a date (UTC, YYYY-MM-DD)\nffmcp tokens -d 2025-11-07\n```\n\nNotes:\n- The total is best-effort for streaming responses and depends on provider SDK support for usage in stream events.\n- Token accounting is updated automatically on each command invocation that returns usage from the provider.\n\n## Threads: Conversation History\n\nffmcp supports **threads** to maintain conversation history for both the `chat` command and `agent run` command. Threads allow you to have ongoing conversations where the AI remembers previous messages.\n\n### Chat Threads\n\nChat threads are independent conversation histories that work with the `chat` command:\n\n```bash\n# Create a chat thread\nffmcp thread create conversation1\n\n# Set it as active (optional - chat will use active thread automatically)\nffmcp thread use conversation1\n\n# Chat with conversation history\nffmcp chat \"Hello, my name is Alice\" -t conversation1 -p openai\nffmcp chat \"What's my name?\" -t conversation1 -p openai  # Remembers!\n\n# Or use active thread (no -t needed)\nffmcp chat \"Hello\" -p openai  # Uses active thread automatically\nffmcp chat \"Continue\" -p openai  # Remembers previous message\n\n# With system message (saved to thread)\nffmcp chat \"Solve 2+2\" -s \"You are a math tutor\" -t math-thread\nffmcp chat \"Now solve 5+5\" -t math-thread  # Remembers system message\n\n# Manage threads\nffmcp thread list                    # List all chat threads\nffmcp thread current                 # Show active thread\nffmcp thread clear conversation1     # Clear messages (keeps thread)\nffmcp thread delete conversation1    # Delete thread entirely\n```\n\n**Key Points:**\n- Chat threads are **independent** from agent threads\n- Each thread maintains its own conversation history\n- System messages are saved to the thread on first use\n- Active thread is used automatically if no thread is specified\n\n### Agent Threads\n\nAgent threads are tied to specific agents and maintain conversation history for agent runs:\n\n```bash\n# Create an agent\nffmcp agent create myagent -p openai -m gpt-4o-mini -i \"You are helpful\"\n\n# Create a thread for the agent\nffmcp agent thread create myagent conversation1\n\n# Set it as active (optional - agent run uses active thread automatically)\nffmcp agent thread use myagent conversation1\n\n# Run agent with conversation history\nffmcp agent run \"Plan a trip to Paris\" --agent myagent\nffmcp agent run \"Add a day in London\" --agent myagent  # Remembers!\n\n# Or specify thread explicitly\nffmcp agent run \"Start new topic\" --agent myagent --thread conversation2\n\n# Manage agent threads\nffmcp agent thread list myagent           # List threads for agent\nffmcp agent thread current myagent        # Show active thread\nffmcp agent thread clear myagent conv1    # Clear messages\nffmcp agent thread delete myagent conv1   # Delete thread\n```\n\n**Key Points:**\n- Agent threads are **tied to specific agents**\n- Each agent can have multiple threads\n- Each agent has its own active thread\n- Tool calls and actions are saved to the thread\n- Threads work seamlessly with agent actions (web fetch, image generation, etc.)\n\n### When to Use Threads\n\n**Use Chat Threads when:**\n- You want simple conversation history with the `chat` command\n- You're switching between different providers/models\n- You don't need agent features (actions, tools, etc.)\n- You want lightweight conversation management\n\n**Use Agent Threads when:**\n- You're using agents with actions and tools\n- You want conversation history tied to a specific agent configuration\n- You need multiple conversation contexts per agent\n- You want to leverage agent capabilities (web search, image generation, etc.)\n\n### Thread Management Commands\n\n**Chat Threads:**\n```bash\nffmcp thread create \u003cname\u003e      # Create thread\nffmcp thread list               # List all threads\nffmcp thread use \u003cname\u003e         # Set active thread\nffmcp thread current            # Show active thread\nffmcp thread clear \u003cname\u003e       # Clear messages\nffmcp thread delete \u003cname\u003e      # Delete thread\n```\n\n**Agent Threads:**\n```bash\nffmcp agent thread create \u003cagent\u003e \u003cname\u003e    # Create thread\nffmcp agent thread list \u003cagent\u003e              # List threads\nffmcp agent thread use \u003cagent\u003e \u003cname\u003e        # Set active thread\nffmcp agent thread current \u003cagent\u003e           # Show active thread\nffmcp agent thread clear \u003cagent\u003e \u003cname\u003e      # Clear messages\nffmcp agent thread delete \u003cagent\u003e \u003cname\u003e    # Delete thread\n```\n\n### Example Workflows\n\n**Chat Thread Workflow:**\n```bash\n# Create and use a thread\nffmcp thread create project-planning\nffmcp thread use project-planning\n\n# Have a conversation\nffmcp chat \"I want to build a web app\" -p openai\nffmcp chat \"What technologies should I use?\" -p openai\nffmcp chat \"Tell me more about React\" -p openai\n\n# Switch to different thread\nffmcp thread create personal-chat\nffmcp thread use personal-chat\nffmcp chat \"What's the weather like?\" -p openai  # Fresh conversation\n```\n\n**Agent Thread Workflow:**\n```bash\n# Create agent and thread\nffmcp agent create assistant -p openai -m gpt-4o-mini -i \"You are helpful\"\nffmcp agent thread create assistant project-a\nffmcp agent thread use assistant project-a\n\n# Run agent with conversation history\nffmcp agent run \"Research React best practices\" --agent assistant\nffmcp agent run \"Find examples of React hooks\" --agent assistant  # Uses web_fetch action\n\n# Create another thread for different project\nffmcp agent thread create assistant project-b\nffmcp agent thread use assistant project-b\nffmcp agent run \"Research Python frameworks\" --agent assistant  # Fresh conversation\n```\n\n## Zep/LEANN Memory (Brains)\n\n**Note:** Brains are separate from threads. Threads maintain conversation history locally, while Brains provide advanced memory features including semantic search, document storage, and graph relationships. You can use both together - agents can have threads for conversation history AND a brain for long-term memory and document search.\n\n**Backend Options:**\n- **Zep**: Cloud or self-hosted memory platform (requires API key for cloud)\n- **LEANN**: Local vector index with 97% storage savings, runs entirely on your server (no API key needed)\n\n### Setup\n\n#### Zep Setup (Cloud or Self-Hosted)\n\n```bash\n# Configure Zep (Cloud)\nexport ZEP_CLOUD_API_KEY=your_key\n\n# Optional for self-hosted\nexport ZEP_BASE_URL=http://localhost:8000\n\n# Or persist settings\nffmcp config -p zep -k YOUR_ZEP_API_KEY\n```\n\n#### LEANN Setup (Local, No API Key Required)\n\n```bash\n# First, install LEANN separately (requires system dependencies)\n# LEANN is optional and not included in default installation\npip install leann\n\n# Or install ffmcp with LEANN support\npip install ffmcp[leann]\n\n# LEANN works out of the box - no API key needed!\n# Optional: Configure index directory (defaults to ~/.ffmcp/leann_indexes)\nexport LEANN_INDEX_DIR=/path/to/indexes\n\n# Or persist settings\nffmcp config set-leann-index-dir /path/to/indexes\n```\n\n**Note:** LEANN requires `leann-backend-hnsw` which may need system dependencies. If installation fails, you can still use Zep backend without LEANN.\n\n### Brains\n\n```bash\n# Create a Zep brain (default)\nffmcp brain create my-zep-brain --backend zep\n\n# Create a LEANN brain (local, no API key needed)\nffmcp brain create my-leann-brain --backend leann\n\n# Create with default session ID\nffmcp brain create mybrain --session-id session-123\n\n# List all brains (shows backend type)\nffmcp brain list\n# Output: my-zep-brain (zep) *\n#         my-leann-brain (leann)\n\n# Use a brain\nffmcp brain use mybrain\nffmcp brain current\n```\n\n### Memory\n\nMemory operations work identically for both Zep and LEANN backends:\n\n```bash\n# Add a message to memory\nffmcp brain memory add --role user --role-type user --content \"Who was Octavia Butler?\"\n\n# Get memory context\nffmcp brain memory get\n\n# Get memory for a specific brain and session\nffmcp brain memory get --brain mybrain --session session-123\n\n# Search memory\nffmcp brain memory search \"Octavia\"\n\n# Clear memory for session\nffmcp brain memory clear\n```\n\nNotes:\n- Omitting `--brain` uses the active brain (set with `ffmcp brain use`).\n- Omitting `--session` defaults to the brain's `default_session_id` (if set) or the brain name.\n- Both Zep and LEANN support the same memory operations.\n\n### Collections \u0026 Documents\n\nCollection and document operations work identically for both backends:\n\n```bash\n# Create a namespaced collection under the brain\nffmcp brain collection create knowledge --description \"KB for mybrain\"\n\n# Add a document\nffmcp brain document add knowledge --text \"Zep is a memory platform for LLM apps\" --id doc1\n\n# Search documents\nffmcp brain document search knowledge \"memory platform\"\n```\n\n### Graph (Zep Cloud Only)\n\nGraph operations are only available with Zep Cloud backend:\n\n```bash\n# Add JSON data to user graph\necho '{\"projects\": {\"alpha\": {\"status\": \"in progress\"}}}' | \\\n  ffmcp brain graph add user-123 --type json --input -\n\n# Get user graph\nffmcp brain graph get user-123\n```\n\n**Note:** Graph API is not available in LEANN backend. Use Zep Cloud backend for graph operations.\n\n### LEANN-Specific Operations\n\nLEANN provides additional direct index management commands:\n\n```bash\n# Build a LEANN index directly from files/directories\nffmcp brain leann build my-index ./documents/ --backend hnsw\n\n# List all LEANN indexes\nffmcp brain leann list\n\n# Search a LEANN index directly\nffmcp brain leann search my-index \"query text\" --top-k 10\n\n# Remove a LEANN index\nffmcp brain leann remove my-index --force\n```\n\n### Choosing Between Zep and LEANN\n\n**Use Zep when:**\n- You need graph relationships\n- You want cloud-hosted memory\n- You need real-time collaboration features\n- You have a Zep Cloud API key\n\n**Use LEANN when:**\n- You want 100% local/private storage (no API key needed)\n- You need maximum storage efficiency (97% savings)\n- You're running on your own server\n- You want to avoid external dependencies\n- You don't need graph features\n\n**Both backends support:**\n- Memory operations (add, get, search, clear)\n- Collections and documents\n- Semantic search\n- Metadata filtering\n- Session management\n\n## Usage Examples\n\n### Basic Text Generation\n\n```bash\nffmcp generate \"Write a Python function to calculate fibonacci\"\n```\n\n### Advanced Options\n\n```bash\nffmcp generate \"Creative story\" \\\n  -p openai \\\n  -m gpt-4 \\\n  -t 0.9 \\\n  --max-tokens 500 \\\n  -s\n```\n\n### File Processing\n\n```bash\n# Process a file\nffmcp generate -i input.txt -o output.txt\n\n# Chain operations\ncat data.txt | ffmcp generate | grep \"important\" \u003e filtered.txt\n```\n\n### Integration in Scripts\n\n```bash\n#!/bin/bash\nRESULT=$(ffmcp generate \"Translate to French: Hello world\" -p openai)\necho \"Translation: $RESULT\"\n```\n\n### Programmatic Usage (Node.js/JavaScript)\n\nIf you installed via npm, you can use ffmcp programmatically in your Node.js projects:\n\n```javascript\nconst ffmcp = require('ffmcp');\n\n// Generate text\nconst result = await ffmcp.generate('Write a haiku about coding', {\n  provider: 'openai',\n  model: 'gpt-4',\n  temperature: 0.7\n});\nconsole.log(result);\n\n// Chat with AI\nconst response = await ffmcp.chat('Hello, how are you?', {\n  provider: 'anthropic',\n  system: 'You are a helpful assistant',\n  thread: 'conversation1'\n});\nconsole.log(response);\n\n// Stream responses\nconst stream = ffmcp.streamGenerate('Tell me a story', {\n  provider: 'openai'\n});\n\nstream.on('data', (chunk) =\u003e {\n  process.stdout.write(chunk);\n});\n\nstream.on('end', () =\u003e {\n  console.log('\\nDone!');\n});\n\n// Configure API keys\nawait ffmcp.config('openai', 'your-api-key-here');\n\n// List providers\nconst providers = await ffmcp.providers();\nconsole.log(providers);\n\n// Execute raw commands\nconst output = await ffmcp.raw(['agent', 'list']);\nconsole.log(output);\n```\n\n**TypeScript Support:**\n```typescript\nimport ffmcp from 'ffmcp';\n\nconst result = await ffmcp.generate('Hello', {\n  provider: 'openai',\n  model: 'gpt-4',\n  temperature: 0.7\n});\n```\n\nSee [NPM_README.md](NPM_README.md) for complete npm package documentation.\n\n### Complete Workflow Example\n\n```bash\n# 1. Transcribe audio\nffmcp openai transcribe meeting.mp3 -o transcript.txt\n\n# 2. Summarize transcript\nffmcp generate -i transcript.txt -o summary.txt\n\n# 3. Generate image based on summary\nffmcp openai image \"$(cat summary.txt | head -c 100)\"\n\n# 4. Create embeddings for search\nffmcp openai embed \"$(cat transcript.txt)\" -o embeddings.json\n```\n\n## Supported AI Providers\n\nffmcp supports 11 major AI providers, each with their own strengths:\n\n| Provider | Models | Key Features | Best For |\n|----------|--------|-------------|----------|\n| **OpenAI** | GPT-4, GPT-3.5, DALL·E, Whisper | Full feature set (vision, images, audio, embeddings) | Comprehensive AI tasks |\n| **Anthropic** | Claude 3.5 Sonnet, Claude 3 Opus | Long context, high quality | Complex reasoning, long documents |\n| **Google Gemini** | Gemini 2.0 Flash, Gemini 1.5 Pro | Multimodal, fast | General purpose, vision tasks |\n| **Groq** | Llama 3.1, Mixtral, Gemma | Ultra-fast inference | Speed-critical applications |\n| **DeepSeek** | DeepSeek Chat, DeepSeek Coder | OpenAI-compatible, coding-focused | Code generation, technical tasks |\n| **Mistral AI** | Mistral Large, Pixtral | High quality, vision support | Enterprise applications |\n| **Together AI** | Llama, Mixtral, Qwen, many more | Access to many open-source models | Experimentation, cost-effective |\n| **Cohere** | Command R+, Command R | Enterprise features, RAG | Business applications, embeddings |\n| **Perplexity** | Sonar Large, Sonar Pro | Built-in web search, citations | Research, real-time information |\n| **AI33** | Various models | Multiple model access | General purpose |\n| **AIMLAPI** | 300+ models unified API | Single API for 300+ models, OpenAI-compatible | Access to wide variety of models |\n\n### Default Models\n\nEach provider has a sensible default model:\n- OpenAI: `gpt-4o-mini`\n- Anthropic: `claude-3-5-sonnet-20241022`\n- Gemini: `gemini-2.0-flash-exp`\n- Groq: `llama-3.1-70b-versatile`\n- DeepSeek: `deepseek-chat`\n- Mistral: `mistral-large-latest`\n- Together: `meta-llama/Llama-3-70b-chat-hf`\n- Cohere: `command-r-plus`\n- Perplexity: `llama-3.1-sonar-large-128k-online`\n- AI33: (varies by model)\n- AIMLAPI: `gpt-4o`\n\nYou can override defaults with the `-m` flag or set a custom default:\n```bash\nffmcp config set-default-model gemini gemini-1.5-pro\n```\n\n## Architecture\n\n```\nffmcp/\n├── ffmcp/\n│   ├── __init__.py\n│   ├── cli.py              # Main CLI interface\n│   ├── config.py           # Configuration management\n│   ├── providers/\n│   │   ├── __init__.py\n│   │   ├── base.py         # Base provider interface\n│   │   ├── openai_provider.py      # Full OpenAI implementation\n│   │   ├── anthropic_provider.py   # Anthropic Claude\n│   │   ├── gemini_provider.py      # Google Gemini\n│   │   ├── groq_provider.py        # Groq\n│   │   ├── deepseek_provider.py    # DeepSeek\n│   │   ├── mistral_provider.py     # Mistral AI\n│   │   ├── together_provider.py   # Together AI\n│   │   ├── cohere_provider.py      # Cohere\n│   │   └── perplexity_provider.py  # Perplexity AI\n│   └── voiceover/\n│       ├── __init__.py\n│       ├── base.py         # Base TTS provider interface\n│       └── elevenlabs_provider.py   # ElevenLabs TTS implementation\n├── setup.py\n├── requirements.txt\n└── README.md\n```\n\n## OpenAI Features Supported\n\n- ✅ **Chat Completions** - GPT-4, GPT-3.5, GPT-4o models\n- ✅ **Vision** - Image understanding with GPT-4 Vision\n- ✅ **DALL·E** - Image generation (DALL·E 2 \u0026 3)\n- ✅ **Whisper** - Audio transcription and translation\n- ✅ **Text-to-Speech** - TTS-1 and TTS-1-HD models\n- ✅ **Embeddings** - Text embeddings for semantic search\n- ✅ **Function Calling** - Tools and function calling support\n- ✅ **Assistants API** - Create and manage AI assistants\n- ✅ **Streaming** - Real-time streaming for all text generation\n\n## Voiceover/TTS Features Supported\n\n- ✅ **Multiple TTS Providers** - ElevenLabs (more coming soon)\n- ✅ **Voice Configuration Management** - Create, read, update, delete voice configs\n- ✅ **Provider Voice Discovery** - List and explore available voices\n- ✅ **Agent Voice Integration** - Assign voices to agents\n- ✅ **Flexible TTS Generation** - Use saved configs or direct parameters\n- ✅ **Advanced Voice Settings** - Stability, similarity, style, speaker boost\n- ✅ **Multiple Output Formats** - MP3, PCM, and more\n\n## Adding New Providers\n\nTo add a new AI provider:\n\n1. Create a new file in `ffmcp/providers/` (e.g., `cohere_provider.py`)\n2. Inherit from `BaseProvider` and implement required methods\n3. Register it in `ffmcp/providers/__init__.py`\n\nExample:\n\n```python\nfrom ffmcp.providers.base import BaseProvider\n\nclass CohereProvider(BaseProvider):\n    def get_provider_name(self) -\u003e str:\n        return 'cohere'\n    \n    def generate(self, prompt: str, **kwargs) -\u003e str:\n        # Implementation\n        pass\n    # ... implement other methods\n```\n\n## Roadmap\n\n- [x] OpenAI full feature support\n- [x] Multiple AI providers (9 providers supported!)\n- [x] Image generation support\n- [x] Audio transcription/translation\n- [x] Voiceover/TTS system with multiple providers\n- [x] Agent voice integration\n- [x] npm package for Node.js/JavaScript users\n- [ ] Batch processing\n- [ ] Plugin system for custom providers\n- [ ] Python API for programmatic use\n- [x] Advanced features (function calling, tool use, etc.)\n- [ ] Provider-specific features (Gemini vision, Cohere RAG, etc.)\n\n## Provider Documentation\n\nFor detailed information about each provider, see [PROVIDERS.md](PROVIDERS.md) (if available) or run:\n```bash\nffmcp providers\n```\n\nFor comprehensive voiceover/TTS documentation, see [VOICEOVER.md](VOICEOVER.md).\n\nFor npm package usage and Node.js/JavaScript API documentation, see [NPM_README.md](NPM_README.md).\n\n## Contributing\n\nContributions welcome! Please feel free to submit a Pull Request.\n\n## License\n\nMIT License\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrandonhenry%2Fffmcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbrandonhenry%2Fffmcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrandonhenry%2Fffmcp/lists"}