Skip to content

llm_install.md

Latest commit

 

History

History
323 lines (244 loc) · 11.8 KB

llm_install.md

File metadata and controls

323 lines (244 loc) · 11.8 KB

LLM Installation Guide: MCP Flutter Inspector

0. AI Agent Instructions

Attention AI Agent: This guide outlines the process for installing the MCP Flutter Inspector server. Your primary role is to:

  1. Gather Information: First, you must interact with the USER to obtain specific paths and preferences.
  2. Execute Steps: Once all necessary information is gathered, proceed with the installation steps precisely as described, substituting placeholders with user-provided values.
  3. Verify: Confirm with the USER that the installation was successful.

Do not proceed with cloning or modification steps until you have confirmed the necessary paths with the USER.

Overview

This guide provides step-by-step instructions for AI agents to install and configure the MCP Flutter Inspector server by cloning from GitHub. This tool enables AI assistants to inspect and interact with Flutter applications during development.

Prerequisites

Before starting the installation, ensure the following requirements are met:

  • Flutter SDK: Installed and configured (includes Dart SDK)
  • Flutter App: Running in debug mode (the USER will specify which app).
  • AI Assistant: Cursor, Claude, Cline AI, Windsurf, RooCode, or any MCP-compatible tool
  • Git: For cloning the repository

Installation Steps

1. Gather User Information (AI Agent Action)

AI Agent: Before proceeding, you must ask the USER the following:

  1. "Where on your system should I clone the mcp_flutter repository? Please provide the absolute path to the directory where you keep your MCP server projects." (Let's call this [MCP_SERVER_BASE_PATH])
  2. "Which Flutter application project should I configure for use with the MCP Flutter Inspector? Please provide the absolute path to this Flutter project." (Let's call this [FLUTTER_APP_PATH])

Do not proceed until you have these paths from the USER.

2. Clone the Repository

AI Agent: Use the [MCP_SERVER_BASE_PATH] provided by the USER.

cd [MCP_SERVER_BASE_PATH]
git clone https://github.com/Arenukvern/mcp_flutter
cd mcp_flutter # This will be [MCP_SERVER_BASE_PATH]/mcp_flutter

Let [CLONED_MCP_FLUTTER_PATH] be [MCP_SERVER_BASE_PATH]/mcp_flutter.

3. Install and Build Dependencies

AI Agent: Execute this within [CLONED_MCP_FLUTTER_PATH].

make install

This command will:

  • Install all necessary Dart dependencies from pubspec.yaml
  • Build the MCP server automatically
  • Create the executable at mcp_server_dart/build/flutter_inspector_mcp

4. Add MCP Toolkit to the User's Flutter App

AI Agent: Use the [FLUTTER_APP_PATH] provided by the USER.

cd [FLUTTER_APP_PATH]
flutter pub add mcp_toolkit

Alternatively, if the USER prefers, instruct them to manually add to their pubspec.yaml within [FLUTTER_APP_PATH]:

dependencies:
  flutter:
    sdk: flutter
  # ... other dependencies
  mcp_toolkit: ^0.4.0

Then, AI Agent, run the following within [FLUTTER_APP_PATH]:

flutter pub get

5. Initialize MCP Toolkit in the User's Flutter App

AI Agent: Instruct the USER to update their Flutter app's main.dart file located at [FLUTTER_APP_PATH]/lib/main.dart:

import \'package:flutter/material.dart\';
import \'package:mcp_toolkit/mcp_toolkit.dart\';
import \'dart:async\';

Future<void> main() async {
  runZonedGuarded(
    () async {
      WidgetsFlutterBinding.ensureInitialized();
      MCPToolkitBinding.instance
        ..initialize() // Initializes the Toolkit
        ..initializeFlutterToolkit(); // Adds Flutter related methods to the MCP server
      runApp(const MyApp()); // Ensure MyApp is their actual root widget
    },
    (error, stack) {
      // Critical: Handle zone errors for MCP server error reporting
      MCPToolkitBinding.instance.handleZoneError(error, stack);
    },
  );
}

// ... rest of their app code

AI Agent: Remind the USER to replace const MyApp() with their actual root widget if it's different.

6. Start Flutter App with Required Flags

AI Agent: Instruct the USER to start their Flutter application (located at [FLUTTER_APP_PATH]) with the following command:

flutter run --debug --host-vmservice-port=8182 --dds-port=8181 --enable-vm-service --disable-service-auth-codes

Note to USER (Relay this): The --disable-service-auth-codes flag is currently required as a security workaround.

7. Configure Your AI Tool

AI Agent: Ask the USER which AI assistant they are using (Cursor, Cline AI, Claude Desktop, etc.). Based on their answer, provide the corresponding configuration. Use [CLONED_MCP_FLUTTER_PATH] for the path to the server.

For Cline AI

  1. AI Agent: Instruct the USER that the configuration for MCP servers with Cline AI is typically managed in a file named cline_mcp_servers.json located in a specific user configuration directory. The exact path might be ~/Library/Application Support/[Cursor | VSCode or other IDE]/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json on macOS (as per the USER's OS). The USER should verify the correct path for their Cline AI installation or consult more detailed Cline documentation.

    The settings file may have other MCP servers already configured, so you would read it first and then add your new server to the existing mcpServers object.

{
  "mcpServers": {
    "flutter-inspector": {
      "command": "[CLONED_MCP_FLUTTER_PATH]/mcp_server_dart/build/flutter_inspector_mcp",
      "args": [
        "--dart-vm-host=localhost",
        "--dart-vm-port=8181",
        "--resources",
        "--images",
        "--dynamics"
      ],
      "env": {},
      "disabled": false,
      "autoApprove": []
    }
  }
}
  1. AI Agent: Instruct the USER to restart Cline.
  2. Flutter inspector tools will be automatically available.

For Cursor

⚠️ Important (Relay to USER): Cursor doesn't support resources well, so use --no-resources.

  1. AI Agent: Instruct the USER that the configuration for MCP servers with Cursor AI is typically managed in a file named ~/.cursor/mcp.json.

    The settings file may have other MCP servers already configured, so you would read it first and then add your new server to the existing mcpServers object.

{
  "mcpServers": {
    "flutter-inspector": {
      "command": "[CLONED_MCP_FLUTTER_PATH]/mcp_server_dart/build/flutter_inspector_mcp",
      "args": [
        "--dart-vm-host=localhost",
        "--dart-vm-port=8181",
        "--no-resources",
        "--images",
        "--dynamics"
      ],
      "env": {},
      "disabled": false
    }
  }
}
  1. AI Agent: Instruct the USER to restart Cursor.
  2. Open Agent Panel (Cmd+L on macOS).
  3. Test with commands like "List all available tools from my Flutter app" or "Take a screenshot of my app".

For Claude Desktop

  1. AI Agent: Instruct the USER to add to their Claude configuration file (e.g., ~/Library/Application Support/Claude/claude_desktop_config.json on macOS; confirm path with user if different):
{
  "mcpServers": {
    "flutter-inspector": {
      "command": "[CLONED_MCP_FLUTTER_PATH]/mcp_server_dart/build/flutter_inspector_mcp",
      "args": [
        "--dart-vm-host=localhost",
        "--dart-vm-port=8181",
        "--resources",
        "--images",
        "--dynamics"
      ],
      "env": {},
      "disabled": false
    }
  }
}
  1. AI Agent: Instruct the USER to restart Claude Desktop.
  2. Flutter inspector tools will be automatically available.

Dynamic Tools Registration

AI Agent: Inform the USER about the new dynamic tools registration feature:

What is Dynamic Tools Registration?

The v2.2.0 release introduces the ability for Flutter apps to register custom tools and resources at runtime. This means:

  • Tools can be added while the app is running. However MCP Server may need to be restarted to see the new tools.
  • Hot Reload Support: Tools update automatically during development
  • Custom Functionality: Apps can expose app-specific debugging and inspection tools

Basic Example for the USER

AI Agent: Show the USER how to register a custom tool in their Flutter app:

// Add this to your Flutter app after MCPToolkitBinding initialization
final customTool = MCPCallEntry.tool(
  handler: (request) {
    final name = request['name'] ?? 'World';
    return MCPCallResult(
      message: 'Hello, $name!',
      parameters: {'greeting': 'Hello, $name!'},
    );
  },
  definition: MCPToolDefinition(
    name: 'say_hello',
    description: 'Say hello to someone',
    inputSchema: {
      'type': 'object',
      'properties': {
        'name': {
          'type': 'string',
          'description': 'Name to greet',
        },
      },
    },
  ),
);

// Register the tool
await MCPToolkitBinding.instance.addEntries(entries: {customTool});

Using Dynamic Tools

AI Agent: Explain to the USER how to use dynamic tools:

  1. Discover Tools: Use listClientToolsAndResources to see all available tools
  2. Execute Tools: Use runClientTool with the tool name and parameters
  3. Hot Reload: Tools update automatically when you hot reload your Flutter app

Verification

AI Agent: To verify with the USER that the installation is successful:

  1. Confirm their Flutter app (from [FLUTTER_APP_PATH]) is running with the specified flags.
  2. Confirm their AI assistant has been restarted after configuration.
  3. Ask them to try commands like:
    • "List all available tools from my Flutter app"
    • "Take a screenshot of the app"
    • "Get runtime errors"

Important Notes for the USER (Relay these)

  • Path Configuration: Ensure all paths like [CLONED_MCP_FLUTTER_PATH] and [FLUTTER_APP_PATH] were correctly substituted with your actual absolute paths.
  • Security: The --disable-service-auth-codes flag is a temporary workaround.
  • Debug Mode: The Flutter app must be running in debug mode for the inspector to work.
  • Port Configuration: Default ports used by the Flutter app are 8182 (VM service) and 8181 (DDS).
  • Dynamic Tools: The --dynamics flag enables dynamic tools registration support.

Troubleshooting (AI Agent: Use this to help USER)

  • Connection Issues:
    • Verify Flutter app is running with correct flags and ports (--host-vmservice-port=8182 --dds-port=8181).
    • Check AI tool's MCP server configuration for correct command and arguments.
  • MCP Server Not Found:
    • Double-check that [CLONED_MCP_FLUTTER_PATH]/mcp_server_dart/build/flutter_inspector_mcp is the correct and absolute path to the built server executable.
    • Ensure make install in Step 3 completed successfully and created the build directory.
  • Permission Errors:
    • Check file permissions for [CLONED_MCP_FLUTTER_PATH] and its subdirectories.
    • Ensure the flutter_inspector_mcp executable has execute permissions.
  • Tool Not Available in AI Assistant:
    • Ensure the AI assistant was restarted after its MCP configuration was updated.
    • Verify the disabled: false flag in the MCP server configuration for the AI tool.
  • Dynamic Tools Not Appearing:
    • Ensure mcp_toolkit package is properly initialized in your Flutter app.
    • Check that tools are registered using MCPToolkitBinding.instance.addEntries().
    • Use listClientToolsAndResources to verify registration.
    • Hot reload your Flutter app after adding new tools.

Command Line Options Reference

The Dart-based MCP server supports the following command-line options:

  • --dart-vm-host: Host for Dart VM connection (default: localhost)
  • --dart-vm-port: Port for Dart VM connection (default: 8181)
  • --resources: Enable resources support (default: true)
  • --no-resources: Disable resources support (useful for Cursor)
  • --images: Enable images support (default: true)
  • --dumps: Enable dumps support (default: false)
  • --dynamics: Enable dynamic tools registration (default: true)
  • --log-level: Logging level (default: info)
  • --environment: Environment (default: production)