synaptic-flow

🚀 SynapticFlow - AI Agent Platform for Everyone

📋 Project Overview

SynapticFlow: Making MCP Tool Integration Accessible to All Users

SynapticFlow is a desktop AI agent platform designed to solve two critical problems in the AI ecosystem:

1. Accessibility Gap: MCP (Model Context Protocol) tools are powerful but primarily accessible to developers. We make these tools available to general users through an intuitive interface.

2. LLM Provider Lock-in: Users shouldn't be restricted to a few major LLM providers. SynapticFlow provides freedom to choose from multiple providers, including increasingly powerful local LLMs.

🎯 What Problems We Solve

🔧 MCP Tool Integration Made Simple

• Problem: MCP tools require technical setup and command-line knowledge
• Solution: Built-in tools and easy MCP server management with GUI
• Benefit: Anyone can use powerful tools without technical barriers

🔓 Freedom from LLM Vendor Lock-in

• Problem: Most AI platforms tie users to specific LLM providers
• Solution: Support for multiple providers (OpenAI, Anthropic, Groq, local models, etc.)
• Benefit: Choose the best model for your needs and budget

🤖 Personalized AI Agents

• Problem: Generic AI assistants don't fit specific workflows
• Solution: Create custom agents with unique personalities and tool access
• Benefit: AI that works exactly how you want it to

🛠 What We Provide

✅ Comprehensive Built-in Tool Ecosystem

🛡️ Secure File Management:

• SecureFileManager: Advanced path validation and sandboxed operations
• Content Store: Upload, index, and full-text search across PDF, DOCX, XLSX files
• File Attachments: Smart MIME type handling with preview capabilities
• Document Processing: Extract and analyze content from multiple formats

⚡ Code Execution & Development:

• Python Sandbox: Secure code execution with real-time result capture
• TypeScript Runtime: JavaScript/TypeScript evaluation environment
• Output Management: Comprehensive execution logging and error handling
• Development Tools: Built-in debugging and testing utilities

🌐 Browser Automation:

• Interactive Browser Server: Automated web interactions and scraping
• Session Management: Persistent browser sessions with state management
• Content Extraction: Clean markdown conversion from web pages
• Web Integration: Seamless web data processing pipeline

🔗 Advanced MCP Integration:

• Dual Backend Support: Both Rust Tauri and Web Worker implementations
• Security Validation: Built-in SecurityValidator with comprehensive protection
• Tool Execution Context: Unified calling interface across all backends
• Error Normalization: Robust error handling and reporting system

✅ Advanced Multi-LLM Ecosystem

8 Major Providers, 50+ Models:

• 🤖 OpenAI: GPT-4.1 series, o3/o4-mini reasoning models, GPT-4o variants
• 🧠 Anthropic: Claude 4 Opus/Sonnet, Claude 3.5 series with advanced tool calling
• 🚀 Google: Gemini 2.5 Pro/Flash (2M context), Gemini 2.0 agentic models
• ⚡ Groq: Llama 3.3 70B, DeepSeek R1 Distill, Qwen3 32B reasoning (1,800+ tokens/sec)
• 🔥 Fireworks: DeepSeek R1, Qwen3 235B MoE, Llama 4 Maverick/Scout
• 🧠 Cerebras: Ultra-fast inference with industry-leading speed
• 🏠 Ollama: Local models with zero cost (Llama, Mistral, Qwen, CodeLlama)
• 🎯 Empty: Custom provider configurations

Advanced Features:

• 🤔 Reasoning Models: o3, DeepSeek R1, Qwen3 thinking models for complex problem-solving
• 💰 Cost Optimization: Real-time cost tracking and model comparison
• 📚 Massive Context: Up to 2M tokens (Gemini 2.5 Pro)
• 👁️ Multimodal: Vision, document processing, and code understanding

✅ User-Friendly Features

• 🤖 Custom Agents: Create AI assistants with specific roles and tool access
• 👥 Multi-Agent Collaboration: Multiple agents working together on complex tasks
• 💬 Session Management: Organize conversations with file attachments and context
• 📤 Export/Import: Share agent configurations and setups with others
• 🎨 Modern UI: Clean, terminal-style interface that's both powerful and intuitive

🛠 Advanced Technology Stack

Core Framework:

• Tauri 2.x: Latest cross-platform framework with enhanced security and performance
• React 18.3: Modern UI with concurrent features and advanced hooks
• TypeScript 5.6: Latest language features with strict type safety
• RMCP 0.2.1: Rust-based Model Context Protocol with child process transport

Backend Technologies:

• Rust: High-performance native operations with async/await architecture
• Tokio: Advanced async runtime for concurrent MCP server management
• SecurityValidator: Built-in path validation and process sandboxing
• Warp: HTTP server infrastructure for browser automation capabilities

Frontend Technologies:

• Tailwind CSS 4.x: Latest utility-first styling with performance optimizations
• Radix UI: Accessible component primitives for robust UI
• Dexie: TypeScript-friendly IndexedDB wrapper for local data
• Zustand: Lightweight, scalable state management solution

🛡️ Security & Performance

Built-in Security:

• SecurityValidator: Advanced path traversal protection and sandboxed operations
• MIME Type Validation: Safe file handling across all supported formats
• Process Isolation: MCP servers run in isolated child processes for maximum security
• API Key Management: Secure in-app credential storage with encryption
• Content Sanitization: Automatic cleaning and validation of all user inputs

Performance Optimizations:

• Streaming Responses: Real-time AI model outputs with minimal latency
• Concurrent Tool Execution: Parallel MCP server operations for faster results
• Smart Caching: Intelligent resource caching for improved response times
• Memory Management: Optimized for long-running sessions and large datasets
• Ultra-Fast Models: Cerebras integration delivering 1,800+ tokens/second

📁 Project Structure

synaptic-flow/
├── src/                        # React Frontend (Feature-Driven Architecture)
│   ├── app/                    # App entry, root layout, global providers
│   │   ├── App.tsx             # Main application component
│   │   ├── main.tsx            # React entry point
│   │   └── globals.css         # Global styles
│   ├── assets/                 # Static assets (images, svgs)
│   ├── components/             # Shared UI components (20+ shadcn/ui components)
│   │   ├── ui/                 # shadcn/ui component library
│   │   ├── layout/             # App layout components
│   │   └── common/             # Reusable common components
│   ├── features/               # Feature modules (7 major features)
│   │   ├── assistant/          # AI agent management and configuration
│   │   ├── chat/               # Real-time chat interface with tool calling
│   │   ├── group/              # Multi-agent collaboration system
│   │   ├── history/            # Conversation history and search
│   │   ├── prompts/            # Prompt management and templates
│   │   ├── session/            # Session management with file attachments
│   │   ├── settings/           # Configuration and API key management
│   │   └── tools/              # Built-in tool ecosystem and MCP integration
│   ├── context/                # React context system (8 specialized contexts)
│   │   ├── AssistantContext.tsx   # Agent state management
│   │   ├── BuiltInToolContext.tsx # Tool execution context
│   │   ├── MCPServerContext.tsx   # MCP server management
│   │   └── ...                   # Additional contexts
│   ├── hooks/                  # Custom React hooks
│   │   ├── use-rust-backend.ts    # Tauri backend integration
│   │   ├── use-mcp-server.ts      # MCP server management
│   │   └── ...                   # Feature-specific hooks
│   ├── lib/                    # Service layer and business logic
│   │   ├── ai-service.ts          # LLM provider integration
│   │   ├── logger.ts              # Centralized logging system
│   │   ├── secure-file-manager.ts # Advanced file operations
│   │   ├── rust-backend-client.ts # Backend communication layer
│   │   └── ...                   # Additional services
│   ├── models/                 # TypeScript type definitions
│   │   ├── chat.ts               # Chat and message types
│   │   ├── mcp-types.ts          # MCP protocol types (680+ lines)
│   │   └── llm-config.ts         # LLM configuration types
│   └── config/                 # Configuration files
│       └── llm-providers.json    # LLM provider definitions
├── src-tauri/                 # Rust Backend (Advanced Architecture)
│   ├── src/
│   │   ├── lib.rs                 # Main Tauri application
│   │   ├── mcp/                   # MCP server integration modules
│   │   ├── security/              # Security validation and sandboxing
│   │   ├── tools/                 # Built-in tool implementations
│   │   └── commands/              # Tauri command definitions
│   ├── Cargo.toml             # Rust dependencies
│   └── tauri.conf.json        # Tauri 2.x configuration
├── docs/                      # Documentation and guides
│   └── history/               # Refactoring and change history
├── package.json               # Node.js dependencies and scripts
├── tailwind.config.js         # Tailwind CSS 4.x configuration
└── vite.config.ts             # Vite build configuration

🚀 Getting Started

Ready to use SynapticFlow? Here's how to get up and running:

Option 1: Download Release (Recommended)

Visit our Releases page to download the latest version for your operating system.

Option 2: Build from Source

1. Prerequisites: Ensure you have Rust, Node.js (v18+), and pnpm installed.

2. Install Dependencies:

   pnpm install
   

3. Development Commands:

   # Development
   pnpm tauri dev              # Start development server with hot reload
   pnpm dev                    # Frontend-only development mode
   
   # Code Quality
   pnpm lint                   # ESLint checking with strict rules
   pnpm lint:fix              # Auto-fix lint issues
   pnpm format                # Prettier formatting
   pnpm format:check          # Check formatting compliance
   
   # Testing & Building
   pnpm test                  # Run comprehensive test suite
   pnpm build                 # Production build optimization
   pnpm tauri build          # Create optimized desktop app bundle
   
   # Diagnostics
   pnpm diagnose             # System diagnostic for troubleshooting
   

Next Steps

1. Configure Your First LLM: Open Settings and add your preferred AI provider's API key
2. Create an Agent: Set up your first AI assistant with specific tools and personality
3. Connect MCP Tools: Add external MCP servers or use our built-in tools
4. Start Collaborating: Begin conversations with your AI agents

🔥 Performance Highlights

Speed & Efficiency:

• ⚡ Ultra-Fast Models: Cerebras delivering 1,800+ tokens/second
• 💰 Cost Optimization: 60-80% cost reduction with smart model selection
• 🚀 Concurrent Operations: Parallel tool execution for faster results
• 🤯 Massive Context: Handle up to 2M tokens in single conversations

📚 Documentation

• 📖 User Guide: Complete setup and usage instructions
• 🏗️ Architecture: Technical details for developers
• 🔧 MCP Integration: How to connect and use MCP servers
• ❓ Troubleshooting: Common issues and solutions
• 📈 Refactoring History: Detailed change logs and improvements

🤝 Contributing

We welcome contributions! Here's how you can help:

• 🐛 Report Issues: Found a bug? Open an issue
• 💡 Suggest Features: Have ideas? Share them in our discussions
• 🔧 Submit Code: Read our Contributing Guide to get started
• 📚 Improve Docs: Help make our documentation even better

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🌟 Support

If SynapticFlow helps you work more efficiently with AI tools, consider:

• ⭐ Star this repository to show your support
• 🗣️ Share with others who might find it useful
• 🐛 Report issues to help us improve
• 💬 Join discussions to shape the future of the project

---

Ready to experience the most advanced AI agent platform? SynapticFlow combines enterprise-grade security, lightning-fast performance, and unlimited LLM freedom in one powerful desktop application! 🚀

Download SynapticFlow | View Source | Join Community