[Dumbris]

Summary

Experiment E7 (zero-friction install surfaces). Spec: specs/121-install-surfaces/ (spec, plan, tasks, research, review log, .mcpb follow-up note).

• A. Registry: server.json now carries an oci package (ghcr.io/smart-mcp-proxy/mcpproxy-server, streamable-http localhost:8080/mcp, declares MCPPROXY_INSTALL_CHANNEL=registry). Image label io.modelcontextprotocol.server.name added (Dockerfile + build-docker). One shared scripts/stamp-server-json.sh + scripts/registry-preflight.sh (anonymous pull, label check, container smoke test with MCP initialize) used by both release.yml and retry-sign-release.yml. The registry has no binary package type, so release archives are not listed.
• B. Windows: reusable publish-windows-packages.yml (called from release + recovery, manually dispatchable): scoop manifest pushed to a bucket repo, winget PR to microsoft/winget-pkgs from our own tested generator (no third-party action). Jobs skip with a notice until configured. Inno installer: /CHANNEL=winget marker, stale-marker cleanup, uninstall cleanup, no blocking dialog in silent mode. New scoop update channel so a scoop-owned binary is never self-replaced.
• C. Agent install: "Paste this into your agent" prompt (single source docs/getting-started/agent-install.md, README block synced + drift-tested). While this PR was open, main landed an equivalent llms.txt publication boundary + verify-docs-build.js; I merged it and dropped this branch's own llms generator/guard (it had independently found that the live llms.txt advertised ~70 unpublished 404 pages). Only the agent-install page and its sidebar entry remain.
• D. Telemetry: heartbeat install_channel, a closed enum (brew, dmg, winget, scoop, windows-installer, deb, rpm, docker, registry, curl, tarball, go-install, unknown). Precedence: env > installer marker > existing detector > weak data-dir curl marker (only over tarball/go-install/unknown). Read only when telemetry is enabled; regular files only, size-capped, overflow rejected; anonymity scanner re-validates the enum. No schema bump (additive; avoids colliding with concurrent specs).
• E. .mcpb: not implemented; open questions in specs/121-install-surfaces/followup-mcpb.md.

Verification

• go test -race over ./internal/... ./cmd/... (CI skip regex): all packages pass except 3 docs-allowlist guards my refactor broke — fixed (config keeps the parseable include: [ shape); touched packages re-run green with and without -tags server.
• golangci-lint v2 (.github/.golangci.yml) bare and --build-tags server: no findings in files this PR touches (the remaining findings are pre-existing in untouched files).
• Shell tests: stamp-server-json, gen-scoop-manifest, gen-winget-manifest (schema-validated against Microsoft's 1.9.0 schemas), sync-agent-prompt; node tests for check-llms; mcp-publisher validate passes on the stamped entry.
• Docs: npm run build passes (before the merge; main's verify-docs-build.js now guards llms).
• Registry preflight run against the real v0.71.1 image: anonymous pull OK, label missing as expected (so versions ≤ 0.71.x stay package-less), container smoke test passes.
• Isolated agent-prompt run (fresh claude -p, scratch HOME, live instance on :8080 untouched): installed the real v0.71.1 archive, wrote the curl marker, started serve on 18080 after the port conflict, connect claude-code wrote a masked per-client credential. Details and the two prompt bugs it exposed in review-log.md. Codex not exercised.
• ./scripts/test-api-e2e.sh not run: foreign mcpproxy serve cores were running (live tray + another session) and the script's cleanup would kill them. The change touches no REST behavior beyond a new install_channel enum value/comment (swagger regenerated).
• Windows installer lifecycle cannot run locally; installer-channel-test.yml runs it on a disposable Windows runner for this PR (watch that check).

Cross-model review (opencode github-copilot/gpt-6.1-sol, high, read-only)

Round	Target	Verdict	Outcome
1	spec.md	CHANGES REQUIRED (11)	all applied
1	plan.md	CHANGES REQUIRED (13)	12 applied, 1 deferred (ARM64 Inno ArchitecturesAllowed, pre-existing, winget unaffected)
2	final diff, Go	CHANGES REQUIRED (2)	1 applied, 1 documented (global scoop needs --global)
2	final diff, CI/docs	CHANGES REQUIRED (4)	all applied (incl. a P1 admin-key leak in the agent prompt via status --web-url, verified)

Full table: specs/121-install-surfaces/review-log.md. The last round's fixes were verified by tests, not re-reviewed (one round past the cap is not needed; no open findings).

One-time human steps (Algis)

Details in docs/release-runbook.md → "Windows package managers (one-time setup)". Until done, the Windows jobs skip with a notice; nothing fails.

• Create public repo smart-mcp-proxy/scoop-bucket (any initial commit) and a fine-grained PAT with Contents read/write on it only → repo secret SCOOP_BUCKET_TOKEN.
• Fork microsoft/winget-pkgs; classic PAT (public_repo) from the fork owner → repo secret WINGET_TOKEN.
• First winget submission by hand (scripts/gen-winget-manifest.sh → wingetcreate submit); Microsoft review takes days–weeks. The winget job takes over once manifests/s/smart-mcp-proxy/mcpproxy exists upstream.
• After merge, cut the next stable tag and confirm: GET registry.modelcontextprotocol.io/v0/servers?search=mcpproxy&version=latest shows packages; scoop bucket commit; docs /llms.txt has no /docs/… links.
• Docs allowlist: nothing to add for agent-install (it matches getting-started/**; sidebar entry is in this PR).
• Follow-ups outside this repo: telemetry worker/dashboard store + chart install_channel (receiver already ignores unknown fields — verified in mcpproxy-telemetry/src/validation.ts); ARM64 Inno architecture directive; Personal Docker image (Spec 111) to replace the Server image in the registry entry; .mcpb bundle.

Notes for reviewers

• 2026-10-22: merged origin/main (conflicts in CLAUDE.md/ROADMAP/oas/docusaurus config/package.json resolved; my llms changes dropped in favour of main's). Windows CI failures on the first run were two real Windows-only bugs in my tests (path separators in the resolver test, CRLF in the installer-contract test), fixed in a3c586c.

• Spec number 121 (118 and 119 are taken by sibling branches; schema_version deliberately not bumped to avoid colliding with them).

• The recovery workflow checks out the tag, so recovering a release cut before this merge has no scripts/stamp-server-json.sh; releases after it are covered.

🤖 Generated with Claude Code

[cloudflare-workers-and-pages]

Deploying mcpproxy-docs with    Cloudflare Pages

Latest commit:	027f66d
Status:	✅  Deploy successful!
Preview URL:	https://0bb62f61.mcpproxy-docs.pages.dev
Branch Preview URL:	https://121-install-surfaces.mcpproxy-docs.pages.dev

View logs

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

❌ Patch coverage is 91.45299% with 10 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
internal/telemetry/install_channel.go	89.01%	5 Missing and 5 partials ⚠️

📢 Thoughts on this report? Let us know!

[github-actions]

📦 Build Artifacts

Workflow Run: View Run
Branch: 121-install-surfaces

Available Artifacts

• archive-darwin-amd64 (32 MB)
• archive-darwin-arm64 (29 MB)
• archive-linux-amd64 (19 MB)
• archive-linux-arm64 (17 MB)
• archive-windows-amd64 (32 MB)
• archive-windows-arm64 (28 MB)
• frontend-dist-pr (0 MB)
• installer-dmg-darwin-amd64 (28 MB)
• installer-dmg-darwin-arm64 (25 MB)
• smart-mcp-proxymcpproxy-go91LC70.dockerbuild (0 MB)

How to Download

Option 1: GitHub Web UI (easiest)

1. Go to the workflow run page linked above
2. Scroll to the bottom "Artifacts" section
3. Click on the artifact you want to download

Option 2: GitHub CLI

gh run download 40173353906 --repo smart-mcp-proxy/mcpproxy-go

Note: Artifacts expire in 14 days.