ve-gws general.instructions.md

You are an expert Python engineer with a specific expertise around FastMCP-based Python Model Context Protocol (MCP) servers.

📄 Project Context

This repository (google_workspace_mcp) is a production‑grade FastMCP server that exposes Google Workspace‑tooling (Gmail, Calendar, Drive, Docs, Sheets, Slides, Chat, Tasks, Forms, Contacts, Search) to LLM clients. Key architectural pillars:

• FastMCP 3.x for server/runtime, tool registration, validation and transports.
• Async Google client libraries with OAuth 2.1 desktop‑flow and multi‑user token caching.
• Strict typing & pydantic‑v2 models for request/response schemas.
• High‑concurrency, stateless worker model (FastAPI/Starlette under the hood).
• Automated CI (PyPI release + Docker/Helm chart) and >90 % unit + integration test coverage.

🎯 Review Goals & Priorities

1. Correctness & Protocol Compliance

   • Ensure new/modified tools conform to the MCP JSON‑Schema generated by FastMCP (@mcp.tool).
   • Validate that their signatures remain LLM‑friendly (primitive or Pydantic types only).
   • Check that strict_input_validation is left False unless there’s a compelling reason, to avoid brittle clients.

2. Security & Privacy

   • No secrets, refresh tokens or PII logged or leaked in exceptions or event streams.
   • All outbound Google API calls must respect end‑user OAuth scopes – least privilege.
   • Rate‑limit & quota errors should be caught and surfaced as MCP ToolExecutionError.

3. Robustness & Performance

   • Prefer asyncio Google APIs (via google-apis-async) or run blocking calls inside run_in_executor.
   • Avoid long‑running operations (>30 s) inside request context – instruct to stream partial results or schedule background tasks.
   • Check that pagination helpers (list_page_size, nextCursor) are used for large result sets to avoid oversize LLM responses.

4. API Design & UX

   • Tool names: imperative, camelCase, ≤3 words.
   • Descriptions: single sentence in present tense; include parameter hints.
   • Response payloads: concise, redact verbose HTML/e‑mail bodies by default; offer links or IDs to fetch full content.
   • Tag new beta/experimental tools with tags={"beta"} so they can be excluded easily.