From c1e39011bf25045c06559cfdb63b388b8dbefb97 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 20 Jul 2026 23:32:02 +0000 Subject: [PATCH 1/4] Initial plan From 630b0f115f845361c856d7ec021281f731afc64b Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 20 Jul 2026 23:35:54 +0000 Subject: [PATCH 2/4] docs: reconcile README and CONTRIBUTING with current runtime options --- CONTRIBUTING.md | 16 +++++++++++++--- README.md | 22 ++++++++++++++++------ 2 files changed, 29 insertions(+), 9 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6ddcb8a03..2ca5aa387 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -95,11 +95,21 @@ make test-integration # Automatically builds binary if needed ``` #### Run All Tests -Run both unit and integration tests (always rebuilds the binary first): +Run both unit and integration tests (depends on `build`, so `make` may skip rebuilding when already up to date): ```bash make test-all ``` +#### Common Maintenance Targets +```bash +make format # Auto-format Go code +make clean # Remove build artifacts and generated test outputs +make agent-finished # Format + build + lint + tests (recommended before submitting) +make help # Show all available targets +``` + +Use `make release patch|minor|major` to trigger the automated release workflow. + #### Rust Guard Tests Run Rust guard unit tests (requires `cargo`): ```bash @@ -167,7 +177,7 @@ Start the server with: ./run.sh ``` -This will start MCPG in routed mode on `http://0.0.0.0:8000` (using the defaults from `run.sh`). +This will start MCP Gateway in routed mode on `http://0.0.0.0:8000` (using the defaults from `run.sh`). Or run manually: ```bash @@ -204,7 +214,7 @@ See [docs/ENVIRONMENT_VARIABLES.md](docs/ENVIRONMENT_VARIABLES.md) for the full ### Testing with Codex -You can test MCPG with Codex (in another terminal): +You can test MCP Gateway with Codex (in another terminal): ```bash cp ~/.codex/config.toml ~/.codex/config.toml.bak && cp agent-configs/codex.config.toml ~/.codex/config.toml AGENT_ID=demo-agent codex diff --git a/README.md b/README.md index ee72a27d9..66c4b6310 100644 --- a/README.md +++ b/README.md @@ -15,6 +15,8 @@ This gateway is used with [GitHub Agentic Workflows](https://github.com/github/g ```json { "gateway": { + "port": 8000, + "domain": "${MCP_GATEWAY_DOMAIN}", "agentId": "${MCP_GATEWAY_AGENT_ID}" }, "mcpServers": { @@ -55,26 +57,33 @@ Inside the container, the gateway starts in routed mode on `http://0.0.0.0:8000` - If you configure `payloadDir` / `MCP_GATEWAY_PAYLOAD_DIR`, use an absolute path (for example `/tmp/jq-payloads`) - If you configure `payloadDir`, you can also tune `payloadSizeThreshold` / `MCP_GATEWAY_PAYLOAD_SIZE_THRESHOLD` to control when payloads are written to disk (default: `524288` bytes) -When running `awmg` directly (outside `docker run`), useful CLI flags include: -- `--config-stdin`: Read JSON config from stdin (required when piping config, e.g. `cat config.json | awmg --config-stdin --routed`). - - For backward compatibility, JSON stdin also accepts legacy snake_case server timeout aliases: `connect_timeout` and `tool_timeout` (prefer `connectTimeout` and `toolTimeout`). -- `--env `: Load environment variables from a `.env` file before startup. -- `-v`, `-vv`, `-vvv`: Increase verbosity (`info`, `debug`, `trace`). +When running `awmg` directly (outside `docker run`), key CLI flags include: +- Configuration/runtime: `--config` (`-c`), `--config-stdin`, `--env`, `--listen` (`-l`), `--routed`, `--unified`, `--validate-env`, `--sequential-launch`, and `-v`/`-vv`/`-vvv`. +- Logging/payload/shutdown: `--log-dir`, `--payload-dir`, `--payload-path-prefix`, `--payload-size-threshold`, `--wasm-cache-dir`, `--url-domain-audit`, `--shutdown-timeout`. +- Guards/security: `--guards-mode`, `--guards-sink-server-ids`, `--guard-policy-json`, `--allowonly-scope-public`, `--allowonly-scope-owner`, `--allowonly-scope-repo`, `--allowonly-min-integrity`, `--tls-cert`, `--tls-key`, `--tls-ca`, `--hmac-secret`. +- Tracing: `--otlp-endpoint`, `--otlp-service-name`, `--otlp-sample-rate`. +- For backward compatibility, JSON stdin also accepts legacy snake_case server timeout aliases: `connect_timeout` and `tool_timeout` (prefer `connectTimeout` and `toolTimeout`). +- Run `./awmg --help` for the full authoritative flag list. - A complete reference for all environment variables — including guard policy, TLS, tracing, authentication tokens, and containerized deployment — is in [docs/ENVIRONMENT_VARIABLES.md](docs/ENVIRONMENT_VARIABLES.md). Common operational environment variables include: +- `MCP_GATEWAY_PORT` — used by `--validate-env` container checks (must be 1-65535) - `MCP_GATEWAY_DOMAIN` — gateway domain used by containerized startup checks and commonly referenced from config +- `GITHUB_API_URL`, `GITHUB_SERVER_URL` — explicit/derived GitHub API endpoint selection for proxy mode - `MCP_GATEWAY_LOG_DIR` — log file directory (default: `/tmp/gh-aw/mcp-logs`) - `MCP_GATEWAY_PAYLOAD_DIR` — large payload storage directory (must be absolute path; default: `/tmp/jq-payloads`) - `MCP_GATEWAY_PAYLOAD_SIZE_THRESHOLD` — size threshold in bytes for payload storage (default: `524288`) - `MCP_GATEWAY_SESSION_TIMEOUT` — session timeout for stateful unified/routed MCP sessions (default: `6h`) - `MCP_GATEWAY_TOOL_TIMEOUT` — global tool invocation timeout fallback when JSON stdin `gateway.toolTimeout` is not set (built-in default: `60`) - `MCP_GATEWAY_FORCE_PUBLIC_REPOS` — when `true` (default), auto-forces `repos="public"` allow-only policy when workflow repo is public +- `MCP_GATEWAY_GUARDS_MODE`, `MCP_GATEWAY_WASM_GUARDS_DIR` — default guard enforcement mode and per-server WASM guard discovery root +- `MCP_GATEWAY_ALLOWONLY_SCOPE_PUBLIC`, `MCP_GATEWAY_ALLOWONLY_SCOPE_OWNER`, `MCP_GATEWAY_ALLOWONLY_SCOPE_REPO`, `MCP_GATEWAY_ALLOWONLY_MIN_INTEGRITY` — environment defaults for allow-only policy override flags - `MCP_GATEWAY_AGENT_ID` — agent identifier for env validation and containerized startup checks -- `MCP_GATEWAY_API_KEY` — *deprecated alias for `MCP_GATEWAY_AGENT_ID`*; still accepted with a deprecation warning, prefer `MCP_GATEWAY_AGENT_ID` +- `MCP_GATEWAY_API_KEY` — *deprecated alias for `MCP_GATEWAY_AGENT_ID`*; still accepted with a deprecation warning, prefer `MCP_GATEWAY_AGENT_ID`. When both are set, `MCP_GATEWAY_AGENT_ID` takes precedence. - `ACTIONS_ID_TOKEN_REQUEST_URL`, `ACTIONS_ID_TOKEN_REQUEST_TOKEN` — required for `github-oidc` auth type (set automatically by GitHub Actions) - `DOCKER_HOST` — Docker daemon socket path (default: `/var/run/docker.sock`) - `RUNNING_IN_CONTAINER` — set to `"true"` to force container detection when `/.dockerenv` and cgroup detection are unavailable +- `OTEL_EXPORTER_OTLP_HEADERS`, `GH_AW_OTLP_ENDPOINTS` — tracing export headers and multi-endpoint OTLP fan-out - `MCP_GATEWAY_SHUTDOWN_TIMEOUT` - `MCP_GATEWAY_WASM_CACHE_DIR` - `MCP_GATEWAY_PAYLOAD_PATH_PREFIX` @@ -220,6 +229,7 @@ Key configuration fields (gateway-level under `[gateway]` in TOML / `"gateway"` | `customSchemas` (JSON stdin top-level) | Map custom server `type` names to HTTPS JSON schema URLs for custom server validation | For the full gateway field list (including rate limiting, tracing, keepalive, and more), see **[docs/CONFIGURATION.md](docs/CONFIGURATION.md)**. +For the full server field list (including TOML-only fields such as `working_directory`, `rate_limit_threshold`, and `rate_limit_cooldown`), also see **[docs/CONFIGURATION.md](docs/CONFIGURATION.md)**. ## Architecture From 1d1baaea6935f1b4992198ac9f9785de8eb9d30f Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 20 Jul 2026 23:41:52 +0000 Subject: [PATCH 3/4] docs: clarify schema requirements and test-all rebuild wording --- CONTRIBUTING.md | 2 +- README.md | 16 ++++++++++------ 2 files changed, 11 insertions(+), 7 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2ca5aa387..54a316a51 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -95,7 +95,7 @@ make test-integration # Automatically builds binary if needed ``` #### Run All Tests -Run both unit and integration tests (depends on `build`, so `make` may skip rebuilding when already up to date): +Run both unit and integration tests (rebuilds binary only if source has changed since last build): ```bash make test-all ``` diff --git a/README.md b/README.md index 66c4b6310..8ef64c5b6 100644 --- a/README.md +++ b/README.md @@ -31,6 +31,8 @@ This gateway is used with [GitHub Agentic Workflows](https://github.com/github/g } ``` + Note: In JSON stdin config, `gateway.port` and `gateway.domain` are schema-required fields. + Looking for complete examples? See [`config.example.toml`](config.example.toml), [`config.example-payload-threshold.toml`](config.example-payload-threshold.toml), and [`example-http-config.json`](example-http-config.json). 3. **Run the container**: @@ -57,11 +59,13 @@ Inside the container, the gateway starts in routed mode on `http://0.0.0.0:8000` - If you configure `payloadDir` / `MCP_GATEWAY_PAYLOAD_DIR`, use an absolute path (for example `/tmp/jq-payloads`) - If you configure `payloadDir`, you can also tune `payloadSizeThreshold` / `MCP_GATEWAY_PAYLOAD_SIZE_THRESHOLD` to control when payloads are written to disk (default: `524288` bytes) -When running `awmg` directly (outside `docker run`), key CLI flags include: -- Configuration/runtime: `--config` (`-c`), `--config-stdin`, `--env`, `--listen` (`-l`), `--routed`, `--unified`, `--validate-env`, `--sequential-launch`, and `-v`/`-vv`/`-vvv`. -- Logging/payload/shutdown: `--log-dir`, `--payload-dir`, `--payload-path-prefix`, `--payload-size-threshold`, `--wasm-cache-dir`, `--url-domain-audit`, `--shutdown-timeout`. -- Guards/security: `--guards-mode`, `--guards-sink-server-ids`, `--guard-policy-json`, `--allowonly-scope-public`, `--allowonly-scope-owner`, `--allowonly-scope-repo`, `--allowonly-min-integrity`, `--tls-cert`, `--tls-key`, `--tls-ca`, `--hmac-secret`. -- Tracing: `--otlp-endpoint`, `--otlp-service-name`, `--otlp-sample-rate`. +When running `awmg` directly (outside `docker run`), commonly used CLI flags include: +- Configuration input: `--config` (`-c`), `--config-stdin`, `--env` (config source and env file loading). +- Runtime mode/networking: `--listen` (`-l`), `--routed`, `--unified`, `--validate-env`, `--sequential-launch` (serve mode, address, and startup checks). +- Observability: `-v`/`-vv`/`-vvv` (log verbosity). +- Logging/payload/shutdown: `--log-dir`, `--payload-dir`, `--payload-path-prefix`, `--payload-size-threshold`, `--wasm-cache-dir`, `--url-domain-audit`, `--shutdown-timeout` (runtime file/log and graceful-shutdown behavior). +- Guards/security: `--guards-mode`, `--guards-sink-server-ids`, `--guard-policy-json`, `--allowonly-scope-public`, `--allowonly-scope-owner`, `--allowonly-scope-repo`, `--allowonly-min-integrity`, `--tls-cert`, `--tls-key`, `--tls-ca`, `--hmac-secret` (DIFC policy and transport security). +- Tracing: `--otlp-endpoint`, `--otlp-service-name`, `--otlp-sample-rate` (OpenTelemetry export settings). - For backward compatibility, JSON stdin also accepts legacy snake_case server timeout aliases: `connect_timeout` and `tool_timeout` (prefer `connectTimeout` and `toolTimeout`). - Run `./awmg --help` for the full authoritative flag list. - A complete reference for all environment variables — including guard policy, TLS, tracing, authentication tokens, and containerized deployment — is in [docs/ENVIRONMENT_VARIABLES.md](docs/ENVIRONMENT_VARIABLES.md). @@ -79,7 +83,7 @@ Common operational environment variables include: - `MCP_GATEWAY_GUARDS_MODE`, `MCP_GATEWAY_WASM_GUARDS_DIR` — default guard enforcement mode and per-server WASM guard discovery root - `MCP_GATEWAY_ALLOWONLY_SCOPE_PUBLIC`, `MCP_GATEWAY_ALLOWONLY_SCOPE_OWNER`, `MCP_GATEWAY_ALLOWONLY_SCOPE_REPO`, `MCP_GATEWAY_ALLOWONLY_MIN_INTEGRITY` — environment defaults for allow-only policy override flags - `MCP_GATEWAY_AGENT_ID` — agent identifier for env validation and containerized startup checks -- `MCP_GATEWAY_API_KEY` — *deprecated alias for `MCP_GATEWAY_AGENT_ID`*; still accepted with a deprecation warning, prefer `MCP_GATEWAY_AGENT_ID`. When both are set, `MCP_GATEWAY_AGENT_ID` takes precedence. +- `MCP_GATEWAY_API_KEY` — *deprecated alias for `MCP_GATEWAY_AGENT_ID`*; still accepted with a deprecation warning (lower precedence when both are set). - `ACTIONS_ID_TOKEN_REQUEST_URL`, `ACTIONS_ID_TOKEN_REQUEST_TOKEN` — required for `github-oidc` auth type (set automatically by GitHub Actions) - `DOCKER_HOST` — Docker daemon socket path (default: `/var/run/docker.sock`) - `RUNNING_IN_CONTAINER` — set to `"true"` to force container detection when `/.dockerenv` and cgroup detection are unavailable From 8231f0e7daf3c9bc563e57617d7e4019bbd9bd5b Mon Sep 17 00:00:00 2001 From: Landon Cox Date: Mon, 20 Jul 2026 16:46:21 -0700 Subject: [PATCH 4/4] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 54a316a51..024b94b1f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -95,7 +95,7 @@ make test-integration # Automatically builds binary if needed ``` #### Run All Tests -Run both unit and integration tests (rebuilds binary only if source has changed since last build): +Run both unit and integration tests (always rebuilds the binary first): ```bash make test-all ```