diff --git a/AGENTS.md b/AGENTS.md index b0fa610d7..927dcbbda 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -16,9 +16,10 @@ Quick reference for AI agents working with MCP Gateway (Go-based MCP proxy serve **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 - ALWAYS run before completion) -**Run**: `./awmg --config config.toml` -**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` +**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 @@ -97,6 +98,7 @@ args = ["run", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN", "-i", "ghcr.io/gith - Required fields: `container` for stdio, `url` for http - **Containerization Requirement**: TOML stdio servers must use `command = "docker"` per [MCP Gateway Specification Section 3.2.1](https://github.com/github/gh-aw/blob/main/docs/src/content/docs/reference/mcp-gateway.md#321-containerization-requirement) - **Note**: In JSON stdin format, the `command` field is not supported - stdio servers must use `container` field +- **Note**: In JSON stdin format, `args` is optional and provides extra Docker runtime arguments inserted before the container image name - Port range validation: 1-65535 - Timeout validation: positive integers only @@ -374,6 +376,7 @@ DEBUG_COLORS=0 DEBUG=* ./awmg --config config.toml ## Environment Variables +- `GITHUB_MCP_SERVER_TOKEN` - Highest-priority GitHub auth token (takes precedence over `GITHUB_TOKEN`, `GITHUB_PERSONAL_ACCESS_TOKEN`, `GH_TOKEN`) - `GITHUB_PERSONAL_ACCESS_TOKEN` - GitHub auth - `GITHUB_API_URL` - Explicit GitHub API endpoint (e.g., `https://copilot-api.mycompany.ghe.com`); used by proxy to set upstream target - `GITHUB_SERVER_URL` - GitHub server URL; proxy auto-derives API endpoint: `*.ghe.com` → `copilot-api.*.ghe.com`, GHES → `/api/v3`, `github.com` → `api.github.com` @@ -404,9 +407,13 @@ DEBUG_COLORS=0 DEBUG=* ./awmg --config config.toml - `MCP_GATEWAY_TLS_KEY` - Path to TLS server private key PEM file; required when `MCP_GATEWAY_TLS_CERT` is set (sets default for `--tls-key`) - `MCP_GATEWAY_CA_CERT` - Path to CA certificate PEM file for client certificate verification; enables mutual TLS (mTLS) when set alongside `MCP_GATEWAY_TLS_CERT`/`MCP_GATEWAY_TLS_KEY` (sets default for `--tls-ca`) - `MCP_GATEWAY_HMAC_SECRET` - Shared HMAC-SHA256 secret for request signing and replay protection; when set, requests to MCP handlers must carry valid `X-MCP-Timestamp`, `X-MCP-Nonce`, and `X-MCP-Signature` headers (sets default for `--hmac-secret`) +- `OTEL_EXPORTER_OTLP_ENDPOINT` - OTLP HTTP endpoint for trace export; sets default for `--otlp-endpoint` +- `OTEL_SERVICE_NAME` - Service name in traces; sets default for `--otlp-service-name` +- `AWMG_BINARY_PATH` - Override binary path for integration tests +- `AWMG_WASM_GUARD_PATH` - Override WASM guard path for proxy integration tests - `RUNNING_IN_CONTAINER` - Set to `"true"` to force container detection when `/.dockerenv` and cgroup detection are unavailable -**Note:** `MCP_GATEWAY_PORT` is read by the `awmg` binary for environment validation (`--validate-env`) only. Plain `PORT`, `HOST`, and `MODE` are not read by `awmg` directly. However, `run.sh` uses `PORT`, `HOST` (default: `0.0.0.0`), and `MODE` (default: `--routed`) to set the bind address and routing mode. Use the `--listen` and `--routed`/`--unified` flags when running `awmg` directly. +**Note:** `MCP_GATEWAY_PORT` is read by the `awmg` binary for environment validation (`--validate-env`) only. Plain `PORT`, `HOST`, and `MODE` are not read by `awmg` directly. However, `run.sh` uses `MCP_GATEWAY_PORT` (falling back to `PORT`), `HOST` (default: `0.0.0.0`), and `MODE` (default: `--routed`) to set the bind address and routing mode. Use the `--listen` and `--routed`/`--unified` flags when running `awmg` directly. **File Logging:** - Operational logs are always written to log files in the configured log directory diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 26cf071c5..5127fb089 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -175,6 +175,9 @@ echo '{"mcpServers": {...}}' | ./awmg --config-stdin # Increase verbosity ./awmg --config config.toml -v +# Launch MCP servers sequentially during startup +./awmg --config config.toml --sequential-launch + # Custom payload directory and size threshold (payload dir must be absolute) ./awmg --config config.toml --payload-dir /tmp/payloads --payload-size-threshold 1048576 ``` @@ -263,8 +266,8 @@ gh-aw-mcpg/ ├── config/ # Configuration loading (TOML/JSON) ├── difc/ # Decentralized Information Flow Control ├── envutil/ # Environment variable utilities - ├── guard/ # Security guards (NoopGuard, WasmGuard, WriteSink) - ├── httputil/ # Shared HTTP response helpers + ├── guard/ # Security guards (NoopGuard, WasmGuard, WriteSinkGuard) + ├── httputil/ # Shared HTTP helper utilities (server responses, proxy transport) ├── launcher/ # Backend server management ├── logger/ # Debug logging framework ├── mcp/ # MCP protocol types & connection @@ -289,7 +292,7 @@ gh-aw-mcpg/ - **`internal/difc/`** - Decentralized Information Flow Control - **`internal/envutil/`** - Environment variable utilities - **`internal/guard/`** - Guard framework for resource labeling -- **`internal/httputil/`** - Shared HTTP response helpers (JSON responses, error formatting) +- **`internal/httputil/`** - Shared HTTP helper utilities (server responses, proxy transport) - **`internal/launcher/`** - Backend process management (Docker, stdio) - **`internal/logger/`** - Micro logger for debug output - **`internal/mcp/`** - MCP protocol types and JSON-RPC handling diff --git a/config.example-payload-threshold.toml b/config.example-payload-threshold.toml index 63a9809de..5ad764837 100644 --- a/config.example-payload-threshold.toml +++ b/config.example-payload-threshold.toml @@ -17,6 +17,7 @@ api_key = "your-api-key-here" # - Flag: --payload-dir /custom/path # - Env: MCP_GATEWAY_PAYLOAD_DIR=/custom/path # Default: /tmp/jq-payloads +# Note: This runtime storage path may live under /tmp and is separate from any agent editing workspace. payload_dir = "/tmp/jq-payloads" # Payload path prefix for remapping file paths returned to clients diff --git a/docs/ENVIRONMENT_VARIABLES.md b/docs/ENVIRONMENT_VARIABLES.md index 30afeb25e..f63834765 100644 --- a/docs/ENVIRONMENT_VARIABLES.md +++ b/docs/ENVIRONMENT_VARIABLES.md @@ -55,7 +55,12 @@ When using `run_containerized.sh`, these additional variables are available: | Variable | Description | Default | |----------|-------------|---------| | `DOCKER_HOST` | Docker daemon socket path | `/var/run/docker.sock` | -| `DOCKER_API_VERSION` | Docker API version (set by helper scripts, Docker client auto-negotiates) | Set by querying Docker daemon's current API version; falls back to `1.44` if detection fails | + +### Helper/CLI Docker Variables + +| Variable | Description | Default | +|----------|-------------|---------| +| `DOCKER_API_VERSION` | Docker API version used by helper scripts such as `run.sh`, integration test scripts, and `run_containerized.sh`. The Docker Go client in `awmg` auto-negotiates API version, but an exported `DOCKER_API_VERSION` can still affect `docker` CLI subprocesses launched with the inherited environment. | Set by querying Docker daemon's current API version; falls back to `1.44` if detection fails | ## GitHub Authentication diff --git a/internal/config/config_core.go b/internal/config/config_core.go index 1cbd75594..54b8fd8df 100644 --- a/internal/config/config_core.go +++ b/internal/config/config_core.go @@ -252,13 +252,13 @@ type ServerConfig struct { // RateLimitThreshold is the number of consecutive rate-limit errors from this backend // that will trip the circuit breaker (transition CLOSED → OPEN). When OPEN, requests // are immediately rejected until the cooldown period elapses. Default: 3. - // Supported in file-based config (TOML/JSON); stdin JSON config does not currently accept this field. + // Supported in TOML config only; the JSON stdin config does not currently accept this field. RateLimitThreshold int `toml:"rate_limit_threshold" json:"rate_limit_threshold,omitempty"` // RateLimitCooldown is the number of seconds the circuit breaker stays OPEN before // allowing a single probe request (transition OPEN → HALF-OPEN). If the probe // succeeds the circuit closes; if rate-limited again it re-opens. Default: 60. - // Supported in file-based config (TOML/JSON); stdin JSON config does not currently accept this field. + // Supported in TOML config only; the JSON stdin config does not currently accept this field. RateLimitCooldown int `toml:"rate_limit_cooldown" json:"rate_limit_cooldown,omitempty"` }