Fix documentation discrepancies in CONTRIBUTING.md and README.md

[Claude]

Reconciles documentation with actual implementation after nightly documentation checker identified 4 discrepancies between docs and code.

Critical Fixes

Docker container section - Updated CONTRIBUTING.md to reflect actual entrypoint and requirements:

• Changed run.sh → run_containerized.sh (actual entrypoint in Dockerfile:41)
• Added -i flag requirement for stdin configuration
• Added required env vars: MCP_GATEWAY_PORT, MCP_GATEWAY_DOMAIN, MCP_GATEWAY_API_KEY

Before:

docker run --rm -v $(pwd)/.env:/app/.env \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -p 8000:8000 \
  awmg

After:

docker run --rm -i \
  -e MCP_GATEWAY_PORT=8000 \
  -e MCP_GATEWAY_DOMAIN=localhost \
  -e MCP_GATEWAY_API_KEY=your-secret-key \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -p 8000:8000 \
  awmg < config.json

DOCKER_API_VERSION fallback - Corrected "1.43 for arm64, 1.44 for amd64" → "1.44 for all architectures" (matches run.sh:105-112, run_containerized.sh:240-247)

Minor Fixes

Missing args field - Added to README.md Server Configuration Fields:

• Documents StdinServerConfig.Args (config_stdin.go:50-51)
• Enables Docker runtime args before container image: ["--network", "host"]

Incomplete dependencies - Added missing direct deps to CONTRIBUTING.md:

• github.com/modelcontextprotocol/go-sdk - MCP protocol
• github.com/itchyny/gojq - JQ processing
• github.com/santhosh-tekuri/jsonschema/v5 - validation
• github.com/stretchr/testify - test assertions
• golang.org/x/term - terminal detection

Original prompt

---

This section details on the original issue you should resolve

<issue_title>📚 Documentation Reconciliation Report - 2026-02-20</issue_title>
<issue_description>## Summary

Found 4 discrepancies between documentation and implementation during nightly reconciliation check.

• Workflow Run: §22212520119
• Date: 2026-02-20
• Branch: main

---

Critical Issues 🔴

Issues that would cause user confusion or broken workflows if followed:

1. CONTRIBUTING.md Docker container section describes wrong entrypoint

Location: CONTRIBUTING.md, lines 463–469 (Docker Development → Run Container section)

Problem: The documentation states:

"The container uses run.sh as the entrypoint, which automatically:

• Detects architecture and sets DOCKER_API_VERSION (1.43 for arm64, 1.44 for amd64)
• Loads environment variables from .env
• Starts MCPG in routed mode on port 8000
• Reads configuration from stdin (via heredoc in run.sh)"

Actual Behavior: The Dockerfile uses run_containerized.sh as the entrypoint (not run.sh):

ENTRYPOINT ["/app/run_containerized.sh"]

run_containerized.sh requires:

• stdin to be open (-i flag)
• All three required env vars: MCP_GATEWAY_PORT, MCP_GATEWAY_DOMAIN, MCP_GATEWAY_API_KEY
• JSON configuration piped via stdin (no default heredoc)

Impact: Users following the documented docker run command will get an immediate error because:

• The -i flag is missing
• The required environment variables are not set
• No stdin configuration is provided

Code Reference: Dockerfile:41, run_containerized.sh:109–136, run_containerized.sh:165–183

Suggested Fix:
Update the Docker development section to reflect the actual entrypoint and requirements:

The container uses `run_containerized.sh` as the entrypoint, which:
- Requires the `-i` flag for JSON configuration via stdin
- Requires `MCP_GATEWAY_PORT`, `MCP_GATEWAY_DOMAIN`, `MCP_GATEWAY_API_KEY` env vars
- Queries the Docker daemon API version (falls back to 1.44)
- Validates Docker socket, port mapping, and environment before starting

Update the docker run example to:

docker run --rm -i \
  -e MCP_GATEWAY_PORT=8000 \
  -e MCP_GATEWAY_DOMAIN=localhost \
  -e MCP_GATEWAY_API_KEY=your-secret-key \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -p 8000:8000 \
  awmg < config.json

---

Important Issues 🟡

Issues that are misleading but have workarounds:

2. CONTRIBUTING.md DOCKER_API_VERSION fallback value is incorrect

Location: CONTRIBUTING.md, lines 465–468 (Docker Development section)

Problem: Documentation says DOCKER_API_VERSION is set to "1.43 for arm64, 1.44 for amd64"

Actual Behavior: Both run.sh and run_containerized.sh set the fallback to 1.44 for all architectures:

# In both scripts (fallback branch):
if [ "$arch" = "arm64" ] || [ "$arch" = "aarch64" ]; then
    export DOCKER_API_VERSION=1.44  # NOT 1.43 as documented
else
    export DOCKER_API_VERSION=1.44
fi

Note: The primary path queries the live Docker daemon API version, so the fallback only matters when Docker inspection fails.

Impact: Users expecting 1.43 on arm64 (for compatibility with older Docker) may be confused.

Code Reference: run.sh:105–112, run_containerized.sh:240–247

Suggested Fix: Update the description to say "1.44 for all architectures (fallback)" or simply "queries Docker daemon; falls back to 1.44."

---

Minor Issues 🔵

Small inconsistencies or missing details:

3. README.md missing args field documentation for JSON stdin server config

Location: README.md, "Server Configuration Fields" section

Problem: The StdinServerConfig struct has an undocumented args field:

// Args are additional Docker runtime arguments (passed before container image)
Args []string `json:"args,omitempty"`

Impact: Users cannot discover this advanced feature from the documentation alone.

Code Reference: internal/config/config_stdin.go:51–53

Suggested Fix: Add to the Server Configuration Fields section:

• args (optional): Additional Docker runtime arguments inserted before the container image name (e.g., ["--network", "host"])

4. CONTRIBUTING.md dependencies list is incomplete

Location: CONTRIBUTING.md, lines 372–378 (Dependencies section)

Problem: The listed dependencies are:

• github.com/spf13/cobra
• github.com/BurntSushi/toml
• Standard library for JSON, HTTP, exec

Actual dependencies (from go.mod):

• github.com/spf13/cobra ✅
• github.com/BurntSushi/toml ✅
• github.com/modelcontextprotocol/go-sdk — MCP protocol implementation (missing)
• github.com/itchyny/gojq — JQ schema processing (missing)
• github.com/santhosh-tekuri/jsonschema/v5 — JSON schema validation (missing)
• github.com/stretchr/testify — Test assertions (missing)
• golang.org/x/term —...

• Fixes 📚 Documentation Reconciliation Report - 2026-02-20 #1164

[Copilot]

Pull request overview

This PR reconciles documentation with actual implementation after a nightly documentation checker identified 4 discrepancies. The changes correct critical errors in the Docker container usage instructions and add missing documentation for configuration fields and dependencies.

Changes:

• Fixed CONTRIBUTING.md Docker container section to reference correct entrypoint (run_containerized.sh instead of run.sh) and document required -i flag and environment variables
• Corrected DOCKER_API_VERSION fallback documentation (1.44 for all architectures, not 1.43 for arm64)
• Added missing args field documentation to README.md Server Configuration Fields section
• Added missing direct dependencies to CONTRIBUTING.md Dependencies section

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File	Description
README.md	Added documentation for the args field in Server Configuration Fields, enabling users to discover advanced Docker runtime argument configuration
CONTRIBUTING.md	Fixed Docker container section with correct entrypoint, flags, and env vars; corrected DOCKER_API_VERSION fallback value; added missing dependencies (go-sdk, gojq, jsonschema, testify, term)

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.