# Architecture

This page is for contributors and agents deciding 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

```text
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

1. A Flutter app runs in debug mode with `mcp_toolkit` initialized.
2. The CLI or MCP server discovers a VM service target.
3. Static commands call toolkit VM service extensions.
4. App-owned dynamic entries are posted through DTD events and discovered by
   the server.
5. 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` |

## Further Reading

- [Docs map](/start_here/docs_map)
- [CLI vs MCP](/start_here/cli_vs_mcp)
- [Dynamic Tool Registry](/core/dynamic_tools_registry)
- [IntentCall consumer guide](/intentcall/)
- [Creating Dynamic Tools](/guides/creating_dynamic_tools)