# MCPCallEntry to AgentCallEntry migration

Flutter MCP Toolkit removed the dual authoring path. **`MCPCallEntry` is deleted** from
`mcp_toolkit`; use **`AgentCallEntry`** and the operator tools below for straggler repos.

IntentCall architecture and future package planning are canonical in the IntentCall repository. This page is kept in `mcp_flutter` because it documents the consumer migration surface shipped by Flutter MCP Toolkit.

## TL;DR

```bash
# Preview changes (exit 1 if anything would change)
flutter-mcp-toolkit migrate agent-entries --check lib/

# Apply in place
flutter-mcp-toolkit migrate agent-entries --write lib/main.dart
```

Alias: `migrate mcp-call-entry` (same flags).

## What changes

| Before (MCPCallEntry) | After (AgentCallEntry) |
| --------------------- | ---------------------- |
| `MCPCallEntry.tool(definition: MCPToolDefinition(...), handler: …)` | `AgentCallEntry.tool(namespace:, name:, description:, inputSchema:, handler: …)` |
| `MCPCallEntry.resource(definition: MCPResourceDefinition(...), handler: …)` | `AgentCallEntry.resource(...)` |
| `Set<MCPCallEntry>` | `Set<AgentCallEntry>` |
| Handler returns `MCPCallResult` | Handler returns `AgentResult.success(...)` (migrator wraps legacy handlers) |
| `import 'package:mcp_toolkit/mcp_toolkit.dart';` only | Adds `intentcall_core` + `intentcall_schema` imports when needed |

Default namespace: `app` (override with `--namespace my_ns`).

## CLI reference

```text
flutter-mcp-toolkit migrate agent-entries [--check] [--write] [--namespace app] <path>

  path    Dart file or directory (recursive for directories)
  --check Report files that would change; exit 1 if any pending
  --write Apply migrations in place (mutually exclusive with --check)
```

Examples:

```bash
flutter-mcp-toolkit migrate agent-entries --check .
flutter-mcp-toolkit migrate agent-entries --write lib/custom_tools.dart
flutter-mcp-toolkit migrate agent-entries --write --namespace my_app lib/
```

## Limitations (manual follow-up)

The migrator is **text-based**, not a full analyzer rewrite:

1. **Extension types** — `extension type Foo._(MCPCallEntry entry) implements MCPCallEntry`
   are retargeted to `AgentCallEntry`, but you should review namespace and handler bodies.
2. **`inputSchema`** — `ObjectSchema(...)` from `dart_mcp` becomes a placeholder empty
   object schema. Copy constraints from the old definition manually.
3. **Complex handlers** — block bodies with multiple returns may need hand-editing to
   return `AgentResult` directly instead of the adapter wrapper.
4. **Bootstrap APIs** — `addMcpTool`, `MCPToolkitBinding.addEntries`, and
   `agent_client_install` accept **`AgentCallEntry` only** (Phase 6b hard cut).

## MCP tool

`fmt_migrate_agent_entries` — report-only by default (`projectRoot` required);
set `apply: true` to rewrite files on the host. CLI equivalent:
`flutter-mcp-toolkit migrate agent-entries`.

## Platform hooks (native + web)

One-time project setup (dogfood: [flutter_test_app/INTENTCALL_PLATFORM.md](../../flutter_test_app/INTENTCALL_PLATFORM.md)):

```bash
flutter-mcp-toolkit init intentcall-platform --project-dir path/to/flutter_app
flutter-mcp-toolkit codegen sync --platform web,android,ios,macos,linux,windows \
  --project-dir path/to/flutter_app
```

CI drift: add `--check` to both commands (also in `make check-contracts`).

Apple AppIntentsTesting scaffold generation, when the app has full Xcode and a
UI-test target ready:

```bash
flutter-mcp-toolkit codegen appintents-testing generate \
  --project-dir path/to/flutter_app \
  --bundle-id com.example.App \
  --sample-arguments path/to/appintents_testing_samples.json \
  --entity-fixtures path/to/appintents_testing_entities.json \
  --output path/to/YourAppUITests/IntentCallAppIntentsLiveInvocationTests.swift
```

This command only proves generated scaffold shape. Runtime proof requires the
generated source to run inside a signed XCTest UI-test target. Manifest,
fixture, and output paths are resolved relative to `--project-dir` unless they
are absolute paths.

## Related docs

- [IntentCall consumer docs](../intentcall/README.md)
- Canonical IntentCall design and ADRs: `github.com/Arenukvern/intentcall`
- [v2 → v3 migration](./migration_v2_to_v3.mdx) — server-side `fmt_` prefix (unchanged)

## Validation

```bash
cd mcp_server_dart && dart test test/migrate_agent_entries_test.dart
flutter-mcp-toolkit migrate agent-entries --check path/to/your_app/lib
flutter-mcp-toolkit init intentcall-platform --check --project-dir path/to/flutter_app
```
