📚 Documentation Reconciliation Report - 2026-07-02

[github-actions]

Found 1 critical discrepancy and 1 minor clarification between documentation and implementation during nightly reconciliation check.

• Workflow Run: §28626960639
• Date: 2026-07-02
• Branch: main

---

Critical Issues 🔴

1. JSON Stdin Example for gateway.opentelemetry Includes Unsupported headers Field

Location: docs/CONFIGURATION.md, lines 465–479 ("JSON stdin example" block)

Problem: The JSON stdin example shows "headers" as a field inside gateway.opentelemetry:

{
  "gateway": {
    "opentelemetry": {
      "endpoint": "(otelcollector.example.com/redacted)",
      "serviceName": "mcp-gateway",
      "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
      "spanId": "00f067aa0ba902b7",
      "headers": "Authorization=Bearer ..."
    }
  }
}

Actual Behavior: The headers field is not supported in JSON stdin gateway.opentelemetry. The JSON schema (internal/config/schema/mcp-gateway-config.schema.json) defines opentelemetryConfig with "additionalProperties": false and does not include headers. The struct StdinOpenTelemetryConfig (internal/config/config_stdin.go:75-87) has no headers field. A unit test (TestLoadFromStdin_OpenTelemetryHeaders in internal/config/load_from_stdin_coverage_test.go:184-212) explicitly verifies this configuration causes a validation error per spec §4.1.3.7 v1.14.0 Breaking Change. Authentication headers for OTLP export must be provided via the OTEL_EXPORTER_OTLP_HEADERS environment variable.

Impact: Users following this documentation example will get a config validation failure when starting the gateway and will be unable to start it.

Code References:

• Schema: internal/config/schema/mcp-gateway-config.schema.json — opentelemetryConfig definition (additionalProperties: false, no headers property)
• Struct: internal/config/config_stdin.go:74-87 — StdinOpenTelemetryConfig (fields: endpoint, traceId, spanId, serviceName only)
• Test: internal/config/load_from_stdin_coverage_test.go:184-212 — confirms headers in JSON stdin opentelemetry is rejected

Suggested Fix:

1. Remove "headers" from the JSON stdin example in docs/CONFIGURATION.md
2. Add a note after the example:

   Note: The headers field is not supported in JSON stdin gateway.opentelemetry (per spec §4.1.3.6). To pass OTLP export headers when using JSON stdin config, use the OTEL_EXPORTER_OTLP_HEADERS environment variable.

3. In the field table (line 448), annotate headers as TOML-only (similar to how sample_rate is annotated):
   • Before: | headers | Comma-separated key=value HTTP headers... |
   • After: | headers(TOML only) | Comma-separated key=value HTTP headers... UseOTEL_EXPORTER_OTLP_HEADERS env var for JSON stdin configs. |

---

Minor Issues 🔵

2. README.md gateway config table — MCP_GATEWAY_PORT note slightly misleading

Location: README.md, line 187

Current text: "Use the --listen flag or MCP_GATEWAY_PORT env var (containerized) to set the actual listen port."

Problem: This implies the awmg binary reads MCP_GATEWAY_PORT to set its listen address. It does not. The binary only reads MCP_GATEWAY_PORT for --validate-env checks. The wrapper scripts (run.sh, run_containerized.sh) read MCP_GATEWAY_PORT and pass --listen explicitly. docs/ENVIRONMENT_VARIABLES.md describes this correctly.

Impact: Low — a user running awmg directly might set MCP_GATEWAY_PORT expecting automatic listen address configuration.

Suggested Fix: Update to: "Use the --listen flag to set the listen address; MCP_GATEWAY_PORT is used by run.sh/run_containerized.sh to build the --listen argument, not read directly by awmg."

---

Accurate Sections ✅

• Docker Quick Start (README.md) — configuration structure, env vars, and flags correct
• TOML configuration format — field names match ServerConfig struct tags in internal/config/config_core.go
• JSON stdin format — all standard fields correctly described and present in StdinServerConfig
• headers in TOML gateway.opentelemetry — valid; TracingConfig.Headers field exists ✅
• Variable expansion behavior — accurately documented and confirmed in internal/config/expand.go ✅
• All documented env vars in docs/ENVIRONMENT_VARIABLES.md — cross-referenced and accurate ✅
• Go version requirement — CONTRIBUTING.md Go 1.25.0 matches go.mod ✅
• Binary name awmg — consistent across all files ✅
• golangci-lint version — CONTRIBUTING.md v2.8.0 matches Makefile GOLANGCI_LINT_VERSION=v2.8.0 ✅
• All 13 documented make targets exist with matching descriptions ✅
• PayloadPreviewSize default of 500 — confirmed in internal/middleware/jqschema.go:34 ✅
• Example config files — all 4 referenced files exist ✅
• Further Reading — all 10 local docs files in docs/ exist ✅
• rate_limit_threshold/rate_limit_cooldown — correctly documented as TOML-only with defaults matching circuit_breaker.go ✅

Tested Commands

Command	Status
make build	✅ Target defined, binary output awmg
make test	✅ Alias for test-unit
make test-unit	✅ Runs ./internal/...
make test-integration	✅ Auto-builds binary if needed
make test-all	✅ Runs unit + integration
make lint	✅ go vet + gofmt + golangci-lint
make coverage	✅ Unit tests with coverage
make install	✅ Installs golangci-lint + go deps
make clean	✅ Removes build artifacts
make format	✅ gofmt -w
make test-race	✅ Race detector
make test-rust	✅ Gracefully skips if cargo absent
make test-ci	✅ JSON output for CI

Build was not executed in this run — network restrictions prevent go mod download. Targets were verified via dry-run and Makefile inspection.

Warning

Firewall blocked 2 domains

The following domains were blocked by the firewall during workflow execution:

• awmgmcpg
• proxy.golang.org

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

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

See Network Configuration for more information.

Generated by Nightly Documentation Reconciler · 427.5 AIC · ⊞ 4.4K · ◷

• expires on Jul 5, 2026, 11:17 PM UTC