Fix Flutter Toolkit Commands Failing With Unknown property "isolateId"

[drown0315]

Fix Flutter Toolkit Commands Failing With Unknown property "isolateId"

Summary

• Strip Flutter VM Service isolateId metadata before mcp_toolkit validates tool arguments.
• Add a regression test for service extension callbacks that receive VM-injected isolateId.
• Keep real tool arguments intact while preventing strict schemas from rejecting VM routing metadata.

Closes #94

Problem

Flutter VM Service injects isolateId into service extension callback parameters as routing metadata.

mcp_toolkit was passing the full callback parameter map into schema coercion and validation. Because toolkit schemas are strict, commands could fail with:

AgentValidationException: Unknown property "isolateId"

This affected app-side toolkit commands such as:

• get_view_details
• semantic_snapshot
• get_app_errors

Fix

Filter VM Service metadata before schema coercion and validation:

final wireArgs = _extractToolArguments(parameters);

_extractToolArguments removes isolateId while preserving actual tool arguments.

Map<String, Object?> _extractToolArguments(
  final Map<String, String> parameters,
) => Map<String, Object?>.from(parameters)..remove('isolateId');

Validation

• flutter test test/mcp_toolkit_bootstrap_test.dart
• flutter test
• flutter analyze

Summary by CodeRabbit

• Bug Fixes

  • Resolved an issue where tool extensions could fail schema validation during execution due to internal service fields being included in tool arguments.

• Tests

  • Added comprehensive test coverage for tool extension service invocations to verify proper argument handling.

[docs-page]

To view this pull requests documentation preview, visit the following URL:

docs.page/arenukvern/mcp_flutter~95

Documentation is deployed and generated using docs.page.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR fixes a tool validation failure in Flutter debug mode by filtering VM-service-injected isolateId metadata before schema validation. A new _extractToolArguments helper removes the field, and a test verifies the behavior preserves other parameters.

Changes

isolateId metadata filtering in service extensions

Layer / File(s)	Summary
Service extension isolateId parameter filtering mcp_toolkit/lib/src/mcp_toolkit_extensions.dart	Service extension callback now derives wireArgs via _extractToolArguments helper, which removes isolateId from parameters before schema validation, while preserving other tool arguments.
Test isolation of isolateId parameter handling mcp_toolkit/test/mcp_toolkit_bootstrap_test.dart	Test verifies that service extension callbacks strip isolateId metadata while preserving actual tool parameters, using helper classes to capture callback registration and provide test infrastructure.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Poem

A curious field was breaking our tools,
VM metadata mixing with schema rules.
Strip isolateId, let parameters shine—
Test validates the fix is divine! 🐰✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically describes the main fix: removing the 'isolateId' property that was causing validation failures in Flutter Toolkit commands.
Linked Issues check	✅ Passed	The pull request fully addresses issue #94 by filtering VM-injected 'isolateId' metadata before schema validation, allowing toolkit commands to work correctly while preserving intended tool arguments.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to fixing the 'isolateId' validation issue: the helper function removes the problematic field, and the test validates the fix without introducing unrelated modifications.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

🧹 Nitpick comments (1)

mcp_toolkit/lib/src/mcp_toolkit_extensions.dart (1)

194-201: 💤 Low value

Inline comments correctly explain the VM transport metadata filtering.

The helper function correctly strips isolateId before schema coercion/validation, preventing AgentValidationException on unknown properties. The inline comments clearly explain WHY this filtering is necessary (VM service transport injects routing metadata that isn't an MCP tool argument).

💬 Optional: Consider dartdoc style for consistency

While inline comments work well for private functions, the coding guidelines prefer /// for documentation comments. If you want stricter consistency with project conventions:

-// Flutter's VM service extension transport injects isolateId into callback
-// parameters. It routes the VM service call to the target isolate; it is not
-// an MCP tool argument. Strip it before schema coercion/validation because
-// tool schemas intentionally reject unknown properties.
-Map<String, Object?> _extractToolArguments(
-  final Map<String, String> parameters,
-) => Map<String, Object?>.from(parameters)..remove('isolateId');
+/// Flutter's VM service extension transport injects isolateId into callback
+/// parameters. It routes the VM service call to the target isolate; it is not
+/// an MCP tool argument. Strip it before schema coercion/validation because
+/// tool schemas intentionally reject unknown properties.
+Map<String, Object?> _extractToolArguments(
+  final Map<String, String> parameters,
+) => Map<String, Object?>.from(parameters)..remove('isolateId');

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@mcp_toolkit/lib/src/mcp_toolkit_extensions.dart` around lines 194 - 201,
Summary: convert the inline block comment explaining VM service transport
metadata filtering into a dartdoc comment for consistency. Replace the existing
/* ... *// // block above the private helper _extractToolArguments with a ///
dartdoc comment that preserves the same explanation (that Flutter VM service
injects isolateId into callback parameters and it must be stripped before schema
coercion/validation), leaving the implementation Map<String, Object?>
_extractToolArguments(Map<String, String> parameters) => Map<String,
Object?>.from(parameters)..remove('isolateId'); unchanged.

Source: Coding guidelines

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@mcp_toolkit/lib/src/mcp_toolkit_extensions.dart`:
- Around line 194-201: Summary: convert the inline block comment explaining VM
service transport metadata filtering into a dartdoc comment for consistency.
Replace the existing /* ... *// // block above the private helper
_extractToolArguments with a /// dartdoc comment that preserves the same
explanation (that Flutter VM service injects isolateId into callback parameters
and it must be stripped before schema coercion/validation), leaving the
implementation Map<String, Object?> _extractToolArguments(Map<String, String>
parameters) => Map<String, Object?>.from(parameters)..remove('isolateId');
unchanged.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: da41ee07-e7d6-4ad2-8566-aedda7ab0334

📥 Commits

Reviewing files that changed from the base of the PR and between 21c160a and 37fcaa8.

📒 Files selected for processing (2)

• mcp_toolkit/lib/src/mcp_toolkit_extensions.dart
• mcp_toolkit/test/mcp_toolkit_bootstrap_test.dart