flutter-mcp-toolkit

The flutter-mcp-toolkit-control skill allows an AI agent to interact with a running Flutter application as a user would. It is used for UI automation tasks such as tapping widgets, typing text, scrolling, navigating routes, and performing hot reloads during development.

Core Capabilities:

• Interaction: Tap buttons, icons, or list items; type into fields; fill forms; and press keys (Enter, Escape, Tab, etc.).
• Navigation: Programmatically push, pop, or popUntil routes; dismiss dialogs and bottom sheets.
• Scrolling: Swipe or scroll to reveal off-screen content.
• Development Workflow: Trigger hot_reload_and_capture() to perform a hot reload followed by a screenshot, semantic snapshot, and error check in a single round-trip.

The flutter-mcp-boundary-audit skill provides a reference implementation for auditing the mcp_flutter monorepo. It maps generic security and architectural concerns to specific file paths, defines the data flow through gateways, and identifies critical validation points to prevent app isolate bypasses or schema mismatches.

Use this reference when auditing the mcp_flutter repository to ensure that all tool calls, VM service extensions, and WebMCP interactions are properly coerced and validated against their schemas before reaching the application logic.

The flutter-mcp-toolkit-inspect skill is designed for read-only state inspection of a running Flutter app. Use it to understand what is currently displayed on the screen, retrieve recent errors, list available debug targets, inspect VM metadata, and traverse the widget tree.

Important Constraints:

• Do not use this skill for driving interaction (e.g., tapping, scrolling). Use the interact skill for that.
• If no connection target is established, start by calling discover_debug_apps().
• If you need to know which widgets are on screen, start with semantic_snapshot().

The Flutter MCP Toolkit is a multi-layered product designed to allow AI agents to inspect and control debug Flutter applications. The repository contains the following core components:

• mcp_server_dart: The capability kernel/core.
• mcp_toolkit: The toolkit implementation.
• flutter-mcp-toolkit: The primary binary/CLI.
• Plugin Skills: Specialized capabilities for agent onboarding (guide, setup, inspect, control, debug, custom-tools).
• Release Binaries: Distributed via install.sh.

The Flutter MCP Toolkit is designed for Flutter-centric workflows and dynamic runtime tools, complementing the official Dart MCP server. While the official server focuses on Dart tooling, this toolkit provides:

• App-level context: Summaries of app-level errors.
• UI Inspection: Screenshots and view metadata.
• Fast Actions: Support for hot reload and hot restart.
• Customization: Ability to register app-specific tools and resources dynamically from the running app.

It consists of three main components:

1. flutter-mcp-toolkit-server: A Dart MCP server focused on Flutter workflows.
2. flutter-mcp-toolkit: A CLI for automation, snapshots, and CI.
3. mcp_toolkit: A Dart package for in-app extensions.

The toolkit exposes approximately 30 MCP tools prefixed with fmt_*. These tools are categorized into four functional areas to allow AI agents to inspect, interact with, and debug Flutter applications:

• Inspection: Semantic snapshots, viewing details, errors, screenshots, and VM information.
• Interaction: Tapping, scrolling, typing, filling forms, hot-reloading, navigating, and waiting for elements.
• Debug: Accessing recent logs and evaluating Dart expressions.
• Lifecycle: Discovering apps, hot-reloading, and hot-restarting.

For a full reference of available tools, refer to the flutter-mcp-toolkit-{guide,inspect,control,debug} skills.

The Dynamic Tool Registry allows your Flutter app to expose custom MCP (Model Context Protocol) tools and resources at runtime without requiring a rebuild of the MCP server. This enables AI assistants to interact with your app's internal state, run domain-specific debug checks, or inspect app-specific diagnostics.

When to use it:

• You need app-specific diagnostics beyond built-in tools (like get_vm or get_app_errors).
• You have repeated debugging workflows that benefit from being automated via AI.
• You need to expose internal app state or configuration in a controlled, structured format.

When NOT to use it:

• The required action is already covered by built-in tools.
• The action should run in production user builds (it is intended for debug/development).
• The handler performs risky side effects without explicit safeguards.

When the standard bundled MCP tools (like screenshot or tap) are insufficient, you can register app-specific read surfaces or actions via the dynamic registry. Choose your primitive based on the following requirements:

The toolkit provides tools through two primary interfaces: the Model Context Protocol (MCP) and the Command Line Interface (CLI). The naming convention differs depending on which interface you are using:

1. MCP (tools/call): Tools are prefixed with fmt_ (available in v3.0.0+). For example, fmt_tap_widget or fmt_hot_reload_and_capture.
2. CLI (flutter-mcp-toolkit exec --name <bare>): Tools use the bare, unprefixed form. For example, tap_widget or hot_reload_and_capture.

When configuring an AI agent via MCP, ensure you use the fmt_ prefix.

The toolkit maintains separate tools for scroll and swipe because they have different underlying behaviors. Do not attempt to use them interchangeably as a single gesture command:

• scroll: Uses semantic actions (e.g., scrollUp, scrollDown, scrollLeft, scrollRight) via SemanticsOwner.performAction.
• swipe: A synthesized finger drag consisting of a PointerDownEvent $\rightarrow$ movement $\rightarrow$ PointerUpEvent.

The intentcall functionality is being transitioned from a monorepo workspace dependency within mcp_flutter to a set of standalone, published packages. When integrating with intentcall, you should be aware of the dependency hierarchy. The publishing order is as follows:

1. intentcall_schema (Base schemas)
2. intentcall_core (Core logic and migrator logic)
3. intentcall_mcp / adapters (MCP-specific implementations)
4. intentcall_platform (Platform-specific implementations)
5. intentcall_testing (Testing utilities)

Note: While the migrator logic resides in intentcall_core, the migration CLI and fmt_migrate_agent_entries remain part of the mcp_flutter toolkit.