Flutter MCP Toolkit Architecture

July 4, 2026 · View on GitHub

This document is written for contributors and agents who need to decide which layer to change.

Ownership Boundary

mcp_flutter owns Flutter-specific VM/service-extension adapters, fmt_* tools, CLI/MCP runtime proof, plugin skills, and consumer gates.

IntentCall owns reusable agent intent architecture, registry/session semantics, schema policy, platform projection, and publish strategy. If a change is about canonical AgentRegistry, AgentResult, session lifecycle, platform emitters, or intentcall_* package behavior, make it in the IntentCall repository and dogfood the hosted or overridden package here.

Product Layers

AI client / terminal
  |
  | MCP stdio: flutter-mcp-toolkit-server
  | CLI:      flutter-mcp-toolkit / fmtk
  v
mcp_server_dart
  - connection discovery, doctor, validate-runtime
  - default locked fmt_* tool surface
  - dynamic registry bridge
  - Flutter session adapter
  |
  | Dart VM Service + DTD events
  v
Flutter app in debug mode
  - package:mcp_toolkit
  - VM service extensions
  - semantic snapshots, gestures, screenshots, logs
  - app-owned AgentCallEntry tools/resources

Packages

Package / directory	Role
`mcp_toolkit/`	Flutter app package: debug-only bootstrap, service extensions, dynamic entry registration, permission bridge.
`mcp_server_dart/`	CLI and MCP server: connection management, command catalog, `fmt_*` tools, runtime validation, dynamic registry bridge.
`packages/core/`	Pure Dart command/result/schema vocabulary shared by CLI/server/tooling.
`packages/server_capability_kernel/`	Capability host contracts.
`packages/server_capability_core/`	Server-side implementation of the Flutter MCP `fmt_*` capability.
`plugin/`	Shippable Cursor/Codex/Claude plugin assets and skills.
`flutter_test_app/`	Dogfood app and consumer proof target, not a minimal adopter example.

When To Use Which Surface

Need	Use
Add Flutter MCP to an app	`mcp_toolkit` plus `MCPToolkitBinding.instance.bootstrapFlutter(...)`.
Run deterministic checks or CI-ish proof	`flutter-mcp-toolkit` / `fmtk` CLI.
Let an assistant inspect or drive the app	`flutter-mcp-toolkit-server` with MCP `fmt_*` tools.
Expose app-specific state/actions	`AgentCallEntry.tool` / `.resource` from app code, discovered by dynamic registry tools.
Change schema/session/registry/platform behavior	IntentCall repository, then update hosted dependency consumption here.
Validate local repo changes	`steward probe --json --profile quick`, then `make check-contracts`.

Runtime Flow

A Flutter app runs in debug mode with mcp_toolkit initialized.
The CLI or MCP server discovers a VM service target.
Static commands call toolkit VM service extensions.
App-owned dynamic entries are posted through DTD events and discovered by the server.
Agents call static fmt_* tools directly, or dynamic entries through fmt_list_client_tools_and_resources, fmt_client_tool, and fmt_client_resource when dynamic bridging is enabled.

Dynamic Registry Rules

Register app-specific entries once at bootstrap, preferably through bootstrapFlutter(additionalEntries: ..., runApp: ...).
Use resources for read-only idempotent state and tools for actions or parameterized operations.
Keep schemas strict and payloads compact.
Hot restart after adding or removing dynamic entries.
Change Flutter discovery/bridge behavior here; change canonical registry, session, schema, or platform semantics upstream in IntentCall.

Proof Gates

Claim	Gate
Repo contracts and generated skill assets are coherent	`make check-contracts`
Quick low-risk repo health	`steward probe --json --profile quick`
Hosted IntentCall consumer state is clean	`make check-intentcall-hosted-consumer`
Local sibling IntentCall checkout matrix	`make check-intentcall-sibling-matrix`
Live Flutter runtime target is usable	`flutter-mcp-toolkit validate-runtime`
Skill edits are embedded	`make sync-skills`