flutter-mcp-chatbot

MCP Weather Chatbot

A Flutter mobile app that demonstrates the Model Context Protocol (MCP) by creating a weather chatbot that uses real AI and external APIs.

✨ Vibe-Coded Project

This project was created with vibe coding — a relaxed, flow-driven approach where creativity and intuition lead the way. No overthinking, just good energy and clean code.

Architecture

This app implements proper MCP architecture with clean, scalable code organization:

• 🎯 Clean Entry Point (main.dart): Minimal 15-line entry point
• 📱 App Configuration (app.dart): Centralized app setup and theming
• 🌤️ MCP Server (bin/weather_server.dart): Standalone server providing weather tools
• 📡 MCP Client (services/mcp_client.dart): Flutter client with stdio transport
• 🧠 LLM Integration (services/llm_service.dart): Google Gemini AI processing
• 🌦️ Weather API (services/weather_service.dart): OpenWeatherMap integration
• 🎨 Modern UI (widgets/): Modular, reusable components with animations

Key Design Principles

• 🏗️ Clean Architecture: Separation of UI, business logic, and data
• 📦 Modular Design: Barrel exports for clean imports
• 🎨 Design System: Centralized constants and theming
• ♻️ Reusable Components: Widget-based architecture
• 🚀 Scalability: Easy to extend and maintain

Features

• 🤖 Real AI Chat: Uses Google Gemini AI for natural language understanding
• 🌡️ Live Weather Data: Fetches real weather from OpenWeatherMap API
• 📡 True MCP Implementation: Proper client-server communication using MCP protocol
• 🔧 Tool Calling: AI automatically determines when and how to use weather tools
• 📱 Modern Mobile UI: Beautiful Flutter interface with smooth animations
• 🎨 Clean Architecture: Modular, scalable, and maintainable codebase
• ♻️ Reusable Components: Widget-based design system
• 🌈 Material Design 3: Modern UI following Google's latest design principles
• 🔧 Easy Configuration: Centralized constants and theming

Setup

1. Get API Keys (Free)

Gemini AI API Key

1. Visit https://aistudio.google.com/app/apikey
2. Sign up for a free account
3. Generate an API key
4. Copy the key

OpenWeatherMap API Key

1. Visit https://openweathermap.org/api
2. Sign up for a free account
3. Generate an API key
4. Copy the key

2. Secure Configuration

For enhanced security, this project uses --dart-define-from-file instead of .env files. This approach prevents API keys from being exposed in APK files when the app is built.

Create Configuration File

1. Copy the example configuration:

cp .env.json.example .env.json

2. Edit .env.json with your actual API keys:

{
  "OPENWEATHER_API_KEY": "your_openweather_api_key_here",
  "GEMINI_API_KEY": "your_gemini_api_key_here"
}

🔒 Security Note: The .env.json file is git-ignored and will not be committed to version control. This approach ensures your API keys are more secure than using traditional .env files.

🔒 Security Features

This project implements secure API key management using Flutter's --dart-define-from-file feature:

Why This Approach is More Secure

• 📱 APK Protection: API keys are not embedded in the compiled APK file
• 🔍 No Asset Exposure: Keys are not stored in the assets/ folder where they can be extracted
• ⚙️ Compile-time Injection: Keys are injected during compilation, not at runtime
• 🚫 Git Safety: Configuration files are properly git-ignored
• 🔧 Environment Separation: Easy to maintain different keys for different environments

Traditional .env vs. --dart-define-from-file

Method	Security Level	APK Exposure	Extraction Risk
.env in assets	⚠️ Low	✅ Exposed	⚠️ High
--dart-define-from-file	✅ High	❌ Protected	✅ Low

VS Code Integration

The project includes preconfigured launch settings in .vscode/launch.json that automatically use the secure configuration:

• Debug, Release, and Profile configurations
• Automatic --dart-define-from-file=.env.json injection
• No manual command-line arguments needed

3. Install Dependencies

flutter pub get

4. Run the App

Using VS Code

If you're using VS Code, the project includes launch configurations that automatically use the secure environment setup. Just press F5 or use the Debug panel.

Using Command Line

flutter run --dart-define-from-file=.env.json

Building for Production

# Debug build
flutter build apk --dart-define-from-file=.env.json

# Release build  
flutter build apk --release --dart-define-from-file=.env.json

How It Works

MCP Flow

1. User sends message → Flutter UI
2. LLM analyzes message → Gemini AI determines if weather tools needed
3. Tool calling → MCP Client calls weather server via stdio transport
4. Weather data fetched → MCP Server calls OpenWeatherMap API
5. Response generated → LLM creates natural language response
6. Display result → Flutter UI shows the conversation

Example Conversation

User: "What's the weather in London?"

AI: I'll check the current weather in London for you...

[MCP Tool Call: get-current-weather with params: {city: "London"}]

AI: Here's the current weather information I found:

Current Weather in London, GB:
🌡️ Temperature: 15°C (feels like 13°C)
🌤️ Condition: Clouds - overcast clouds
💧 Humidity: 82%
🌬️ Wind: 3.6 m/s
🔽 Pressure: 1008 hPa

Is there anything else you'd like to know about the weather?

Demo Mode

The app works in demo mode even without API keys:

• Without Gemini API: Uses pattern-matching for responses
• Without Weather API: Shows demo weather data
• Full MCP: Still demonstrates proper MCP client-server communication

Project Structure

lib/
├── main.dart                    # 🎯 Clean entry point (15 lines!)
├── app.dart                     # 📱 App configuration
├── config/                      # ⚙️ Configuration & constants
│   ├── app_constants.dart       # 🔧 Colors, dimensions, strings
│   └── app_theme.dart          # 🎨 Material Design theme
├── models/                      # 📊 Data models
│   ├── chat_message.dart        # 💬 Chat message structure
│   ├── weather_data.dart        # 🌡️ Weather data model
│   └── models.dart             # 📦 Barrel exports
├── screens/                     # 📱 Screen widgets
│   └── chat_screen.dart        # 💬 Main chat interface
├── services/                    # 🔧 Business logic & APIs
│   ├── chat_service.dart        # 🤖 Chat coordination
│   ├── llm_service.dart         # 🧠 AI integration
│   ├── mcp_client.dart          # 📡 MCP client
│   ├── mcp_weather_server.dart  # 🌤️ MCP server
│   ├── weather_service.dart     # 🌦️ Weather API
│   └── services.dart           # 📦 Barrel exports
└── widgets/                     # 🧩 Reusable UI components
    ├── chat/                   # 💬 Chat-specific widgets
    │   ├── animated_message_bubble.dart
    │   ├── animated_send_button.dart
    │   └── typing_indicator.dart
    ├── ui/                     # 🎨 General UI widgets
    │   ├── chat_app_bar.dart
    │   ├── chat_input_area.dart
    │   ├── chat_loading_indicator.dart
    │   ├── chat_messages_list.dart
    │   └── weather_widget.dart
    └── widgets.dart            # 📦 Barrel exports

bin/
└── weather_server.dart          # 🌤️ Standalone MCP server

docs/                           # 📚 Comprehensive documentation
├── getting-started.md
├── architecture.md
├── code-structure.md
├── api-integration.md
├── mcp-guide.md
└── overview.md

MCP Protocol Details

This implementation demonstrates:

• Proper initialization: Client-server handshake via MCP protocol
• Tool discovery: Client lists available tools from server
• Tool execution: Client calls tools with parameters, server executes and returns results
• Error handling: Proper MCP error responses and fallbacks
• Transport layer: Uses stdio transport for local communication

Technologies Used

• Flutter: Mobile UI framework
• MCP Dart: Official Dart implementation of Model Context Protocol
• Google Gemini: Free AI inference API
• OpenWeatherMap: Free weather data API
• HTTP: For API communications

Documentation

📚 Comprehensive documentation available in the docs/ folder:

• Getting Started Guide - Setup and installation
• Architecture Guide - How everything works together
• Code Structure Guide - Clean architecture and code organization
• API Integration Guide - Working with external APIs
• MCP Guide - Understanding Model Context Protocol
• Project Overview - High-level project explanation

Troubleshooting

MCP Server Issues

• Ensure dart run bin/weather_server.dart works standalone
• Check environment variables are properly set

API Issues

• Verify API keys are correct in .env file
• Check internet connection for API calls
• Review API quotas (both services offer generous free tiers)

Flutter Issues

• Run flutter doctor to check Flutter setup
• Try flutter clean && flutter pub get

License

MIT License - Feel free to use this as a learning resource or starting point for your own MCP applications!