📚 Documentation Reconciliation Report - 2026-06-06

[github-actions]

Summary

Found 2 discrepancies and 1 clarification opportunity during the nightly documentation reconciliation check.

• Workflow Run: §27076309516
• Date: 2026-06-06
• Branch: main

Note: make build could not be executed in this environment due to network restrictions preventing Go module downloads. All other checks were performed via static code analysis.

---

Important Issues 🟡

Issues that are misleading but have workarounds:

1. README.md: port field described as "Listen port" — it is metadata-only

Location: README.md, Gateway Configuration table

Problem: The Gateway Configuration table says:

| `port` | Listen port |

This implies the port config field controls which port the server listens on.

Actual Behavior: The port field is validated for range (1–65535) and stored for metadata purposes only. It does not set the listen address. The actual listen address comes from:

• The --listen CLI flag (default: 127.0.0.1:3000 for direct binary)
• run_containerized.sh reads MCP_GATEWAY_PORT and passes --listen ${HOST}:${PORT} to awmg

Impact: A user who sets "gateway": {"port": 8080} in their JSON config (or port = 8080 in TOML) expecting the server to listen on 8080 will be confused when the server still listens on the default 3000.

Code References:

• internal/config/validation.go:381-383 — only validates range, never sets listen address
• internal/cmd/root.go — uses listenAddr from --listen flag exclusively; cfg.Gateway.Port is never read
• internal/cmd/flags_core.go — --listen flag default: 127.0.0.1:3000

Correct Documentation (already exists elsewhere):

• config.example.toml says: "This field is parsed and validated but does NOT control the actual listen port. To change the listen port, use the --listen flag."
• docs/CONFIGURATION.md:429 says: "Validated and stored for metadata purposes only. The actual listen address is always set by the --listen CLI flag (default 127.0.0.1:3000)."

Suggested Fix: Update README.md Gateway Configuration table:

| `port` | Metadata only; validated (1–65535) but does not control the listen address. Use `--listen` flag or `MCP_GATEWAY_PORT` (containerized) to set the actual listen port. |

---

Minor Issues 🔵

Small inconsistencies or missing details:

2. docs/CONFIGURATION.md: Incorrect claim that [gateway.tracing] supports ${VAR} expansion

Location: docs/CONFIGURATION.md, line 413

Problem: The file says:

Variable expansion with ${VAR_NAME} is only supported in [gateway.opentelemetry] and legacy [gateway.tracing] fields

This implies both sections support variable expansion.

Actual Behavior: Only [gateway.opentelemetry] fields are expanded. The legacy [gateway.tracing] section does not get variable expansion.

Code Reference:

• internal/config/config_core.go:474-488 — expandTracingVariables() is called only when cfg.Gateway.Opentelemetry != nil; no expansion is performed for the legacy Tracing field

Correct Documentation (already exists elsewhere):

• config.example.toml:254-255 says: "The [gateway.opentelemetry] section supports ${VAR_NAME} expansion; the legacy [gateway.tracing] section does not"
• CONTRIBUTING.md:690-691 says: "${VAR} expansion supported only in [gateway.opentelemetry] section fields"

Suggested Fix: Update docs/CONFIGURATION.md:413:

- Variable expansion with `${VAR_NAME}` is only supported in `[gateway.opentelemetry]` fields (the legacy `[gateway.tracing]` section does **not** support variable expansion)

3. README.md: Ambiguous "forwarded as-is" description for MCP methods

Location: README.md, API Endpoints section

Problem: The file says:

Supported MCP methods: tools/list, tools/call, and any other method (forwarded as-is).

The phrase "forwarded as-is" could be misinterpreted to mean the gateway proxies arbitrary MCP methods (e.g. resources/list, prompts/get) to backend servers.

Actual Behavior: Only tools/list and tools/call cause the gateway to call backend MCP servers. All other methods are handled by the go-sdk server natively (returning empty results or SDK-level errors) and are not proxied to backends.

Code Reference:

• internal/mcp/connection_methods.go:13-29 — method dispatch switch covers only tools/list, tools/call, resources/list, resources/read, prompts/list, prompts/get; unknown methods return "unsupported method" error
• internal/server/unified.go:170-203 — only registers tool handlers on the SDK server

Suggested Fix: Clarify what "forwarded as-is" means:

Supported MCP methods: `tools/list`, `tools/call` (proxied to backend servers), plus standard lifecycle methods (`initialize`, etc.) handled natively by the MCP SDK.

---

Accurate Sections ✅

• Makefile targets (make build, test, test-unit, test-integration, test-all, lint, coverage, install, test-race, test-rust, format, clean, agent-finished) — all exist and are correctly described
• Go version (1.25.0) in CONTRIBUTING.md matches go.mod
• Binary name (awmg) matches Makefile and code
• CLI flags (--config, --config-stdin, --listen, --routed, --unified, --env, --validate-env, -v/-vv/-vvv, --log-dir, --payload-dir, --payload-size-threshold, --sequential-launch, --otlp-endpoint, --otlp-sample-rate) — all verified present in code
• Internal package directories — all 23 listed in CONTRIBUTING.md match actual internal/ directory
• Default listen addresses — 127.0.0.1:3000 (direct binary) and 0.0.0.0:8000 (via run.sh) match code
• Docker API fallback — 1.44 for all architectures matches run_containerized.sh:276-280
• Required container env vars (MCP_GATEWAY_PORT, MCP_GATEWAY_DOMAIN, MCP_GATEWAY_API_KEY) match run_containerized.sh
• TOML command field vs JSON stdin container field — correctly documented and enforced
• TOML ${VAR} expansion — CONTRIBUTING.md correctly limits expansion to [gateway.opentelemetry] fields only
• Dependencies list in CONTRIBUTING.md matches go.mod
• All referenced doc files (docs/CONFIGURATION.md, docs/ENVIRONMENT_VARIABLES.md, docs/PROXY_MODE.md, etc.) exist
• Proxy mode (awmg proxy) flags (--guard-wasm, --policy, --github-token, --listen) match code
• Port validation range (1–65535) matches code
• local type alias for stdio confirmed in validation code
• run_containerized.sh auto-adds --config-stdin as documented in README

Tested Commands

Command	Status	Notes
make --dry-run build	✅ Verified	Target exists, correct description
make --dry-run test	✅ Verified	Alias for test-unit
make --dry-run test-unit	✅ Verified	Runs ./internal/...
make --dry-run test-integration	✅ Verified	Builds binary if needed
make --dry-run test-all	✅ Verified	Builds + runs ./...
make --dry-run lint	✅ Verified	go vet + gofmt + golangci-lint
make --dry-run coverage	✅ Verified	Unit tests with coverage
make --dry-run install	✅ Verified	Go check + golangci-lint install
make build	⚠️ Skipped	Network restricted (Go modules unavailable in sandbox)

Code References

• Configuration structs: internal/config/config_core.go, internal/config/config_stdin.go
• Variable expansion: internal/config/config_tracing.go:74-112
• Port validation: internal/config/validation.go:381-383
• Listen address: internal/cmd/flags_core.go, internal/cmd/root.go
• MCP method dispatch: internal/mcp/connection_methods.go
• Server tool registration: internal/server/unified.go, internal/server/routed.go

Warning

Firewall blocked 1 domain

The following domain was blocked by the firewall during workflow execution:

• proxy.golang.org

To allow these domains, add them to the network.allowed list in your workflow frontmatter:

network:
  allowed:
    - defaults
    - "proxy.golang.org"

See Network Configuration for more information.

Generated by Nightly Documentation Reconciler · sonnet46 7.5M · ◷

• expires on Jun 9, 2026, 11:17 PM UTC