MCP & Flutter

Model Context Protocol (MCP)

What MCP is

MCP (Model Context Protocol) is an open standard created by Anthropic for connecting LLMs (Claude, GPT, Gemini) to external data sources and tools. Think of it like USB-C for AI — a universal interface so any LLM can access any data source without custom integration code per pair.

MCP concepts

• MCP Server: exposes tools (callable functions) and resources (readable data) to LLMs
• MCP Client: the LLM-side library that discovers and calls tools/resources
• Tool: a function the LLM can invoke (e.g., get_inventory, place_order)
• Resource: data the LLM can read (e.g., store catalog, order history)
• Prompt: pre-defined prompt templates the LLM can use

SSE vs STDIO Transports

Why both transports for 6-platform support

• Android, iOS, Web: cannot spawn local processes → SSE transport (remote server)
• Windows, macOS, Linux: can spawn processes → STDIO transport for local MCP servers (e.g., file system access without internet)
• The mcp_client package abstracts this — same API regardless of transport

Internal Packages: mcp_client & llm_shared

mcp_client (Dart package)

// mcp_client package API (simplified)
class McpClient {
  final McpTransport transport; // SseTransport or StdioTransport

  McpClient({required this.transport});

  Future<void> connect() async {
    await transport.connect();
    await _initialize(); // MCP handshake: version negotiation
  }

  // Discover what tools the server exposes
  Future<List<McpTool>> listTools() async {
    final response = await _request('tools/list', {});
    return (response['tools'] as List).map(McpTool.fromJson).toList();
  }

  // Call a tool on the MCP server
  Future<McpResult> callTool(String name, Map<String, dynamic> arguments) async {
    return _request('tools/call', {'name': name, 'arguments': arguments});
  }

  // Read a resource (data)
  Future<McpResource> readResource(String uri) async {
    return _request('resources/read', {'uri': uri});
  }
}

llm_shared (Dart package)

// Unified interface: swap LLM providers without code change
abstract class LlmProvider {
  Future<LlmResponse> chat(List<LlmMessage> messages, {List<McpTool>? tools});
  Stream<String> chatStream(List<LlmMessage> messages);
}

class ClaudeProvider implements LlmProvider {
  @override
  Future<LlmResponse> chat(List<LlmMessage> messages, {List<McpTool>? tools}) {
    // Anthropic API — messages API with tool_use
  }
}

class GptProvider implements LlmProvider {
  @override
  Future<LlmResponse> chat(List<LlmMessage> messages, {List<McpTool>? tools}) {
    // OpenAI API — chat completions with function_call
  }
}

// Usage: same code works for any provider
final llm = GptProvider(); // or ClaudeProvider(), GeminiProvider()
final tools = await mcpClient.listTools();
final response = await llm.chat(messages, tools: tools);
// If LLM wants to call a tool → mcpClient.callTool(name, args)

BLoC State Management

Why BLoC over Provider or Riverpod?

• BLoC (Business Logic Component): events go in, states come out. Strictly separated. Good for complex state machines (order tracking with 7 states).
• Provider: simpler, great for small apps or dependency injection. Less strict — can lead to spaghetti in large apps.
• Riverpod: Provider evolution, compile-time safety. Good choice but BLoC was already established in the team.

// Order BLoC
class OrderBloc extends Bloc<OrderEvent, OrderState> {
  final OrderRepository orderRepository;
  final OrderWebSocketService wsService;

  OrderBloc({required this.orderRepository, required this.wsService})
      : super(OrderInitial()) {

    on<OrderSubscribeRequested>((event, emit) async {
      emit(OrderLoading());
      try {
        // Initial fetch
        final order = await orderRepository.getOrder(event.orderId);
        emit(OrderLoaded(order: order));

        // Subscribe to real-time updates
        await emit.forEach(
          wsService.orderUpdates(event.orderId),
          onData: (updatedOrder) => OrderLoaded(order: updatedOrder),
          onError: (_, __) => OrderError('Connection lost'),
        );
      } catch (e) {
        emit(OrderError(e.toString()));
      }
    });
  }
}

// States
abstract class OrderState {}
class OrderInitial extends OrderState {}
class OrderLoading extends OrderState {}
class OrderLoaded extends OrderState { final Order order; OrderLoaded({required this.order}); }
class OrderError extends OrderState { final String message; OrderError(this.message); }

go_router — Declarative Routing

final router = GoRouter(
  initialLocation: '/splash',
  redirect: (context, state) {
    final isLoggedIn = context.read<AuthBloc>().state is AuthAuthenticated;
    final isGoingToAuth = state.uri.toString().startsWith('/auth');

    if (!isLoggedIn && !isGoingToAuth) return '/auth/login';
    if (isLoggedIn && isGoingToAuth) return '/home';
    return null; // no redirect
  },
  routes: [
    GoRoute(path: '/splash', builder: (_, __) => const SplashScreen()),
    GoRoute(path: '/auth/login', builder: (_, __) => const LoginScreen()),
    GoRoute(
      path: '/orders/:orderId',
      builder: (context, state) {
        final orderId = state.pathParameters['orderId']!;
        return OrderDetailScreen(orderId: orderId);
      },
    ),
    // Deep link: zoober://orders/abc123
    // → opens OrderDetailScreen directly
  ],
);

4-App Flutter Ecosystem

Why 4 separate apps instead of one?

• Different user journeys: a customer's flow is entirely different from a rider's — shared navigation would be confusing
• Different permissions: merchants should never see customer PII; riders see only their assigned orders
• Smaller APK size: each app only bundles features relevant to that role
• Independent release cycles: merchant app can ship a catalog feature without triggering a customer app release

15+ Releases — Release Process

Semantic versioning

• MAJOR.MINOR.PATCH → e.g., 2.3.1
• MAJOR: breaking change (redesign, new auth flow)
• MINOR: new feature (add review system)
• PATCH: bug fix (fix payment timeout)
• Flutter also uses versionCode (integer, increments each release) for Play Store/App Store

Release checklist

• Bump pubspec.yaml version
• flutter build appbundle --release (Android) or flutter build ipa --release (iOS)
• Play Store: upload AAB → staged rollout (10% → 50% → 100% over 3 days)
• App Store: submit for review (1-3 day review period) → phased release (7 days)
• Monitor crash rate and ANR rate in Play Console for 24h before expanding rollout

Platform Channels

Flutter's platform channel system bridges Dart code to native Android (Kotlin) or iOS (Swift) code — used for features unavailable in Flutter's SDK:

// Flutter (Dart) side
const platform = MethodChannel('com.voltvave.zoober/biometrics');

Future<bool> authenticateWithBiometrics() async {
  try {
    final bool authenticated = await platform.invokeMethod('authenticate');
    return authenticated;
  } on PlatformException catch (e) {
    // Biometrics not available on device
    return false;
  }
}

// Android (Kotlin) side — in MainActivity.kt
MethodChannel(flutterEngine.dartExecutor.binaryMessenger, "com.voltvave.zoober/biometrics")
    .setMethodCallHandler { call, result ->
        if (call.method == "authenticate") {
            // Use BiometricPrompt API
            BiometricPrompt(this, ...).authenticate(promptInfo)
        }
    }

Used in Zoober for: biometric authentication (fingerprint/face ID), native payment SDKs (Juspay's native Android SDK for UPI intent flow), and background location tracking for riders.