feat(plan): implement support for MCP servers in Plan mode

[Adib234]

Summary

This PR enables read-only MCP tools to be automatically available and allowed when operating in Plan Mode. By leveraging the optional readOnlyHint annotation in MCP tool definitions, the agent can now utilize safe, non-mutating third-party tools (like documentation search or data retrieval) during the design and strategy phase without compromising safety.

Details

• Metadata Preservation: Added an isReadOnly property to the DiscoveredMCPTool class and its constructor to track the read-only status of discovered tools.
• Discovery Logic: Updated McpClient.discoverTools to extract the readOnlyHint from the MCP tool's annotations object.
• Dynamic Policy Updates: When a tool is identified as read-only during discovery, the McpClient now automatically adds an ALLOW rule to the PolicyEngine specifically for ApprovalMode.PLAN. This ensures the tool can execute in Plan mode without requiring explicit manual policy configuration.
• System Prompt Integration: Updated PromptProvider to scan the tool registry for these read-only MCP tools and include them in the "Available Tools" list within the Plan Mode system prompt.

Related Issues

Fixes #16748
Fixes #18261

How to Validate

To validate locally you can turn on plan mode and add a MCP server to the settings file.

  "mcpServers": {
    "slow": {
      "command": "node",
      "args": [
        "/Users/adibakm/dev4/gemini-cli/mcp-random-reader/index.js"
      ]
    }
  },

Here's the code for the MCP server that includes readOnlyHint in its' annotation https://paste.googleplex.com/5838293042331648

Now if you ask Gemini CLI to execute the tool in plan mode, it should be able to do it

Also tested with Github MCP server and invoked a read-only tool

Pre-Merge Checklist

• Updated relevant documentation and README (if needed)
• Added/updated tests (if needed)
• Noted breaking changes (if any)
• Validated on required platforms/methods:
  • MacOS
    • npm run
    • npx
    • Docker
    • Podman
    • Seatbelt
  • Windows
    • npm run
    • npx
    • Docker
  • Linux
    • npm run
    • npx
    • Docker

[gemini-code-assist]

Summary of Changes

Hello @Adib234, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the system's 'Plan Mode' capabilities by integrating support for read-only Model Context Protocol (MCP) tools. It enables the agent to safely utilize non-mutating third-party tools during the planning and strategy phases, thereby expanding the agent's information gathering and analytical capabilities without introducing risks associated with state-changing operations. The changes involve updates to tool discovery, policy enforcement, and prompt generation to seamlessly incorporate these newly recognized read-only tools.

Highlights

• Read-Only MCP Tool Support in Plan Mode: The system now supports the automatic availability and allowance of read-only Model Context Protocol (MCP) tools when operating in Plan Mode. This leverages the readOnlyHint annotation in MCP tool definitions.
• Metadata Preservation and Discovery Logic: An isReadOnly property has been added to the DiscoveredMCPTool class and its constructor. The McpClient.discoverTools method is updated to extract this readOnlyHint from the MCP tool's annotations.
• Dynamic Policy Updates: When a tool is identified as read-only during discovery, the McpClient automatically adds an ALLOW rule to the PolicyEngine specifically for ApprovalMode.PLAN. This ensures read-only tools can execute in Plan Mode without manual policy configuration.
• System Prompt Integration: The PromptProvider has been updated to scan the tool registry for these read-only MCP tools and include them in the 'Available Tools' list within the Plan Mode system prompt, making them visible to the agent.
• Comprehensive Testing: New unit tests have been added to verify the correct registration of read-only tools with policy rules and their inclusion in the generated system prompts for Plan Mode.

Changelog

• packages/cli/src/ui/commands/mcpCommand.test.ts
  • Updated createMockMCPTool calls to include the new isReadOnly parameter.
• packages/core/src/core/prompts.test.ts
  • Added imports for DiscoveredMCPTool, CallableTool, and MessageBus.
  • Mocked getToolRegistry().getAllTools to support testing tool discovery.
  • Introduced a new test case to ensure read-only MCP tools are correctly included in the system prompt when in Plan Mode.
• packages/core/src/prompts/promptProvider.ts
  • Imported DiscoveredMCPTool.
  • Modified the planModeToolsList generation logic to identify and append read-only DiscoveredMCPTool instances to the list of available tools in Plan Mode.
• packages/core/src/telemetry/loggers.test.ts
  • Adjusted DiscoveredMCPTool constructor calls in tests to accommodate the new isReadOnly parameter.
• packages/core/src/tools/mcp-client.test.ts
  • Imported ApprovalMode and PolicyDecision.
  • Added a test case to verify that McpClient registers tools with readOnlyHint and adds an ALLOW policy rule for ApprovalMode.PLAN.
  • Added a test case to confirm that no policy rule is added for tools without the readOnlyHint annotation.
• packages/core/src/tools/mcp-client.ts
  • Imported ApprovalMode and PolicyDecision.
  • Modified the discoverTools function to extract the readOnlyHint from MCP tool annotations.
  • Passed the extracted isReadOnly status to the DiscoveredMCPTool constructor.
  • Implemented logic to automatically add an ALLOW policy rule for identified read-only tools in ApprovalMode.PLAN.
• packages/core/src/tools/mcp-tool.test.ts
  • Updated multiple DiscoveredMCPTool constructor calls in tests to include the new isReadOnly parameter.
• packages/core/src/tools/mcp-tool.ts
  • Added a readonly isReadOnly?: boolean property to the DiscoveredMCPTool class constructor.
  • Updated the clone method to include the isReadOnly property.

Activity

• The pull request addresses and fixes issue Implement support for MCP servers in Plan mode #16748, which likely relates to enabling MCP server support in Plan mode.
• Validation steps are provided, instructing reviewers to enable Plan Mode, configure an MCP server with a readOnlyHint annotation, and verify that the Gemini CLI can execute the tool.
• The author, Adib234, has included a pre-merge checklist covering documentation, testing, breaking changes, and platform validation across MacOS, Windows, and Linux environments.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[github-actions]

Size Change: +1.13 kB (0%)

Total Size: 23.7 MB

Filename	Size	Change
./bundle/gemini.js	23.7 MB	+1.13 kB (0%)

ℹ️ View Unchanged

Filename	Size
./bundle/sandbox-macos-permissive-closed.sb	1.03 kB
./bundle/sandbox-macos-permissive-open.sb	890 B
./bundle/sandbox-macos-permissive-proxied.sb	1.31 kB
./bundle/sandbox-macos-restrictive-closed.sb	3.29 kB
./bundle/sandbox-macos-restrictive-open.sb	3.36 kB
./bundle/sandbox-macos-restrictive-proxied.sb	3.56 kB

_{compressed-size-action}

[gemini-code-assist]

Code Review

This pull request effectively enables read-only MCP tools in Plan Mode, which is a great enhancement for safety and usability during the design phase. The implementation is logical and includes relevant tests. I've identified one area for improvement to enhance robustness. My specific comment provides a suggestion to address this point.

[jerop]

• how does default mode handle read-only mcp tools? does it ask user for permissions? should we carry over this change to default mode as well? we want to make sure that plan mode is most conservative (that is, don't want it to be more permissive than default mode)
• is there a way to configure this in policy engine? it'd be great if policy engine was the source of truth for all tool permissions, both core or mcp tools

[Adib234]

how does default mode handle read-only mcp tools? does it ask user for permissions? should we carry over this change to default mode as well? we want to make sure that plan mode is most conservative (that is, don't want it to be more permissive than default mode)

default mode asks for users's permission when a tool from an MCP server will execute. i've updated to make sure that we ask for the user permission every time a tool from an mcp server will execute in plan mode.

is there a way to configure this in policy engine? it'd be great if policy engine was the source of truth for all tool permissions, both core or mcp tools

yes it seems there is, we can use PolicyDecision.ASK_USER to make sure the user is asked for a tool's execution