The localhost-callback path is gone. Every install — laptop, SSH,
Codespace, Docker, CI — goes through the same boxed prompt and
verification page. Three reasons to make this the default:
- The localhost flow was broken anywhere the browser couldn't reach
127.0.0.1:52417 (SSH, Docker, Codespaces). Auto-detection via
SSH_CONNECTION / $DISPLAY was a half-fix that depended on env
vars users don't always set.
- Device flow works everywhere, has no random port-binding behavior,
and still ends in the same long-lived ctx7sk- API key.
- One UX path is simpler to support than two.
Drops the --device flag (it was the opt-in for what's now the
default). Older CLI versions (<= 0.5.0) continue to work against the
unchanged auth endpoints, so pinned installs are unaffected.
The legacy localhost machinery in utils/auth.ts is left in place
for now — nothing imports it from commands/auth.ts anymore, and a
follow-up can delete it once we're confident no rollback is needed.
* feat(cli): OAuth 2.0 device authorization flow
Adds RFC 8628 device-code login for headless / remote hosts (SSH,
Codespaces, Docker, CI) where the existing localhost-callback flow
can't work — the browser opens on the user's laptop while the
callback listener runs on the remote host, so the redirect target
is unreachable.
Device flow prints a verification URL and short code, then polls the
new /api/oauth/device/token endpoint. The user visits the URL on any
device, signs in, and approves; the CLI receives the same ctx7sk- API
key it would have gotten from the legacy flow.
- shouldUseDeviceFlow() auto-detects via SSH_CONNECTION /
SSH_CLIENT / SSH_TTY and missing $DISPLAY on Linux.
- ctx7 login --device forces it. ctx7 setup picks it up
automatically when resolveCliAuth needs to authenticate.
- pollDeviceToken returns a "transient" status for network errors
and 5xx responses so a flaky backend or Upstash blip doesn't end
the session — keeps polling until the device_code TTL elapses.
* polish(cli): boxed device-code prompt, Press-Enter, whoami success line
Tightens up the device-flow UX so it matches the patterns from gh /
stripe / wrangler:
- Wrap the user_code + verification URL in a boxen rounded box with
a title, gray border, and the code as the visual headline (green
bold, indented on its own line).
- Add a "Press Enter to open the browser, or Ctrl-C to quit..."
confirmation step in TTY mode so the user can read the code before
the browser steals focus. Skipped under --no-browser or non-TTY.
- Replace the generic "Login successful!" line with
"Logged in as <email> (<team>)" by fetching /api/dashboard/whoami
with the freshly minted token. Falls back to the old text if the
call fails.
- Tighten the mockShouldUseDeviceFlow signature in the test mock so
the spread-into-mock pattern typechecks.
No behavior change to the localhost-callback flow.
* test(cli): cover shouldUseDeviceFlow + start/poll + performDeviceLogin
auth-utils: SSH/$DISPLAY heuristics for shouldUseDeviceFlow; the
form-encoded start-device-authorization request shape and error
propagation; pollDeviceToken status mapping for each RFC 8628 code,
5xx -> transient, network error -> transient, and unknown 4xx ->
throw.
auth-commands: performDeviceLogin happy path (approved -> saveTokens
called), denied/expired return null and don't save, transient errors
keep polling instead of bailing, slow_down bumps the interval
(verified with fake timers), startDeviceAuthorization throwing exits
without polling, browser-open behavior under openBrowser=true/false.
Also covers the performLogin selector: forceDevice=true and
shouldUseDeviceFlow=true both route through performDeviceLogin
without hitting the localhost callback path.
28 new tests; suite is 235/235.
* docs(cli): tighten device-flow comments
Drop restatement; keep only WHY-bearing notes.
* fix(cli): default poll interval to 5s per RFC 8628 §3.2
The CLI was treating `interval` as required and would NaN-crash if
a future server omitted it. Spec requires clients to default to 5
when absent.
DeviceAuthorizationResponse.interval is now optional, and
performDeviceLogin uses DEFAULT_DEVICE_POLL_INTERVAL_SECONDS (5) as
the fallback. Test covers the missing-interval path.
* fix(cli): rfc 8628 spec gaps — backoff, hostname, bare verification_uri
Three small spec-compliance fixes from the §3.5 / §3.3 / §5.4 audit:
- §3.5: poll loop now bumps intervalMs by 5s on `transient` results
(network errors and 5xx) — the RFC requires unilateral backoff on
connection timeouts, and mirroring the slow_down handler is the
simplest correct response.
- §3.3: the boxed prompt now prints the bare verification_uri
alongside verification_uri_complete so screen readers / paper /
another device can still type the short form.
- §5.4: startDeviceAuthorization sends `os.hostname()` so the server
can show it on the verification page; the user can confirm the
device they're authorizing matches the one running the CLI.
Transient-backoff test rewritten with fake timers (the new +5s wait
made the old real-timer assertion blow past the 5s default timeout).
resolveMode treated --api-key as a non-interactive marker and
short-circuited to MCP, but --api-key is equally valid for CLI +
Skills mode (which authenticates skill downloads). Users who
preferred CLI mode were silently locked into MCP unless they
also passed --cli.
Remove options.apiKey from the auto-MCP OR-chain. --mcp / --cli /
--stdio / --oauth / -y still skip the prompt; --api-key alone now
falls through to the interactive mode picker.
* fix(cli): wire --antigravity and remove broken --universal in setup
The setup command advertised --universal and --antigravity flags but
neither was wired through getSelectedAgents, so passing them silently
fell back to auto-detection and wrote to the wrong directory (see #2695).
Remove --universal from setup entirely, and add a full Antigravity
SetupAgent config: skills under .agent/skills, MCP config at
~/.gemini/antigravity/mcp_config.json with serverUrl for HTTP, and
detection of .agent or ~/.gemini/antigravity.
* fix(cli): align antigravity setup with official Google docs
After verifying against Google Codelabs / Google Cloud Community
docs, correct the Antigravity config:
- MCP global path: ~/.gemini/config/mcp_config.json (Antigravity 2.0
shared config, replacing the older ~/.gemini/antigravity/ path
which an outdated github/github-mcp-server install guide cited).
- HTTP key: httpUrl (Gemini convention; antigravity is Gemini-based).
The previous serverUrl was sourced from the same outdated guide.
- Rule: append to GEMINI.md / ~/.gemini/GEMINI.md (Antigravity reads
Gemini-family rules, not a vendor-specific file).
- Project MCP: none documented; projectPaths is empty and setupAgent
/ remove falls back to globalPaths so --project --mcp still writes
to the correct location.
Skills stay at .agent/skills to keep the in-repo IDE_PATHS convention
consistent across setup, skill, and generate commands.
* chore(cli): move Antigravity to 5th in agent selection list
Match the natural ordering users expect in the checkbox prompt:
Claude Code, Cursor, OpenCode, Codex, Antigravity, Gemini CLI.
* fix(cli): antigravity HTTP key is serverUrl, not httpUrl
Antigravity rejects the entry with "serverURL or command must be
specified" when given httpUrl. Switch the HTTP entry back to
serverUrl (the github-mcp-server install guide had this right even
though its file path was outdated).
Also tighten the empty-projectPaths fallback in remove.ts: it
incorrectly leaked global state into project-scope detection,
making `remove --project` report Antigravity whenever a global
~/.gemini/config/mcp_config.json existed. Project-scope detect/
remove now no-ops for agents with no project-level MCP, while
setup still falls back to the global path so --project --mcp
--antigravity writes to the file Antigravity actually reads.
* fix(cli): wire --antigravity into the remove command
Symmetric to the setup fix: --antigravity was missing from
UninstallOptions and getSelectedAgents, so users had no CLI path
to undo a `ctx7 setup --antigravity` install.
* docs(azure-apim): reflect Settings tab + cascade-delete + audience-uniqueness
Three updates after merging the per-user identity feature to production:
1. Dashboard navigation: Entra cards moved from the Overview tab to a
conditional Settings tab (only visible for enterprise teamspaces or
active trials). Update Part 4 and the troubleshooting section.
2. Cascade-delete: clicking Remove on the Microsoft Entra ID card now
removes both the tenant configuration AND all provisioned users in a
single step. Add a note so admins know not to use Remove for
single-user revocation.
3. Audience uniqueness: each MCP API app (audience GUID) can be claimed
by one teamspace at a time. Document the failure mode and how to
resolve it, since hitting it from a fresh setup is easy.
* docs(azure-apim): add Part 6 — smoke test the gateway from CLI
Walks through pre-authorizing Azure CLI on the Gateway app's scope and
running an `az account get-access-token` + curl against APIM end-to-end.
Lets admins validate the full OBO flow before pointing real MCP clients
at the gateway.
Renumber the original "Connect an MCP client" to Part 7.
* feat(mcp): multi-tenant Entra ID validation
Detect inbound Entra v2 tokens by issuer pattern, fetch per-teamspace
configuration (tenantId, audience, requiredScope) from the Context7
app, and verify the token against the matching tenant's JWKS. The MCP
server only validates — user resolution happens in the app middleware
against the entra_user_mappings table.
Per-tenant JWKS cache and a 5-minute in-memory config cache keyed by
JWT audience reduce overhead under load.
* fix(mcp): prettier formatting + refresh changeset
Resolves prettier/eslint errors blocking the test workflow, and refreshes
the changeset to match the actual MCP-side behavior (validate only; user
resolution lives in the app middleware).
* fix(mcp): only negative-cache 404 responses, not transient errors
Address review: caching null under the same 5-minute TTL on every failure
mode meant one transient blip (5xx, network error, JSON parse error) locked
every Entra token for that audience out of the server for 5 minutes with a
misleading "Unknown audience" message.
Now only the authoritative 404 ("audience not configured") is cached as
null. 5xx, network errors, and parse errors fall through without caching
so the next request retries.
* Add JSON output for skills list
* test(cli): resolve tempDir via realpath for macOS compatibility
On macOS, os.tmpdir() returns /var/folders/... but process.cwd()
reports the symlink-resolved /private/var/folders/... after chdir.
The JSON output uses the resolved cwd, so the test assertion mismatched
the unresolved tempDir on macOS.
* chore: add changeset for skills list --json
---------
Co-authored-by: Fahreddin Özcan <ozcanfahrettinn@gmail.com>
* fix(cli): declare @inquirer/core as direct dependency
selectOrInput.ts imports from @inquirer/core directly, but the package
was only resolvable as a transitive of @inquirer/prompts. Under pnpm's
isolated linker this fails with ERR_MODULE_NOT_FOUND at startup.
Fixes#2651
* chore: add changeset
* docs(enterprise): add Azure APIM deployment guide
Step-by-step guide for deploying Context7 behind Azure API Management
with Microsoft Entra ID per-user authentication via On-Behalf-Of (OBO)
token exchange. Covers APIM provisioning, Entra app registrations,
policy wiring, OAuth discovery surfaces, and connecting MCP clients
(VS Code Copilot, Cursor) through the gateway.
* docs(azure-apim): cover user pre-provisioning + fix variable typo
- Restructure Part 4 into two steps: tenant config + pre-provisioning
users via the new dashboard card. Calls out that Context7 rejects
unmapped oids — there is no auto-provisioning.
- Add troubleshooting entry for the unmapped-user 401 (most common
failure once tenant config is correct).
- Fix \$APIM_NAME → \$APIM typo in the OAuth proxy provisioning
commands; the rest of the doc uses \$APIM so the OAuth proxy
commands would have failed as written.
* fix(cli): validate skill names to prevent path traversal on install
Adds boundary validation and containment checks so a remote SKILL.md
with a malicious name field (e.g. `name: ..`) cannot escape the skills
root during `ctx7 skills install`. Previously, the value flowed from
parseSkillFrontmatter to installSkillFiles unchecked, and the existing
traversal guard only verified files stayed inside the attacker-chosen
directory rather than the real skills root, enabling arbitrary file
writes outside `.claude/skills` (e.g. `.claude/settings.json` for
hook-driven RCE). symlinkSkill had the same trust issue and could
`rm(recursive: true)` arbitrary directories.
* chore: add changeset for skill name validation
* chore: soften changeset wording
Configures pnpm's minimumReleaseAge to 10080 minutes (7 days) so newly
published package versions can't be installed until they've existed on
the registry long enough for short-lived supply-chain compromises (e.g.
hijacked publish tokens, typosquats) to be detected and yanked. 7 days
is the post-Shai-Hulud/tj-actions community baseline.
Critical hotfixes can still be installed by adding entries to
minimumReleaseAgeExclude.
Ref: https://pnpm.io/blog/2025/12/05/newsroom-npm-supply-chain-security
Some LLM clients send `context7CompatibleLibraryID`/`userQuery` instead of
the canonical `libraryId`/`query` — likely echoing phrasing from the tool
descriptions — and trip Zod validation before the tool ever runs.
Hook `Transport.onmessage` (set before `server.connect()` so the SDK chains
its dispatch over it) and rewrite those two keys in place on `tools/call`
requests where the canonical key is absent. Published `tools/list` schemas
are unchanged; the rewrite is a server-side compatibility shim.
Listen for stdin end/close and SIGHUP and exit with code 0. Without these,
an idle undici keep-alive socket left over from a recent fetch keeps
libuv's event loop alive past stdin EOF, leaving an orphan node process
when the parent (e.g. Claude Code) is force-killed.
Fixes#2542
readJsonConfig only caught file-read errors, not JSON.parse errors.
During `ctx7 remove`, the detector iterates every agent's well-known
config path; an unparseable JSON file at any of them (e.g. a
hand-edited ~/.claude.json) crashed the command with an unhandled
SyntaxError before it could do anything.
Wrap the readJsonConfig call in hasMcpConfig with a try/catch that
logs a warning naming the path and parse error and skips that agent.
Keep readJsonConfig itself strict so write paths in setup and
uninstallMcp continue to surface failures via their existing handling.
* fix(mcp): stream tool-call responses so headers flush before 60s
The remote MCP server's StreamableHTTPServerTransport runs in JSON mode
(`enableJsonResponse: true`), which buffers the entire response and writes
status + headers + body together at the end of the tool call. Long-running
tools — notably `query-docs` with `researchMode: true` — routinely take
60–250s, during which no bytes are written to the wire.
MCP HTTP clients cap the underlying `fetch()` waiting for headers
(Claude Code: 60s, hardcoded in @modelcontextprotocol/sdk consumers),
independent of the higher-level per-tool timeout. Production curl with
`-w time_starttransfer` shows `start_transfer ≈ total ≈ 125s` for a
research call — the connection sits silent for the full duration before
flushing in one burst, well past any reasonable client `fetch` timeout.
Switch to SSE responses for POST tool calls. The SDK then returns the
HTTP response synchronously after parsing the request, headers flush in
ms, and the body streams while the tool runs. Same total wall time, but
clients see headers immediately and don't time out.
The existing NGINX-timeout comment above (about rejecting GETs) is about
the standalone GET SSE channel for server-initiated notifications and
still applies — GETs remain rejected. Per-request POST SSE responses are
bounded by the tool call and work fine on the existing ingress
(`proxy-buffering: off`, `proxy-read-timeout: 3600`).
Streamable HTTP requires clients to accept both `application/json` and
`text/event-stream` (SDK enforces 406 otherwise), so this is transparent
to compliant clients including Claude Code.
* remove comment
* chore: add changeset
* fix(mcp): emit progress notifications during researchMode query-docs
The SSE-streaming change in the previous commit only addresses clients
whose timeout fires when response *headers* don't arrive (e.g. Claude
Code's `wrapFetchWithTimeout`). Clients using the MCP SDK's default
`Protocol.request()` timer (`DEFAULT_REQUEST_TIMEOUT_MSEC = 60000`) hit
a wall-clock timeout that bytes flowing don't reset.
Emit `notifications/progress` every 20s while the upstream fetch is in
flight, gated on `researchMode: true` and the client supplying a
`progressToken` in `_meta`. Clients that pass an `onprogress` handler
have the SDK include `progressToken` automatically; on each notification
the SDK resets their JSON-RPC request timer (when they also opted into
`resetTimeoutOnProgress: true`), keeping 60–250s research runs alive.
Clients that don't include a `progressToken` see no notifications and no
behavior change. Fast `query-docs` calls are unaffected — the interval
only arms when `researchMode` is true.
* Merge branch 'master' of https://github.com/upstash/context7 into fix/mcp-stream-tool-responses
# Conflicts:
# packages/mcp/src/index.ts
* fix(mcp): restore researchMode and progress notifications on query-docs
Re-add the researchMode parameter to the query-docs input schema and
re-emit periodic notifications/progress while the upstream call is in
flight. Clients that opt into resetTimeoutOnProgress (e.g. opencode)
reset their per-request timer on each notification, which keeps the
long-running researchMode call alive past the SDK's default 60s
wall-clock timeout.
* fix(mcp): create a fresh McpServer per HTTP request
The HTTP transport is stateless (sessionIdGenerator: undefined), but the
handler shared one global McpServer across requests. McpServer extends
Protocol, which has a single _transport field. Each server.connect()
overwrites it, and any transport.close on any request fires the shared
Protocol's onclose, leaving _transport undefined for everyone else.
That meant a long-running researchMode call lost its transport every
time an unrelated short request (tool list refresh, init confirmation,
etc.) closed in the background, surfacing as "Not connected" on every
subsequent sendNotification and ultimately a -32001 timeout on the
client.
Switch to the per-request pattern from the SDK's
simpleStatelessStreamableHttp example: a createMcpServer factory builds
a fresh server, registers tools, and is closed alongside the transport
on res.on('close'). stdio mode keeps a single server, since stdio has
exactly one transport for the process lifetime.
* Merge remote-tracking branch 'origin/master' into fix/mcp-stream-tool-responses
# Conflicts:
# packages/mcp/src/index.ts
* chore(mcp): minimize PR diff against master
Drop the now-redundant changeset that duplicated the SSE-streaming note
already released in 2.2.3, restore comments inadvertently dropped during
the createMcpServer refactor, and rename the changeset file to reflect
what this PR actually changes.
Net diff vs master is now wrapping the existing setup in a
createMcpServer factory, calling it per HTTP request, and closing the
server alongside the transport (12 logical lines added, ignoring
indentation introduced by Prettier).
* fix(mcp): move client info capture to MCP server initialization for stdio mode
Hide the `researchMode` parameter from the MCP tool's input schema so
agents stop invoking it. The upstream `/api/v2/context` route still
accepts and serves the parameter; only the MCP-layer surface is
removed. Reasoning: several MCP clients hit per-request timeouts (60s
defaults in the SDK and in fetch-wrappers) on long-running research
calls in ways that can't all be solved server-side. Until the timeout
story is reliable across clients, agents shouldn't be able to call it
via MCP.
Updates:
- Drop the `researchMode` field from the `query-docs` input schema.
- Drop the workflow line in the tool description that referenced it.
- Stop forwarding `researchMode` to fetchLibraryContext; the field is
optional on ContextRequest, so omitting it is equivalent to false.
github-actions[bot]