flutter mcp toolkit custom tools
- Repo stars 0
- Author repo skills-registry
- Domain
- AI
- Author-declared agents
- No explicit declaration found; this is not inferred or tested compatibility
- Static check
- 88 / 100 · heuristic scan, not runtime safety proof
- Runtime evidence
- Not run; no isolated runtime test evidence is currently recorded
- Author / version / license
- @tomevault-io · no license declared
- Token usage
- Lean
- Setup complexity
- Guided setup
- External API key
- Not required
- Operating systems
- Unspecified (assume cross-platform)
- Runtime requirements
- No explicit requirements detected
- Detected file/system behavior
-
- Read-only
- Write / modify
- Shell exec
- Network behavior
- External requests
- Install commands
- None (reference only)
Heads up: Tool permissions are not declared; actual access depends on the runtime.
<!-- @FMT_MODE_PRELUDE -->
# Custom MCP Toolkit Tools & Resources (Dynamic Registry)
Use this when bundled MCP tools (screenshot, semantic snapshot, tap, …) are not enough and you need **app-specific** read surfaces or actions — e.g. cart totals, feature flags, curated debug snapshots of internal state. Entries are registered **in the Flutter process** and exposed to the agent through the **dynamic registry**.
## Pick the right primitive
| Need | Use |
|------|-----|
| One-off read of a simple value | **`fmt_evaluate_dart_expression`** (no app code change). |
| Stable **read-only** payload (diagnostics, JSON snapshot, “current route”) | **`MCPCallEntry.resource`** + **`fmt_client_resource`**. Prefer resources when the contract is “GET-like” and idempotent. |
| Parameterized or mutating action, or reusable named operation | **`MCPCallEntry.tool`** + **`fmt_client_tool`**. |
## Handler signature (tools and resources)
[`MCPCallHandler`](https://github.com/Arenukvern/mcp_flutter/blob/main/mcp_toolkit/lib/src/mcp_models.dart) is `FutureOr<MCPCallResult> Function(ServiceExtensionRequestMap request)` where **`ServiceExtensionRequestMap` is `Map<String, String>`**.
- Tool arguments arrive as **string values** keyed by schema property names — mirror the README pattern: `request['n']`, `request['userId']`, then parse (`int.tryParse`, `double.tryParse`, `jsonDecode` for nested blobs if the wire format sends JSON-as-string).
- Do **not** use `request.arguments` — that is not the app-side API.
## Minimal tool registration
```dart
import 'package:mcp_toolkit/mcp_toolkit.dart';
final tool = MCPCallEntry.tool(
handler: (request) async {
final userId = request['userId'] ?? '';
final cart = CartRepository.instance.forUser(userId);
return MCPCallResult(
message: 'ok',
parameters: {
'total': cart.total,
'items': cart.items.map((i) => i.toJson()).toList(),
},
);
},
definition: MCPToolDefinition(
name: 'cart_get_snapshot',
description: 'Return current cart total and items for a user.',
inputSchema: {
'type': 'object',
'additionalProperties': false,
'properties': {
'userId': {'type': 'string'},
},
'required': ['userId'],
},
),
);
await MCPToolkitBinding.instance.addEntries(entries: {tool});
```
Prefer **`MCPToolkitBinding.instance.bootstrapFlutter(additionalEntries: { ... }, runApp: ...)`** so tools/resources register in one place with zone/error setup — same entries shape as above.
Register **after** `initialize()` / **`bootstrapFlutter`** wiring, **once** at bootstrap — not inside `build`, not per-widget `initState`.
## Custom resources
Resources are for **read-only** MCP surfaces: diagnostics, config summaries, or JSON blobs the agent polls without treating them as imperative actions.
```dart
MCPCallEntry.resource(
definition: MCPResourceDefinition(
name: 'app_cart_digest',
description: 'Compact cart summary for agents (read-only).',
mimeType: 'application/json',
),
handler: (request) async => MCPCallResult(
message: 'Cart digest',
parameters: {
'itemCount': CartRepository.instance.visibleCount,
'currency': CartRepository.instance.currencyCode,
},
),
),
```
- **`name`** must be `snake_case` (letters, digits, underscores). [`resourceUri`](https://github.com/Arenukvern/mcp_flutter/blob/main/mcp_toolkit/lib/src/mcp_models.dart) maps it to a **`visual://localhost/...`** URI (underscore segments become path segments). Agents consume it via **`fmt_client_resource`** using that URI / listing from **`fmt_list_client_tools_and_resources`**.
- Set **`mimeType`** honestly (`application/json` vs `text/plain`) so clients know how to interpret payloads.
## Schema rules (tools)
The MCP server enforces strict JSON Schema:
- Prefer **`additionalProperties: false`** unless you intentionally accept arbitrary keys. Unknown keys **fail validation** — good for catching agent typos.
- Mark **`required`** for anything the handler reads unconditionally.
- Prefer primitives and **`enum`** over unconstrained strings.
- **`parameters`** in **`MCPCallResult`** must be JSON-serializable; non-serializable objects degrade to **`toString()`**.
## Discovery from the agent side
1. **`fmt_list_client_tools_and_resources`** — enumerate app-registered tools and resources.
2. **`fmt_client_tool`** — invoke a tool by name with JSON args (CLI: `flutter-mcp-toolkit exec --name fmt_client_tool --args '...'` per your transport).
3. **`fmt_client_resource`** — fetch a registered resource (URI from listing / `resourceUri` convention).
If something should appear but does not: confirm **`addEntries`** completed (**`await`**), then hot **restart** — reload does not always replay discovery cleanly.
## Lifecycle gotchas
- **Hot reload** + **`addEntries`** from widget code → duplicate registrations. Register once in **`main()` / bootstrap**, not in **`build`**.
- **Hot restart** clears VM state; registrations tied to **`bootstrapFlutter`** / **`main`** run again on boot — correct pattern survives restart.
- **Debug mode only** — release builds do not expose these VM service extensions.
- **Naming**: flat global namespace per app — prefix tools/resources (`cart_`, `flags_`, `nav_`) to avoid collisions with builtins or other domains.
## When the agent authors surfaces for the user’s app
1. Ensure **`mcp_toolkit`** is in **`pubspec.yaml`**.
2. Add **`lib/mcp_tools/<domain>_surfaces.dart`** exporting **`registerXSurfaces()`** that returns **`Set<MCPCallEntry>`** or performs **`addEntries`** once.
3. Wire **`registerXSurfaces()`** from **`bootstrapFlutter(..., additionalEntries: ...)`** or call **`addEntries`** immediately after **`initializeFlutterToolkit`** inside **`bootstrapFlutter`**’s chain — **never** from **`StatefulWidget` lifecycle**.
4. Tight schemas (**`additionalProperties: false`**, explicit **`required`**).
5. Hot **restart**, then **`fmt_list_client_tools_and_resources`** before first **`fmt_client_tool`** / **`fmt_client_resource`** call.
## Safety and scope
- Treat handlers as **powerful debug hooks**: avoid exposing secrets, full databases, or unchecked filesystem/network IO.
- Keep handlers thin: delegate to domain/services already used by the app (same DI/getters), **don’t** duplicate business logic in MCP-only paths unless intentional.
## Common traps
- **`request.arguments`** — wrong shape; use **`request['key']`** on **`Map<String, String>`**.
- Missing **`await`** on **`addEntries`** → race before discovery lists your surface.
- Returning **`Future`** instances inside **`parameters`** → useless serialization; **`await`** inside the handler.
- **`inputSchema`** out of sync with the handler → agents trust the schema; update both.
## Related
- Driving the live app (snapshot / tap / reload): **`flutter-mcp-toolkit-guide`** → **`flutter-mcp-toolkit-inspect`** / **`flutter-mcp-toolkit-control`**.
- Repository **`ARCHITECTURE.md`** → “Dynamic Registry Architecture”.
---
> Source: [Arenukvern/mcp_flutter](https://github.com/Arenukvern/mcp_flutter) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-05-22 -->
Sections and files
Listed in source order.
sections -> Pick the right primitive → Handler signature (tools and resources) → Minimal tool registration → Custom resources → Schema rules (tools) → Discovery from the agent side
terms -> app-specific · in the Flutter process · dynamic registry · fmtevaluatedartexpression · read-only · MCPCallEntry.resource · fmtclientresource · MCPCallEntry.tool
files/cmd -> fmt_evaluate_dart_expression · MCPCallEntry.resource · fmt_client_resource · MCPCallEntry.tool · fmt_client_tool · MCPCallHandler · FutureOr<MCPCallResult> Function(ServiceExtensionRequestMap request) · ServiceExtensionRequestMap
body sha256 -> ebe00b8b1a8f
Pick the right primitive
Need · Use One-off read of a simple value ·
fmt_evaluate_dart_expression(no app code change). Stable read-only payload (diagnostics, JSON snapshot, “current route”) ·MCPCallEntry.resource+fmt_client_resource. Prefer resources when the contract is “GET-like” and idempotent. Parameterized or mutating action, or reusable named operation ·MCPCallEntry.tool+fmt_client_tool.Handler signature (tools and resources)
MCPCallHandlerisFutureOr<MCPCallResult> Function(ServiceExtensionRequestMap request)whereServiceExtensionRequestMapisMap<String, String>. Tool arguments arrive as string values keyed by schema property names — mirror the README pattern:request['n'],request['userId'], then parse (int.tryParse,double.tryParse,jsonDecodefor nested blobs if the wire format sends JSON-as-string).Minimal tool registration
Prefer
MCPToolkitBinding.instance.bootstrapFlutter(additionalEntries: { ... }, runApp: ...)so tools/resources register in one place with zone/error setup — same entries shape as above. Register afterinitialize()/bootstrapFlutterwiring, once at bootstrap — not insidebuild, not per-widgetinitState.Custom resources
Resources are for read-only MCP surfaces: diagnostics, config summaries, or JSON blobs the agent polls without treating them as imperative actions.
namemust besnake_case(letters, digits, underscores).resourceUrimaps it to avisual://localhost/...URI (underscore segments become path segments). Agents consume it viafmt_client_resourceusing that URI / listing fromfmt_list_client_tools_and_resources.Schema rules (tools)
The MCP server enforces strict JSON Schema: Prefer
additionalProperties: falseunless you intentionally accept arbitrary keys. Unknown keys fail validation — good for catching agent typos. Markrequiredfor anything the handler reads unconditionally. Prefer primitives andenumover unconstrained strings.parametersinMCPCallResultmust be JSON-serializable; non-serializable objects degrade totoString().