Skip to content

AGENTS.md

Latest commit

 

History

History
154 lines (124 loc) · 7.4 KB

AGENTS.md

File metadata and controls

154 lines (124 loc) · 7.4 KB
Raw

AGENTS.md

Instructions for coding agents (Codex and compatible tools) working in this repository. Self-contained — you do not need to read any other file to get oriented.

Repository shape

iap-https-rust is a multi-language, multi-variant MCP (Model Context Protocol) server workspace. Each variant exposes the same system-utility tools (system info, disk usage, process list) but differs in language, transport, and security model. The comparison is the product.

Critically: there is no shared library. Every variant is an independent project with its own manifest, Makefile, README.md, and GEMINI.md. The duplication between variants is intentional. Do not consolidate variants into a Cargo workspace, a shared Go package, or a Python package unless explicitly asked.

iap/  manual/  local/  stdio/  stdiokey/          Rust
bearer-rust/  proxy-rust/                          Rust (Cloud Run access patterns)
local-python/  manual-python/  stdiokey-python/    Python
bearer-python/  proxy-python/                      Python
stdio-go/  stdiokey-go/  manual-go/                Go
bearer-go/  proxy-go/                              Go
docs/     article drafts        images/   article art

local-rust, manual-rust, stdio-rust, stdiokey-rust are symlinks into local, manual, stdio, stdiokey. Always edit the real directory. Writing through both paths creates phantom duplicate diffs.

Variant matrix

Directory Lang Transport Auth
iap/ Rust Streamable HTTP IAP JWT (x-goog-iap-jwt-assertion)
manual/ Rust Streamable HTTP IAP + x-goog-api-key
local/ Rust Streamable HTTP API key (gcloud fetch)
stdio/ Rust Stdio none
stdiokey/ Rust Stdio API key
bearer-rust/ Rust Streamable HTTP bearer ID token / IAP
proxy-rust/ Rust Streamable HTTP via gcloud run services proxy
local-python/ Python SSE API key
manual-python/ Python SSE API key
stdiokey-python/ Python Stdio API key
bearer-python/ Python SSE bearer ID token
proxy-python/ Python SSE via Cloud Run proxy
stdio-go/ Go Stdio none
stdiokey-go/ Go Stdio API key
manual-go/ Go HTTP IAP + API key
bearer-go/ Go HTTP bearer ID token
proxy-go/ Go HTTP via Cloud Run proxy

Build, test, lint

Run commands from inside the variant directory. Every variant honors the same Makefile vocabulary:

Target Rust Go Python
make build cargo build go build — (use make install)
make test cargo test go test unittest
make fmt cargo fmt --all -- --check go fmt ./... ruff format .
make clippy / make lint cargo clippy -- -D warnings golangci-lint run ruff check .
make release cargo build --release optimized build —
make run start the server start the server start the server
make info / make disk one-shot CLI report same same
make deploy gcloud builds submit same same

Two things that will bite you:

  1. make fmt is a check, not a fix — in the Rust variants only. It runs cargo fmt --check and fails on unformatted code; run cargo fmt --all to actually format. The Go and Python make fmt targets do rewrite files (go fmt ./..., ruff format .). Go's make lint silently skips if golangci-lint is not installed — a passing lint there may mean nothing ran.
  2. The root Makefile does not cover every variant. It fans out only over iap manual local stdio stdiokey local-python manual-python stdiokey-python. The Go, bearer-*, and proxy-* variants must be built and tested from their own directories. A green make test at the repo root is not full coverage.

Before you report work as done, run make fmt-equivalent formatting, the linter, and make test in every directory you touched.

Language and dependency baselines

  • Rust — edition 2024. Most variants pin rmcp 0.14. stdio/ is on rmcp 3.1.0 and is the reference implementation for the newer API. Also tokio, axum, sysinfo, tracing / tracing-subscriber (JSON).
  • Go — 1.26, github.com/mark3labs/mcp-go, github.com/shirou/gopsutil/v3.
  • Python — 3.11+, mcp, starlette, uvicorn, psutil.

rmcp 3.x differences (stdio/, and any variant you migrate)

  • ServerInfo (InitializeResult) is #[non_exhaustive] — construct it with ServerInfo::new(capabilities) and the with_* helpers. A struct literal will not compile.
  • Bare #[tool_handler] expands to router = Self::tool_router(), which rebuilds the router on every tool call. Use #[tool_handler(router = self.tool_router)] to reuse the router built once in new().

docs/upgrade-rmcp-3-and-claude-code.md documents the full migration.

Hard constraints

  • Stdio variants must not write to stdout. stdout carries JSON-RPC frames only. All diagnostics go to stderr through tracing. A stray println! / fmt.Println / print() in a stdio variant silently corrupts the protocol.
  • Tool names are a public interface. local_system_info, disk_usage, iap_system_info, sysutils_manual_rust, sysutils_bearer_rust, sysutils_proxy_rust, list_processes. Renaming one breaks every client .mcp.json that registers it — treat renames as breaking changes and say so.
  • Never commit secrets. The root .gitignore excludes .mcp.json at any depth, .env, and *.key. .mcp.json is a per-developer local file that may contain an injected API key. Do not commit one, and do not echo key material into logs, docs, or commit messages.
  • Do not change a sibling variant unprompted. Fixing a bug in stdio/ does not license you to edit stdio-go/ too. Flag the parallel, let the user decide.

Tests

  • Rust: inline #[cfg(test)] mod tests at the bottom of src/main.rs.
  • Go: main_test.go next to main.go.
  • Python: tests/ directory per variant.

Follow the existing placement; do not introduce a new test layout.

Google Cloud environment

  • source ./set_env.sh — exports PROJECT_ID, PROJECT_NUMBER, REGION, ID_TOKEN, SHORT_SHA, RUST_LOG. Reads the project from ~/project_id.txt and requires authenticated gcloud. Must be sourced, not executed.
  • ./init.sh — first-run setup: project ID, API enablement, ADC.
  • set_key.sh, set_adc.sh — API key and ADC credential helpers.
  • API-key variants resolve a key named "MCP API Key" from the project via google-apikeys2 (ADC) or gcloud services api-keys. The MCP_API_KEY environment variable overrides the lookup.
  • Deployment is Cloud Run via each variant's cloudbuild.yaml. Service names vary per variant — read the variant's Makefile rather than guessing.

Do not run make deploy, gcloud builds submit, or any other command that mutates cloud state unless the user explicitly asks for a deploy.

Docs and agent guides

docs/ contains long-form article drafts (with YAML frontmatter) about MCP development in this repo. They are hand-written prose — edit conservatively.

Three agent guides coexist and should be kept consistent when project structure changes: AGENTS.md (this file), CLAUDE.md (Claude Code), and GEMINI.md (Gemini CLI, present at the root and in each variant). README.md is the human-facing entry point.