docs(github-mcp-proxy-demo): make local binary the primary recipe, Docker an alternative

[vaaraio]

Summary

Follow-up to #103. The original demo framed Docker as a hard prerequisite, which contradicts Vaara's design intent: the proxy is light tooling that spawns any MCP-stdio binary as a subprocess and shouldn't pull in external runtimes by default.

This PR makes the local binary path the primary recipe and demotes Docker to an alternative paragraph.

Changes

• Prereqs. Dropped "Docker installed and running" as a hard requirement. Primary path is go install github.com/github/github-mcp-server/cmd/github-mcp-server@latest, which produces a stdio-capable binary with no external runtime.
• Before/After config blocks. Both now use command: /path/to/github-mcp-server with args: ["stdio"].
• Example JSON. Primary github-via-vaara entry uses the binary path. The Docker-wrapped variant is preserved as a sibling _alternative_docker block for readers who already run Docker.
• Troubleshooting. Replaced docker: command not found entry with the go install instruction.

Verification

The binary path is what was actually verified end-to-end during smoke testing against the real github/github-mcp-server:

• Vaara proxy spawned the binary in stdio mode as a subprocess
• initialize handshake completed
• tools/list returned all 42 real GitHub MCP tools
• tools/call search_repositories was intercepted, scored allow (risk 0.113, [0.000, 0.302]), forwarded to upstream
• Audit DB recorded a full hash-chained sequence: action_requested -> risk_scored -> decision_made -> outcome_recorded, each linked to the previous via SHA-256

Docs-only. No code changes, no test changes.

Summary by CodeRabbit

• Documentation
  • Updated MCP proxy demo setup instructions to support using a locally built github-mcp-server binary as an alternative to Docker.
  • Modified example Claude Code MCP configuration to enable local binary routing through the proxy.
  • Enhanced troubleshooting guidance with setup instructions for local binary and Docker alternative option.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR updates the GitHub MCP proxy demo's documentation and example configuration to make a locally-built github-mcp-server binary the primary deployment method, using Vaara's MCP proxy with stdio mode, while documenting Docker as a supported alternative.

Changes

Demo Setup and Configuration Documentation

Layer / File(s)	Summary
Local binary prerequisites and proxy configuration examples/github-mcp-proxy-demo/README.md, examples/github-mcp-proxy-demo/claude_code_config.example.json	Prerequisites now mention locally-built github-mcp-server binary as an option. The primary Claude Code MCP example configuration is rewritten to route through Vaara's proxy with --upstream /path/to/github-mcp-server and --upstream-arg stdio, and the example JSON is updated accordingly.
Docker alternative and troubleshooting guidance examples/github-mcp-proxy-demo/README.md	Added instructions showing how to use Docker-wrapped upstream within the same proxy configuration structure. Troubleshooting section revised to guide users toward building/installing the binary, with updated diagnostic messaging.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• vaaraio/vaara#103: Introduces the _alternative_docker configuration variant and initial demo setup using Docker-based upstream MCP server.
• vaaraio/vaara#100: Adds VaaraMCPProxy and upstream stdio support that enables the local-binary workflow documented in this PR.

Poem

A rabbit hops through setup paths with glee,
Stdio dreams make configs wild and free,
Docker still works, but now binaries shine,
Local builds dance where proxies align! 🐰✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically summarizes the main change: promoting local binary usage as the primary method for the MCP proxy demo while treating Docker as an alternative.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/github-mcp-proxy-binary-path

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

🧹 Nitpick comments (1)

examples/github-mcp-proxy-demo/README.md (1)

146-146: 💤 Low value

Consider clarifying the binary location guidance.

The troubleshooting mentions $(go env GOBIN) or $(go env GOPATH)/bin, which are shell command substitutions. Consider adding a brief note for users unfamiliar with Go, such as: "Run go env GOBIN to see the install directory, or go env GOPATH if GOBIN is not set (the binary will be in the bin subdirectory)."

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@examples/github-mcp-proxy-demo/README.md` at line 146, Update the
troubleshooting line for github-mcp-server to clarify how to find the install
directory: when mentioning $(go env GOBIN) and $(go env GOPATH)/bin, add a short
note telling users to run `go env GOBIN` to display the install directory and,
if GOBIN is empty, run `go env GOPATH` and use the bin subdirectory (i.e., "$(go
env GOPATH)/bin") so readers know how to locate the installed github-mcp-server
binary.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@examples/github-mcp-proxy-demo/README.md`:
- Line 146: Update the troubleshooting line for github-mcp-server to clarify how
to find the install directory: when mentioning $(go env GOBIN) and $(go env
GOPATH)/bin, add a short note telling users to run `go env GOBIN` to display the
install directory and, if GOBIN is empty, run `go env GOPATH` and use the bin
subdirectory (i.e., "$(go env GOPATH)/bin") so readers know how to locate the
installed github-mcp-server binary.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: e4b4447c-e516-4769-a981-29550415b40c

📥 Commits

Reviewing files that changed from the base of the PR and between fd53762 and 04c4049.

📒 Files selected for processing (2)

• examples/github-mcp-proxy-demo/README.md
• examples/github-mcp-proxy-demo/claude_code_config.example.json