CTX7-2006: Support on-premise setup in ctx7 CLI

[fahreddinozcan]

Summary

• add custom deployment support to ctx7 setup --mcp --base-url
• discover on-prem MCP auth and write either anonymous access or a standard Authorization: Bearer credential for every registered client
• securely request a personal key with masked input, while preserving --api-key and CONTEXT7_API_KEY for automation and returning a failing exit status when discovery or required non-interactive auth fails
• keep custom-deployment setup outbound-independent after installation: skip update checks and telemetry, use bundled rule/skill content, refuse auth-discovery redirects with final-URL guidance, and avoid GitHub or Context7 Cloud fetches
• preserve current master behavior for hosted auth and the expanded client registry, including VS Code, Devin, and GitHub Copilot CLI
• document public and approved internal-registry installation for restricted or air-gapped environments
• add a ctx7 minor changeset

Testing

• pnpm --filter ctx7 typecheck
• pnpm --filter ctx7 lint:check
• pnpm --filter ctx7 test (368 passed)
• pnpm --filter ctx7 build
• real built-CLI E2E against a local on-prem endpoint for Claude Code, Cursor, VS Code, and Codex
• verified native client configs use only the configured /mcp URL and bearer key, with bundled rule/skill installation and no GitHub fetch
• verified masked interactive key entry, anonymous auth discovery, non-interactive failure behavior, invalid URL handling, automatic MCP mode selection, and redirect refusal in automated tests

[linear-code]

CTX7-2006

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
context7	🟢 Ready	View Preview	Aug 17, 2026, 9:17 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[context7]

Docs7 for context7.com

Result	Status	Action
Deployment	✅ Ready	Open preview
Content review	❌ Needs attention. 1 problem remains.	View findings

Commit c7d4df6 · Updated 2026-09-08 15:06 UTC · View build details

Show findings in this comment

Grammar and spelling (1)

• path/in/repo.mdx:12 — 有什么问题，最多二十个字

[enesgules]

Approving. Typecheck, lint, and the CLI test suite pass on the branch, and it merges cleanly on master. A few things to fix before or right after merge:

Bug: invalid --base-url crashes with a stack trace. resolveSetupDeployment throws for a malformed URL, a /mcp or /api suffix, embedded credentials, or a query string. The catch in setupCommand only handles ExitPromptError and rethrows everything else.

$ ctx7 setup --base-url http://127.0.0.1:9/mcp --codex --yes
Error: Pass the Context7 deployment root, without /mcp or /api
    at normalizeDeploymentBaseUrl (deployment.ts:34:11)

Wrap that call in setupCommand, log the message, set process.exitCode = 1, and return. One test for this path would be good.

Telemetry is only skipped for setup. trackEvent posts to getBaseUrl(), and the global preAction hook sets that to the on-prem URL. So ctx7 remove --base-url ..., docs, and search still POST to <on-prem>/api/v2/cli/events. A single guard inside trackEvent (tracking.ts) covers every command, and then the per-call guards in setup.ts can go.

Redirect handling does not match the description. redirect: "error" refuses every redirect, not only cross-origin ones. A deployment that redirects http to https fails with just fetch failed. Either say in the docs that redirects are refused, or catch that case and tell the user to pass the final URL.

Mode prompt runs before validation. With --base-url and no --mcp, the MCP-vs-CLI prompt appears, and choosing CLI then errors out. Return "mcp" from resolveMode when a base URL is set.

Duplicate code. HOSTED_MCP_BASE_URL and hostedMcpUrl in agents.ts duplicate getMcpUrl in deployment.ts. buildEntry has one caller and it always passes mcpUrl, so the parameter can be required and the defaults removed.

Nit. The subcommand-level --base-url option never receives a value; the program-level option consumes it and optsWithGlobals reads it. A short comment there would save the next reader a trace.

[fahreddinozcan]

Addressed the review feedback in 5dafb1a: invalid base URLs now fail cleanly, custom-deployment telemetry is centrally disabled, redirects produce final-URL guidance, --base-url selects MCP mode directly, duplicate hosted URL defaults were removed, and the option wiring is documented. Added coverage for invalid URLs, automatic MCP selection, redirects, and telemetry boundaries. Local validation: typecheck, lint, format check, build, 368 tests, plus a built-CLI on-prem smoke test.