feat(mcp): add compact tool mode to reduce context window usage

[haunchen]

Summary

Addresses #82 — MCP tool count optimization.

When using gws mcp -s all, the current behavior generates 200-400 tool definitions (one per API method) that permanently occupy 40-100K tokens in the AI client's context window. Most conversations only use 3-5 methods.

This PR adds a --tool-mode compact|full flag:

• full (default): unchanged behavior, one tool per API method
• compact: one tool per service + a gws_discover meta-tool for schema queries

Compact mode details

• Each service becomes a single tool with resource and method arguments
• gws_discover provides three-level schema query: service → resources → methods → full parameter schema
• Nested resources (e.g., Gmail users.messages, users.threads) are recursively discovered via dot-separated paths
• Tool execution errors now return MCP isError: true results instead of JSON-RPC protocol errors, so clients display actual error messages

Context budget comparison

Mode	Tool count	Estimated context cost
full with -s all	200-400	40-100K tokens
compact with -s all	~26	3-5K tokens

Usage

gws mcp -s all --tool-mode compact

Test Plan

• 425 existing + 16 new unit tests pass
• Clippy clean
• Real-world tested with Claude Desktop: Gmail discover, messages.list, Drive files.list
• Full mode behavior unchanged (default)
• Backward compatible — no breaking changes

[changeset-bot]

🦋 Changeset detected

Latest commit: 2acfdd5

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@googleworkspace/cli	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[gemini-code-assist]

Summary of Changes

Hello, 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 introduces a new 'compact' tool mode for the gws mcp command, aimed at substantially reducing the AI client's context window usage. By consolidating multiple API methods into a single tool per service and providing a dedicated discovery mechanism, the change optimizes token consumption and improves the efficiency of interactions with Google Workspace APIs. It also enhances the user experience by providing more informative error messages for tool execution failures.

Highlights

• New Compact Tool Mode: Introduced a --tool-mode compact|full flag to gws mcp. The compact mode significantly reduces the number of generated tools from 200-400 to approximately 26, drastically cutting down AI client context window usage from 40-100K tokens to 3-5K tokens.
• Service-Per-Tool Representation: In compact mode, each Google Workspace service is represented as a single tool, accepting resource and method arguments, rather than generating a separate tool for each API method.
• New gws_discover Meta-Tool: Added a gws_discover meta-tool that allows for a three-level schema query: service -> resources -> methods -> full parameter schema, enabling dynamic discovery within the compact tool set.
• Improved Tool Execution Error Handling: Tool execution errors now return results with isError: true and a detailed error message, instead of generic JSON-RPC protocol errors, providing better feedback to clients.
• Nested Resource Discovery: The gws_discover tool and compact mode correctly handle nested resources (e.g., users.messages) through dot-separated paths.

Changelog

• .changeset/mcp-compact-tools.md
  • Added new changeset file documenting the introduction of compact tool mode.
• .gitignore
  • Added docs/plans/ to the ignore list for generated documentation.
• src/mcp_server.rs
  • Introduced ToolMode enum and tool_mode field to ServerConfig to manage tool generation strategy.
  • Added --tool-mode argument to the CLI for selecting between compact and full tool modes.
  • Modified handle_request to wrap tool execution errors with isError: true for better client feedback.
  • Implemented build_compact_tools_list function to generate tools for compact mode, including service-level tools and the gws_discover meta-tool.
  • Refactored workflow tool appending into a dedicated append_workflow_tools function.
  • Added handle_discover function to process requests for the gws_discover meta-tool, enabling schema queries.
  • Introduced helper functions (collect_resource_paths, collect_resource_entries, find_resource) for recursive resource discovery and traversal.
  • Updated handle_tools_call to dispatch calls based on the selected tool_mode and handle gws_discover calls.
  • Extracted common method execution logic into a new execute_mcp_method function.
  • Removed redundant comments related to upload path security validation and pagination defaults.
  • Added comprehensive unit tests for ToolMode functionality, CLI argument parsing, resource discovery, and error handling.

Activity

• All 425 existing unit tests passed, along with 16 newly added unit tests.
• The codebase is clean according to Clippy checks.
• Real-world testing was performed with Claude Desktop, verifying functionality for Gmail discover, messages.list, and Drive files.list.
• The behavior of the full tool mode remains unchanged, ensuring backward compatibility.
• The changes are fully backward compatible with existing usage.

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

[gemini-code-assist]

Code Review

This pull request introduces a compact tool mode for mcp to significantly reduce the context window usage by AI clients, which is a valuable optimization. However, a security vulnerability related to path traversal was identified in the file upload sanitization logic. The current check to restrict file uploads to the current directory is insufficient on Windows, potentially allowing an attacker to read arbitrary files on the same drive. A more robust component-based validation is suggested to address this. Additionally, there are a few suggestions to improve code clarity and follow idiomatic Rust practices, particularly in a helper function and the new test cases.

[codecov]

Codecov Report

❌ Patch coverage is 62.35521% with 195 lines in your changes missing coverage. Please review.
✅ Project coverage is 55.85%. Comparing base (f6d74b0) to head (2acfdd5).
⚠️ Report is 4 commits behind head on main.

Files with missing lines	Patch %	Lines
src/mcp_server.rs	62.35%	195 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #172      +/-   ##
==========================================
+ Coverage   55.19%   55.85%   +0.66%     
==========================================
  Files          38       38              
  Lines       13166    13627     +461     
==========================================
+ Hits         7267     7612     +345     
- Misses       5899     6015     +116     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.