gws-mcp copilot-instructions.md

Repository overview

gws is a Rust CLI for Google Workspace APIs. It dynamically generates its command surface at runtime by parsing Google Discovery Service JSON documents — it does not use generated crates like google-drive3. This repository is shigechika/gws-mcp, a fork of googleworkspace/cli that keeps an MCP (Model Context Protocol) server upstream removed. It stays close to upstream on purpose: minimize divergence so future upstream merges stay low-conflict.

Cargo workspace, two crates:

• crates/google-workspace/ — publishable library (Discovery models, HTTP client, path/URL/resource validators in validate.rs)
• crates/google-workspace-cli/ — the gws binary (arg parsing, executor, auth, helpers, and the fork-only mcp_server.rs)

Full architecture, workspace layout, and helper-command conventions are in AGENTS.md at the repo root — read it before reviewing changes to executor.rs, validate.rs, or anything under helpers/.

Build & validate

cargo build                          # dev build, both crates
cargo test -p google-workspace       # library unit tests
cargo test -p google-workspace-cli   # CLI unit tests
cargo clippy --workspace -- -D warnings   # exact command CI runs — not --all-targets
cargo fmt --check

A .rs/Cargo.* change without a .changeset/*.md file fails the Policy Check CI job. Changeset format:

---
"@googleworkspace/cli": patch
---

One-paragraph description of the fix.

What to focus review on in this repo

1. URL construction is a real attack surface — this CLI is driven by LLM/MCP agents

AGENTS.md → "Input Validation & URL Safety" defines the contract precisely. Check every diff that builds a URL against it:

• Path segments: user input must go through crate::validate::encode_path_segment(). Never format raw input into a path.
• Query parameters: must go through reqwest's .query() builder, NOT raw format!("...?key={value}") string interpolation. A value containing & in a hand-formatted query string silently truncates/splits into extra parameters; + gets decoded server-side as a space. (This exact class of bug shipped once in helpers/modelarmor.rs and was only caught in manual review, not by an earlier automated pass — flag any format! containing ? or & next to a variable.)
• Resource names (project IDs, space names, topic names) must go through crate::validate::validate_resource_name() before being embedded anywhere.
• If a diff touches crate::validate::encode_path_segment, validate_resource_name, or any other function in validate.rs: grep for every caller across crates/ (there are call sites scattered across executor.rs, discovery.rs, and multiple files under helpers/ — don't trust a fixed list, re-grep each time, since new helpers add new callers) and check each one still gets the behavior it relies on — these are shared, security-sensitive utilities, not single-use helpers. A change that's correct for the file it's in can still break a different caller with a different usage pattern (e.g. a path-segment encoder reused for a query value).