📚 Documentation Reconciliation Report - 2026-04-07

[github-actions]

Summary

Found 2 documentation gaps between docs/CONFIGURATION.md / config.example.toml and the current implementation during nightly reconciliation.

• Workflow Run: §24063136754
• Date: 2026-04-07
• Branch: main

---

Critical Issues 🔴

None found.

---

Important Issues 🟡

None found.

---

Minor Issues 🔵

1. keepalive_interval / keepaliveInterval config field is undocumented

Location: docs/CONFIGURATION.md (Gateway Configuration Fields table, ~line 363); config.example.toml (header claims "all available configuration options")

Problem: The keepalive_interval (TOML) / keepaliveInterval (JSON) gateway configuration field is fully implemented but absent from all user-facing documentation, including docs/CONFIGURATION.md, config.example.toml, README.md, and AGENTS.md.

Actual Behavior: When set, this integer field controls the interval (in seconds) between keepalive pings sent to HTTP backends to prevent their idle-timeout from expiring. Default is 1500 (25 minutes). Set to -1 to disable keepalives entirely.

Impact: Users with HTTP-backend MCP servers that have custom idle timeouts shorter than 25 minutes cannot discover or configure this field. Users who set -1 to let a higher-level timeout manage sessions cannot discover that option. The config.example.toml incorrectly claims completeness.

Suggested Fix:

Add to the Gateway Configuration Fields table in docs/CONFIGURATION.md:

| `keepaliveInterval` (JSON) / `keepalive_interval` (TOML) | Interval (seconds) between keepalive pings sent to HTTP backends. Prevents remote servers from expiring idle sessions. Set to `-1` to disable keepalives entirely. | `1500` (25 min) |

Add to config.example.toml under [gateway]:

# Keepalive interval (seconds) for HTTP backends (default: 1500 = 25 minutes)
# Set to -1 to disable keepalive pings entirely
# keepalive_interval = 1500

Code Reference: internal/config/config_core.go:95-98 (KeepaliveInterval field and comment), internal/config/config_core.go:139-143 (HTTPKeepaliveInterval() method)

---

2. opentelemetry / tracing gateway configuration fields are undocumented in docs/CONFIGURATION.md

Location: docs/CONFIGURATION.md (Gateway Configuration Fields table)

Problem: The opentelemetry (preferred TOML/JSON key per spec §4.1.3.6) and tracing (legacy TOML key) gateway configuration blocks are fully implemented with sub-fields endpoint, headers, traceId, spanId, and serviceName, but the Gateway Configuration Fields table in docs/CONFIGURATION.md does not document them at all.

docs/ENVIRONMENT_VARIABLES.md documents the OTEL_* env vars for CLI flags, but the JSON stdin / TOML config format for embedding OpenTelemetry settings is absent from docs/CONFIGURATION.md.

Actual Behavior: Users can configure OpenTelemetry tracing via a nested object in both TOML and JSON stdin:

[gateway.opentelemetry]
endpoint = "(otlp.example.com/redacted)"
headers = { Authorization = "Bearer \$\{OTLP_TOKEN}" }

"gateway": {
  "opentelemetry": {
    "endpoint": "(otlp.example.com/redacted)",
    "serviceName": "mcp-gateway",
    "traceId": "...",
    "spanId": "..."
  }
}

Impact: Users wanting to enable OpenTelemetry tracing via the config file (rather than CLI flags) cannot discover the config-level API. The opentelemetry key takes precedence over the legacy tracing key, but neither appears in the configuration reference.

Suggested Fix: Add an "OpenTelemetry / Tracing" subsection to the Gateway Configuration Fields section in docs/CONFIGURATION.md documenting the opentelemetry block fields: endpoint (required, HTTPS), headers (optional map), traceId (optional, 32-char hex), spanId (optional, 16-char hex, ignored without traceId), serviceName (optional, default "mcp-gateway"). Note that the legacy tracing TOML key also works but opentelemetry takes precedence.

Code Reference: internal/config/config_stdin.go:47-63 (StdinOpenTelemetryConfig), internal/config/config_tracing.go (TracingConfig), internal/config/config_core.go:121-131 (GatewayConfig.Tracing and .Opentelemetry)

---

Documentation Completeness

Missing Documentation

• keepalive_interval / keepaliveInterval gateway field — implemented but undocumented in docs/CONFIGURATION.md and config.example.toml
• opentelemetry / tracing gateway configuration block — implemented but absent from docs/CONFIGURATION.md gateway fields table

Accurate Sections ✅

• README Quick Start — Docker run command, JSON config format, env vars all verified accurate
• README Guard Policies — allow-only and write-sink fields verified against code
• CONTRIBUTING.md Prerequisites — Go version (1.25.0) matches go.mod
• CONTRIBUTING.md Make Targets — All 8 documented targets (build, test, test-unit, test-integration, test-all, lint, coverage, install) verified in Makefile
• CONTRIBUTING.md Binary Name — awmg matches Makefile BINARY_NAME
• CONTRIBUTING.md Advanced Flags — --log-dir, --env, --payload-dir, --payload-size-threshold all verified in internal/cmd/flags*.go
• CONTRIBUTING.md Project Structure — All 21 internal packages listed match actual internal/ directory
• CONTRIBUTING.md Dependencies — All 8 listed packages (cobra, toml, go-sdk, gojq, jsonschema, testify, wazero, opentelemetry) verified in go.mod
• JSON stdin format — type, container, entrypoint, entrypointArgs, mounts, env, guard-policies fields all verified in StdinServerConfig
• TOML format — command = "docker" requirement verified in validation code
• Auth header format — Plain API key (not Bearer) confirmed in spec and implementation
• Default listen port — 3000 confirmed in internal/cmd/root.go:33
• Session timeout default — 6h confirmed in internal/server/transport.go:41
• Environment variables — All vars in docs/ENVIRONMENT_VARIABLES.md verified against code
• tools field note — Correctly documented as "stored but not enforced at runtime"
• working_directory note — Correctly documented as "TOML-only, not yet implemented in launcher"

Tested Commands

• ✅ make --dry-run build — target exists, builds awmg binary
• ✅ make --dry-run test — alias for test-unit, confirmed in Makefile
• ✅ make --dry-run test-unit — runs go test ./internal/...
• ✅ make --dry-run test-integration — auto-builds binary if not present
• ✅ make --dry-run test-all — depends on build, runs all tests
• ✅ make --dry-run lint — runs go vet, gofmt, golangci-lint
• ✅ make --dry-run coverage — runs unit tests with coverage
• ✅ make --dry-run install — checks Go version, installs golangci-lint, downloads deps

Recommendations

Immediate Actions Required

None. All documented workflows work correctly.

Nice to Have

1. Add keepalive_interval to docs/CONFIGURATION.md Gateway Fields table and config.example.toml
2. Add opentelemetry / tracing block documentation to docs/CONFIGURATION.md

Code References

• Gateway config struct: internal/config/config_core.go
• JSON stdin config: internal/config/config_stdin.go
• Tracing config: internal/config/config_tracing.go
• CLI flags: internal/cmd/flags*.go
• Validation: internal/config/validation.go

Generated by Nightly Documentation Reconciler · ● 3.7M · ◷

• expires on Apr 10, 2026, 3:52 AM UTC