工具包自定义工具

人工智能 社区

技能解读

当前原文的自动摘译,尚未人工审校。

选择正确的基元

需要 · 使用 一次性读取简单值 · fmt_evaluate_dart_expression(无需更改应用程序代码)。稳定的只读负载(诊断、JSON 快照、“当前路线”)· MCPCallEntry.resource + fmt_client_resource。当合约“类似 GET”且幂等时,优先选择资源。参数化或变异操作,或可重用的命名操作 · MCPCallEntry.tool + fmt_client_tool。

处理程序签名(工具和资源)

MCPCallHandler 是FutureOr<MCPCallResult> Function(ServiceExtensionRequestMap request),其中ServiceExtensionRequestMap 是Map<String, String>。工具参数以模式属性名称键入的字符串值形式到达 - 镜像 README 模式:request['n']、request['userId'],然后解析(如果有线格式发送 JSON 作为字符串,则解析嵌套 blob 的int.tryParse、double.tryParse、jsonDecode)。

最少的工具注册

更喜欢MCPToolkitBinding.instance.bootstrapFlutter(additionalEntries: { ... }, runApp: ...),这样工具/资源就可以通过区域/错误设置注册在一个地方 - 与上面相同的条目形状。在 initialize() / bootstrapFlutter 接线之后注册,一次在引导程序中 - 不在 build 内部,而不是每个小部件 initState。

定制资源

资源用于只读 MCP 表面:代理轮询的诊断、配置摘要或 JSON blob,而不将它们视为命令式操作。 name 必须是snake_case(字母、数字、下划线)。 resourceUri 将其映射到visual://localhost/... URI(下划线段成为路径段)。代理使用来自 fmt_list_client_tools_and_resources 的 URI/列表通过 fmt_client_resource 使用它。

架构规则(工具)

MCP 服务器强制执行严格的 JSON 模式:首选additionalProperties: false,除非您故意接受任意密钥。未知的密钥无法验证 - 有助于捕获代理拼写错误。为处理程序无条件读取的任何内容标记required。与无约束字符串相比,更喜欢基元和enum。 MCPCallResult中的parameters必须是JSON可序列化的;不可序列化对象降级为toString()。

流狐档案 运行与权限由流狐静态检查推断,不代表作者声明或实际测试结果。
领域
人工智能
作者声明的智能体
未找到明确声明;不据此推断已兼容或已测试
静态检查
88 / 100 · 启发式扫描,不代表运行安全
运行环境证据
未执行;当前没有隔离运行测试证据
作者 / 版本 / 许可证
@tomevault-io · 未声明许可证
上下文用量评级
低消耗
接入复杂程度
需简单配置
是否需要外部接口密钥
不需要
兼容的系统
未声明(默认跨平台)
运行环境要求
未检出明确要求
检测到的文件与系统行为
  • 只读
  • 允许写入 / 修改
  • 命令执行
网络行为
允许外网请求
安装命令数
无(仅作为资料)

需要注意: 未声明工具权限范围;实际权限由运行环境决定。

作者说明文件(原文) SKILL.md

<!-- @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 -->

讨论

基于 GitHub Discussions。登录 GitHub 即可参与讨论、点赞、订阅更新。