fix: handle JSON-encoded console arguments and menu paths

[haranishi]

Description

When the action parameter of read_console contains the JSON string "get", FastMCP argument validation fails. When passed directly to Unity, the value containing quotation marks was also treated as an unknown action. The same input also fails to execute when used as a menu path. This change decodes exactly 1 layer of JSON string encoding in the reported fields so that such input runs the same operation as plain input.

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update
• Refactoring (no functional changes)
• Test update

Changes Made

• Normalizes action and format in read_console before Pydantic validation. Preserves the allowed values in the public schema and does not send unknown values or multiple layers of encoding to Unity. Also validates allowed values when the Python function is called directly.
• Adds handling for the target fields to the C# console and menu handlers. Leaves free-form input such as log search text unchanged.
• Forwards menu paths unchanged from Python, decodes them exactly 1 time in Unity, and then checks them against the existing execution blocklist. Also blocks quoted File/Quit.
• Regenerates the tool reference and removes execute_menu_item, which now has tests, from the existing list of untested tools.

Compatibility / Package Source

• Unity version(s) tested: 6000.3.20f1, Unity Test Framework 1.6.0.
• Package source used (#beta, #main, tag, branch, or file:): Branched from 142ea0a on beta and verified using the modified local file: package.
• Resolved commit hash from Packages/packages-lock.json (if using a Git package URL): Not applicable (local package).

Testing/Screenshots/Recordings

• Python tests (cd Server && uv run pytest tests/ -v): 1,576 passed, 17 skipped.
• Unity EditMode tests: 38/38 passed (10 new tests and 28 related console, menu, and batch tests).
• Unity PlayMode tests
• Package import/compile check: Compiled and ran tests in the actual Unity version listed above.
• Not applicable (explain why in Additional Notes)

Before the fix, normal menu calls succeeded in actual Unity, while quoted console actions and menu paths failed. After the fix, verified that the dedicated test menu executed exactly 1 time, quotation marks in search text were preserved, prohibited menus were blocked, and input with multiple layers of encoding was rejected.

The Python regression tests exercise argument validation in a real FastMCP Client/Server, in a child process isolated from the existing SDK stubs used by the integration tests. Also verified that unknown actions were not sent, the enum schema was preserved, and menu paths were forwarded. Transmission to Unity is replaced with test responses.

The generated-docs check and site build succeeded. The required multi-version Unity check script was also run, but all 4 specified versions were skipped because they were not installed.

Documentation Updates

• I have added/removed/modified tools or resources
• If yes, I have updated all documentation files using:
  • The LLM prompt at tools/UPDATE_DOCS_PROMPT.md (recommended)
  • Manual review of the generated changes

Generated argument descriptions for the 2 modified tools. There are no changes to the tool count, groups, or CLI commands.

Related Issues

Fixes #1102

Additional Notes

Reproduced and verified the reported input format. Actual client behavior using OpenCode with Qwen on Windows is not verified.

Fork CI verification

Checked the GitHub Actions results for the same commit 1831ccb79e1b56dac845213beeb33c971accd328. The Python tests succeeded, as did the harness tests that run without Unity.

C# compilation also succeeded with Unity 6000.0.75f1. Runtime and Editor were compiled for each of the Windows, macOS, and Linux configurations.

The docs build succeeded. The generated-docs drift check also succeeded.

The E2E tests and the Unity Editor tests that require a license were skipped.

The upstream GitHub Actions are waiting for a maintainer to approve the run for the current commit. The CI successes above are results from runs on the fork that verified the same commit.

Summary by CodeRabbit

• New Features
  • Console actions and formats, along with menu paths, now accept JSON-encoded strings. Decoding is limited to one layer, so nested encoded values are not treated as valid inputs.
• Bug Fixes
  • Unsupported console actions and formats are rejected with an error instead of being dispatched. JSON-encoded blocked menu paths remain blocked.
• Documentation
  • Tool reference pages now describe support for JSON-encoded arguments.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: c42ccc06-274c-4bbf-9e91-4f1abe0be139

📥 Commits

Reviewing files that changed from the base of the PR and between 142ea0a and 1831ccb.

📒 Files selected for processing (12)

• MCPForUnity/Editor/Helpers/ParamCoercion.cs
• MCPForUnity/Editor/Tools/ExecuteMenuItem.cs
• MCPForUnity/Editor/Tools/ReadConsole.cs
• Server/src/services/tools/execute_menu_item.py
• Server/src/services/tools/read_console.py
• Server/src/services/tools/utils.py
• Server/tests/integration/test_json_encoded_tool_strings.py
• Server/tests/test_tool_test_symmetry.py
• TestProjects/UnityMCPTests/Assets/Tests/EditMode/Tools/QuotedToolArgumentsTests.cs
• TestProjects/UnityMCPTests/Assets/Tests/EditMode/Tools/QuotedToolArgumentsTests.cs.meta
• website/docs/reference/tools/core/execute_menu_item.md
• website/docs/reference/tools/core/read_console.md

💤 Files with no reviewable changes (1)

• Server/tests/test_tool_test_symmetry.py

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 7 remain after this review.

📝 Walkthrough

The server and Unity tool handlers now decode one layer of JSON-encoded string arguments. The server validates read-console actions and formats, and tests and parameter descriptions cover encoded inputs.

Changes: JSON-Encoded Tool Arguments

Layer / File(s)	Summary
Server argument decoding and validation Server/src/services/tools/utils.py, Server/src/services/tools/read_console.py, Server/src/services/tools/execute_menu_item.py, Server/tests/integration/*, Server/tests/test_tool_test_symmetry.py, website/docs/reference/tools/core/*	The server decodes and validates read-console action and format values. The menu-path annotation and tool documentation describe JSON-encoded strings. Integration tests cover encoded values, invalid inputs, and menu-path forwarding.
Unity argument decoding and handling MCPForUnity/Editor/Helpers/ParamCoercion.cs, MCPForUnity/Editor/Tools/ExecuteMenuItem.cs, MCPForUnity/Editor/Tools/ReadConsole.cs, TestProjects/UnityMCPTests/Assets/Tests/EditMode/Tools/QuotedToolArgumentsTests.cs*	Unity decodes one layer of JSON string encoding before processing menu paths, console actions, and console formats. Edit-mode tests cover encoded, malformed, and nested inputs.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Bug fix · Severity of issue fixed: Medium

Suggested reviewers: scriptwonder

Merge Risk: ⚪ Minimal · up to 1831c

The change makes read_console and menu-item calls accept JSON-quoted arguments while keeping the blocklist in force. No concrete merge-blocking risk was identified.

Pre-merge checks · 4 · 1

Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 25.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 20 functions across 8 files. (3 skipped: …	Write docstrings for the functions missing them to satisfy the coverage threshold.

Passed checks (4 passed)

Check name	Status	Explanation
Title check		The title clearly and concisely summarizes the main change: handling JSON-encoded console arguments and menu paths.
Description check		The description is complete and relevant. It explains the bug, implementation, compatibility details, tests, documentation updates, related issue, and known verification limits.
Linked Issues check		Issue #1102 requires quoted values to work for read_console actions and menu-item execution. read_console applies decode_json_string to action and format, and the Unity handlers apply the sa…
Out of Scope Changes check		The changes stay within issue #1102. The shared decoding helpers, Python validation, Unity handling, regression tests, generated tool documentation, and test-coverage update directly support quoted co…

Full details: Docstring Coverage

Explanation

Docstring coverage is 25.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 20 functions across 8 files. (3 skipped: 3 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

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.}

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[haranishi]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.