A modern, feature-rich Android chat application built with Jetpack Compose and Kotlin, inspired by HuggingFace's chat-ui web application. This app provides a native Android experience for interacting with various AI language models through the HuggingFace Router API. with Kotlin, Jetpack Compose, and modern Android architecture.

• 💬 Chat Interface - Beautiful, modern chat UI with message bubbles
• 🤖 114+ AI Models - Access to HuggingFace models via Router API
• 🎯 Smart Routing - Omni router automatically selects the best model
• 📁 File Attachments - Send images and documents (UI complete)
• 🖼️ Image Generation - Generate images with FLUX models
• 🎨 5 Themes - Light, Dark, Stone, Red, Indigo
• 💾 Firebase Persistence - All data saved to Firebase Realtime Database
• ☁️ Cloudinary Integration - Image uploads and optimization
• ⚙️ Settings - Comprehensive settings screen
• 🔄 Conversation Management - Create, delete, and manage chats
• 🔧 MCP Tools - Model Context Protocol support for external tools
• ⚡ Streaming Responses - Real-time token-by-token generation

• 📎 File Picker - Complete file attachment functionality
• 🤝 Share Conversations - Share chats as text or JSON
• 👤 Assistants - Custom AI assistants with system prompts

• Language: Kotlin
• UI: Jetpack Compose
• Architecture: MVVM (Model-View-ViewModel)
• Database: Firebase Realtime Database
• Networking: Ktor Client + Kotlinx Serialization
• Image Loading: Coil
• Cloud Storage: Cloudinary
• Coroutines: Kotlin Coroutines + Flow
• MCP: Model Context Protocol SDK

app/src/main/java/com/example/chat_ui/
├── api/                    # API clients
│   ├── ChatApiClient.kt
│   ├── ChatStreamingClient.kt
│   ├── ModelsApiClient.kt
│   ├── LlmRouter.kt
│   └── ImageGenerationClient.kt
├── config/                 # Configuration
│   └── ConfigManager.kt
├── data/                   # Data layer
│   ├── Models.kt
│   ├── cloud/
│   ├── firebase/
│   └── models/
├── mcp/                    # MCP (Model Context Protocol)
│   ├── MCPModels.kt        # Data models
│   ├── MCPClient.kt        # MCP protocol client
│   ├── MCPManager.kt       # Server management
│   └── MCPToolExecutor.kt  # Tool execution
├── ui/                     # UI layer
│   ├── components/
│   ├── screens/
│   │   ├── MCPSettingsScreen.kt
│   │   └── ...
│   └── theme/
├── utils/                  # Utilities
│   └── FileAttachmentManager.kt
├── viewmodel/              # ViewModels
│   └── ChatViewModel.kt
├── ChatApp.kt              # Main app composable
└── MainActivity.kt         # Entry point

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   User Input    │ --> │   ChatViewModel │ --> │   LLM (OpenAI)  │
└─────────────────┘     └─────────────────┘     └─────────────────┘
                                │                       │
                                │                       │ Tool Calls
                                v                       v
                        ┌─────────────────┐     ┌─────────────────┐
                        │   MCPManager    │ <-- │ MCPToolExecutor │
                        └─────────────────┘     └─────────────────┘
                                │
                                v
                        ┌─────────────────┐
                        │   MCPClient     │ --> MCP Servers
                        └─────────────────┘

How it works:

1. User sends a message
2. ChatViewModel forwards to LLM with available tools
3. LLM may request tool calls (e.g., web search)
4. MCPToolExecutor parses and routes tool calls
5. MCPManager delegates to appropriate MCPClient
6. MCPClient executes tool via MCP protocol (JSON-RPC 2.0 over SSE/HTTP)
7. Results returned to LLM for final response

• Android Studio Hedgehog or newer
• JDK 17 or newer
• Android SDK 34
• Gradle 8.0+

1. Clone the repository

git clone <repository-url>
cd chatui

1. Configure API Keys

Edit app/src/main/assets/config.properties:

# HuggingFace API
OPENAI_BASE_URL=https://router.huggingface.co/v1
OPENAI_API_KEY=hf_YOUR_TOKEN_HERE

# MongoDB
MONGODB_URL=mongodb+srv://username:[email protected]/
MONGODB_DB_NAME=chatuiKT

# Cloudinary
CLOUDINARY_CLOUD_NAME=your_cloud_name
CLOUDINARY_API_KEY=your_api_key
CLOUDINARY_API_SECRET=your_api_secret

# LLM Router
LLM_ROUTER_ARCH_BASE_URL=https://router.huggingface.co/v1
LLM_ROUTER_ARCH_MODEL=router/omni
LLM_ROUTER_FALLBACK_MODEL=Qwen/Qwen3-235B-A22B-Instruct-2507

1. Build and Run

./gradlew assembleDebug
./gradlew installDebug

Or use Android Studio's Run button.

1. Open the app
2. Type a message in the input field
3. Press send
4. The AI will respond using the selected model

1. Tap the menu icon (☰)
2. Select "Models"
3. Browse and select a model
4. Return to chat

1. Tap the menu icon (☰)
2. Select "Gallery"
3. Tap the + button
4. Enter a prompt and select a model
5. Tap "Generate"

1. Tap the menu icon (☰)
2. Select "Settings"
3. Go to "Appearance"
4. Tap a theme circle to switch

1. In chat, tap the image or file icon
2. Select a file from your device
3. The file will upload to Cloudinary
4. Send your message with the attachment

1. Go to Settings → MCP Servers
2. Enable desired servers (Hugging Face MCP is enabled by default)
3. Tap اتصال الكل (Connect All) to connect
4. Return to chat - tools are now available to the AI
5. Ask the AI to use tools (e.g., "Search the web for...")

Example prompts with tools:

• "Search the web for the latest news about AI"
• "Find information about Kotlin Compose"
• "Look up the weather in Tokyo"

The app uses HuggingFace Router API by default. You can configure:

• Base URL
• API Key
• Router settings
• Fallback models

Choose from 5 themes:

• Light - Clean white background
• Dark - Dark gray background (default)
• Stone - Warm dark gray/brown
• Red - Dark with red accents
• Indigo - Dark with indigo accents

• Default model: Omni (smart router)
• 114+ models available
• Filter by multimodal support
• Filter by tools support

Access via Settings → MCP Servers

• Add/Edit/Remove - Manage MCP servers
• Import/Export - JSON configuration
• Toggle - Enable/disable servers
• Reconnect - Retry connection
• View Tools - See available tools per server

Default Servers:

Adding Custom Servers:

{
  "name": "My MCP Server",
  "url": "https://example.com/mcp",
  "type": "SSE",
  "enabled": true,
  "headers": {
    "Authorization": "Bearer YOUR_TOKEN"
  }
}

./gradlew test

# List emulators
emulator -list-avds

# Start emulator
emulator -avd Pixel_5_API_34

# Install and run
./gradlew installDebug
adb shell am start -n com.example.chat_ui/.MainActivity

# View all logs
adb logcat

# Filter by tag
adb logcat | grep -E "ChatViewModel|ChatApiClient"

# Clear logs
adb logcat -c

• Cold start: ~1.5s
• Model loading: ~2s (114 models)
• Message send: ~500ms (without streaming)
• Image generation: ~5-10s (depends on model)
• Theme switch: Instant

• Lazy loading for model list
• Image caching with Coil
• Database queries optimized with indexes
• Coroutines for async operations
• Flow for reactive data

Error: "Unresolved reference"

./gradlew clean
./gradlew build --refresh-dependencies

Error: "Manifest merger failed"

• Check AndroidManifest.xml for conflicts
• Ensure all dependencies are compatible

Error: "Database not initialized"

• Ensure MongoDB URL is correct in config.properties
• Check internet connection

Error: "Upload failed"

• Verify Cloudinary credentials
• Check file size (<10MB)

Error: "API request failed"

• Verify HuggingFace API key
• Check internet connection
• Ensure API quota is not exceeded

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

• Follow Kotlin coding conventions
• Use meaningful variable names
• Add comments for complex logic
• Write unit tests for new features

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

• HuggingFace - For the amazing AI models and Router API
• MongoDB - For Realm database
• Cloudinary - For image hosting
• Jetpack Compose - For the modern UI toolkit

For issues, questions, or suggestions:

• Open an issue on GitHub
• Contact: [[email protected]]

• Basic chat functionality
• Model selection
• Image generation
• Theme system
• Firebase persistence
• Streaming responses
• MCP Tools integration

• File attachments
• Share conversations
• Assistants
• Voice input

• Conversation search
• Export conversations
• Multi-user support
• Offline mode

Current Version: 1.0.0
Completion: 98%
Status: Production-ready with MCP Tools support

See IMPLEMENTATION_STATUS.md for detailed feature status.
See TODO.md for implementation guide.

# 1. Clone
git clone <repo-url>
cd chatui

# 2. Configure
# Edit app/src/main/assets/config.properties

# 3. Build
./gradlew assembleDebug

# 4. Install
./gradlew installDebug

# 5. Run
adb shell am start -n com.example.chat_ui/.MainActivity

That's it! You're ready to chat with AI! 🚀