📚 Documentation Reconciliation Report - 2026-04-01 #2981
Description
Summary
Nightly documentation reconciliation audit found 1 important undocumented feature and 1 minor gap against the current main branch implementation. The core documentation (Quick Start, build commands, project structure) is accurate and working.
- Workflow Run: §23831043886
- Date: 2026-04-01
- Branch: main
Critical Issues 🔴
None found. All documented instructions are accurate and functional.
Important Issues 🟡
1. GitHub OIDC Authentication for HTTP Servers Not Documented
Location: docs/CONFIGURATION.md (Server Configuration Fields section), docs/ENVIRONMENT_VARIABLES.md
Problem: The auth field for HTTP MCP backend servers (enabling github-oidc authentication) is fully implemented in the codebase but is not mentioned anywhere in user-facing documentation.
Actual Behavior: HTTP servers support an auth field with type: "github-oidc" and optional audience to automatically obtain OIDC tokens from GitHub Actions and attach them as Authorization: Bearer <token> headers. When configured, the launcher reads ACTIONS_ID_TOKEN_REQUEST_URL and ACTIONS_ID_TOKEN_REQUEST_TOKEN from the environment (set automatically by GitHub Actions when permissions: { id-token: write } is granted).
Code References:
internal/config/config_stdin.go:102—Auth *AuthConfig \json:"auth,omitempty"``internal/config/validation.go:165-210—validateAuthConfig(onlygithub-oidcis currently supported)internal/launcher/launcher.go:67-137— OIDC provider initialization and per-server auth assignmentinternal/oidc/provider.go— OIDC token provider implementation
Impact: Users who deploy HTTP MCP backends requiring OIDC JWT authentication in GitHub Actions cannot discover this feature without reading the source code.
Suggested Fix for docs/CONFIGURATION.md (add to Server Configuration Fields section):
- **`auth`** (optional, HTTP servers only): Upstream authentication configuration
- Only supported for `type: "http"` servers; using `auth` with stdio servers returns a validation error
- Currently supports one `type`:
- `"github-oidc"` — Obtains a GitHub Actions OIDC token and attaches it as `Authorization: Bearer <token>` on every request to the HTTP backend. Requires the GitHub Actions job to have `permissions: { id-token: write }`.
- **`audience`** (optional): OIDC token audience. Defaults to the server's `url` value.
- Example:
```json
"my-http-server": {
"type": "http",
"url": "(myinternalservice.example.com/redacted),
"auth": {
"type": "github-oidc",
"audience": "(myinternalservice.example.com/redacted)"
}
}
```Suggested Fix for docs/ENVIRONMENT_VARIABLES.md (add a new section or table row):
Add to the "Proxy Mode Variables" or create a new "GitHub Actions OIDC Variables" section:
| Variable | Description | Default |
|---|---|---|
ACTIONS_ID_TOKEN_REQUEST_URL |
GitHub Actions OIDC token endpoint (set automatically by GitHub Actions runner when permissions: { id-token: write } is granted). Required when any HTTP server uses auth.type = "github-oidc". |
(set by GitHub Actions) |
ACTIONS_ID_TOKEN_REQUEST_TOKEN |
GitHub Actions OIDC bearer token used to authenticate the token request (set automatically by GitHub Actions runner). Used alongside ACTIONS_ID_TOKEN_REQUEST_URL. |
(set by GitHub Actions) |
Minor Issues 🔵
2. Several CLI Flags Not Mentioned in CONTRIBUTING.md or README.md
Location: CONTRIBUTING.md (Running Locally section)
Problem: The following flags are implemented and used in common workflows, but are not shown in any awmg usage examples in CONTRIBUTING.md or README.md:
| Flag | Env Var | Description |
|---|---|---|
--env <file> |
— | Load environment variables from a .env file |
--verbose / -v |
DEBUG |
Increase verbosity (can be passed multiple times) |
--log-dir <dir> |
MCP_GATEWAY_LOG_DIR |
Directory for log files |
--payload-dir <dir> |
MCP_GATEWAY_PAYLOAD_DIR |
Directory for large payload storage |
--payload-path-prefix |
MCP_GATEWAY_PAYLOAD_PATH_PREFIX |
Client-visible path prefix for payload files |
--payload-size-threshold |
MCP_GATEWAY_PAYLOAD_SIZE_THRESHOLD |
Byte threshold above which payloads are written to disk |
Code Reference: internal/cmd/flags_core.go, internal/cmd/flags_logging.go
Impact: These flags are documented in docs/ENVIRONMENT_VARIABLES.md and AGENTS.md, but a developer reading only CONTRIBUTING.md would not know about them.
Suggested Fix: Add an "Advanced Flags" subsection to the "Running Locally" section in CONTRIBUTING.md:
### Advanced Flags
```bash
# Custom log directory
./awmg --config config.toml --log-dir /path/to/logs
# Load environment file
./awmg --config config.toml --env .env
# Increase verbosity
./awmg --config config.toml -v
# Custom payload directory and size threshold
./awmg --config config.toml --payload-dir /tmp/payloads --payload-size-threshold 1048576See docs/ENVIRONMENT_VARIABLES.md for the full list of environment variable overrides.
## Documentation Completeness
### Missing Documentation
- `auth` field (HTTP server OIDC configuration) — implemented, not documented
- `ACTIONS_ID_TOKEN_REQUEST_URL` / `ACTIONS_ID_TOKEN_REQUEST_TOKEN` — used by launcher, not listed in `docs/ENVIRONMENT_VARIABLES.md`
- Several runtime flags missing from `CONTRIBUTING.md` examples
### Accurate Sections ✅
- README.md Quick Start (Docker command, JSON config format, required flags) — verified accurate
- README.md Guard Policies (`allow-only`, `write-sink`) — verified against code
- README.md Proxy Mode (`awmg proxy`) — command exists
- CONTRIBUTING.md make targets (`build`, `test`, `test-unit`, `test-integration`, `test-all`, `lint`, `coverage`, `test-ci`, `format`, `clean`, `install`) — all exist in Makefile with correct descriptions
- CONTRIBUTING.md Go version (`1.25.0`) — matches `go.mod`
- CONTRIBUTING.md binary name (`awmg`) — matches Makefile `BINARY_NAME`
- CONTRIBUTING.md project structure — all listed `internal/` packages exist in codebase
- CONTRIBUTING.md default port (3000 for binary, 8000 for Docker/`run.sh`) — correctly documented
- CONTRIBUTING.md Docker development section — verified against Dockerfile and `run_containerized.sh`
- Variable expansion `\$\{VAR_NAME}` syntax — JSON stdin format only, TOML is accurately noted as not supporting expansion
## Tested Commands
- ✅ `make --dry-run build` — target exists, runs `go build -o awmg .`
- ✅ `make --dry-run test` — alias for `test-unit`
- ✅ `make --dry-run test-unit` — runs `go test -v ./internal/...`
- ✅ `make --dry-run test-integration` — auto-builds binary if needed
- ✅ `make --dry-run test-all` — runs unit + integration
- ✅ `make --dry-run lint` — runs go vet, gofmt check, golangci-lint
- ✅ `make --dry-run coverage` — runs unit tests with coverage report
- ✅ `make --dry-run install` — installs Go dependencies and golangci-lint
- ⚠️ `make build` — **could not execute**: environment has Go 1.24.13 but `go.mod` requires 1.25.0; documentation correctly states this requirement
## Code References
- `auth` field implementation: `internal/config/config_stdin.go:102`, `internal/config/validation.go:165-210`
- OIDC provider: `internal/launcher/launcher.go:67-137`, `internal/oidc/provider.go`
- Flag definitions: `internal/cmd/flags_core.go`, `internal/cmd/flags_logging.go`
- Env var helpers: `internal/config/config_env.go`
> Generated by [Nightly Documentation Reconciler](https://github.com/github/gh-aw-mcpg/actions/runs/23831043886/agentic_workflow) · [◷](https://github.com/search?q=repo%3Agithub%2Fgh-aw-mcpg+is%3Aissue+%22gh-aw-workflow-call-id%3A+github%2Fgh-aw-mcpg%2Fnightly-docs-reconciler%22&type=issues)
> - [x] expires <!-- gh-aw-expires: 2026-04-04T04:00:01.298Z --> on Apr 4, 2026, 4:00 AM UTC
<!-- gh-aw-agentic-workflow: Nightly Documentation Reconciler, engine: copilot, model: auto, id: 23831043886, workflow_id: nightly-docs-reconciler, run: https://github.com/github/gh-aw-mcpg/actions/runs/23831043886 -->
<!-- gh-aw-workflow-id: nightly-docs-reconciler -->
<!-- gh-aw-workflow-call-id: github/gh-aw-mcpg/nightly-docs-reconciler -->