gh-aw-mcpg: Instructions file for Codex

AGENTS.md

Quick reference for AI agents working with MCP Gateway (Go-based MCP proxy server).

Quick Start

Install: make install (install toolchains and dependencies)
Build: make build (builds awmg binary)
Test: make test (run unit tests, no build required)
Test-Unit: make test-unit (run unit tests only)
Test-Integration: make test-integration (run binary integration tests, auto-builds binary if not present)
Test-All: make test-all (run both unit and integration tests; always builds the binary first)
Test-CI: make test-ci (unit tests with coverage and JSON output for CI)
Lint: make lint (runs go vet, gofmt checks, and golangci-lint)
Coverage: make coverage (unit tests with coverage report)
Format: make format (auto-format code with gofmt)
Clean: make clean (remove build artifacts)
Agent-Finished: make agent-finished (run format, build, lint, and all tests (unit, integration, Rust guard) - ALWAYS run before completion)
Run: ./awmg --config config.toml
Run sequentially: ./awmg --config config.toml --sequential-launch
Run with Custom Log Directory: ./awmg --config config.toml --log-dir /path/to/logs
Run with Custom Payload Directory: ./awmg --config config.toml --payload-dir /path/to/payloads

Project Structure

• internal/auth/ - Authentication header parsing and middleware
• internal/cmd/ - CLI (Cobra)
• internal/config/ - Config parsing (TOML/JSON) with validation; the package is split across multiple files
  • config_core.go - Core Config, GatewayConfig, and ServerConfig types plus TOML loading
  • config_stdin.go - JSON stdin structs and stdin→internal config conversion
  • config_env.go, config_feature.go, config_tracing.go - Environment- and feature-specific config helpers
  • validation.go, validation_env.go, validation_schema.go - Fail-fast field, environment, and schema validation
  • validation_test.go - Comprehensive validation tests
• internal/delegation/ - Delegation envelope, capability, and audit logic
• internal/difc/ - Decentralized Information Flow Control
• internal/enclavegithub/ - Enclave-scoped GitHub capability/policy/route handling for delegation
• internal/envutil/ - Environment variable and Docker env-arg utilities
• internal/githubhttp/ - GitHub API-specific HTTP helpers (auth headers, collaborator permission, rate-limit parsing)
• internal/guard/ - Security guards (NoopGuard, WasmGuard, WriteSinkGuard)
• internal/hmacutil/ - HMAC-SHA256 request signing and verification helpers
• internal/httputil/ - Generic HTTP helper utilities (server, proxy)
• internal/jqutil/ - Shared gojq compiler options (security: $ENV access disabled)
• internal/launcher/ - Backend process management
• internal/logger/ - Debug logging framework (micro logger)
• internal/mcp/ - MCP protocol types with enhanced error logging
• internal/mcpresult/ - MCP result text content helpers
• internal/middleware/ - HTTP middleware (jq schema processing)
• internal/mountspec/ - Container bind-mount declaration parsing
• internal/oidc/ - GitHub Actions OIDC token provider and caching
• internal/proxy/ - Filtering HTTP proxy for the GitHub API with DIFC enforcement
• internal/reposelector/ - Canonical/legacy GitHub owner and repository selector validation shared by guard policies, enclave policies, and delegated identities
• internal/restroute/ - Shared REST path-matching helpers
• internal/sanitize/ - Sensitive data redaction utilities (SanitizeString, SanitizeJSON, RedactSecret) for safe log output
• internal/server/ - HTTP server (routed/unified modes)
• internal/util/ - String, formatting, randomness, and JSON deep-clone utilities
• internal/syncutil/ - Concurrency utilities
• internal/sys/ - System utilities
• internal/testutil/ - Test utilities and helpers
• internal/tracing/ - OpenTelemetry tracing setup and OTLP export
• internal/tty/ - Terminal detection utilities
• internal/urlutil/ - URL hostname extraction utilities (used by guard and middleware for domain audit logging)
• internal/version/ - Version management