* fix(mcp): support NODE_EXTRA_CA_CERTS for enterprise MITM proxies
When NODE_EXTRA_CA_CERTS is set, reads the CA certificate file and
injects it into undici's global dispatcher. This fixes fetch failures
behind enterprise transparent SSL intercept proxies (Zscaler, etc.)
where the default TLS context does not trust the corporate CA.
The CA certs are also passed through when an explicit HTTPS_PROXY is
configured, so both proxy modes work with custom certificates.
Fixes#2268
This contribution was developed with AI assistance (Claude Code).
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* chore: add changeset for NODE_EXTRA_CA_CERTS support
* fix(mcp): preserve default CAs with NODE_EXTRA_CA_CERTS
* chore: add changeset for CA trust fix
* chore: remove superseded changeset
* fix(mcp): lint test files with test tsconfig
* fix(mcp): use explicit test file path
* fix(mcp): support older Node TLS CA APIs
* test(mcp): run certificate test with vitest
---------
Co-authored-by: Matt Van Horn <455140+mvanhorn@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
* feat(cli): add Gemini CLI support to setup command
Adds Gemini CLI as a supported agent in `ctx7 setup`. Configures MCP
server in `.gemini/settings.json` using `httpUrl` (Gemini's HTTP
streaming transport), appends rules to `GEMINI.md`, and installs skills
to `.gemini/skills/`. Also adds a permission fix tip when skill
installation fails with EACCES.
* chore: add changeset for Gemini CLI setup
* fix(cli): use GITHUB_TOKEN for skill downloads to avoid rate limits
Closes#2363
* chore: add changeset for gh ratelimit fix
* fix(cli): fallback to gh auth token for skill downloads
Supports private repos and users with gh CLI but no env vars set.
Closes#2369
* feat(cli): support installing skills from private/unindexed repos
When the Context7 backend doesn't know about a repo, the CLI now falls
back to fetching the repo tree from GitHub directly, parsing SKILL.md
frontmatter locally, and downloading skill files. Uses GitHub API status
codes to differentiate non-existent repos from repos without skills.
Closes#2369
* docs: add server URL reference to README and all-clients page
The remote server URL was not easily discoverable in the docs.
This surfaces it in the README installation section and in the
all-clients page intro so users can find it without digging
through individual client configurations.
* docs: align all-clients intro with README wording
* docs: restore unlisted client fallback sentence
* docs: add CLAUDE.md with Context7 integration guidelines
Add documentation for Claude Code integration including:
- Quick setup instructions
- Usage examples with popular libraries
- Auto-trigger rules for NestJS, Prisma, SvelteKit, etc.
- Best practices for library documentation queries
Closes#2272
* feat(mcp): add --version/-v flag to CLI
Add version flag support using Commander.js .version() method.
Uses existing SERVER_VERSION constant from package.json.
Fixes#2284
* chore: remove unrelated CLAUDE.md from PR
* chore: add changeset for mcp version flag
---------
Co-authored-by: liwenjun-dev <liwenjun.dev@gmail.com>
Co-authored-by: Fahreddin Özcan <ozcanfahrettinn@gmail.com>
* fix(setup): allow re-selecting already configured agents and overwrite existing MCP config
Previously, agents with existing Context7 MCP config were disabled in the
selection prompt with "(already configured)" and their config was never
updated. This made it impossible to reconfigure an agent (e.g. rotate API
key or fix a broken URL) without manually editing config files.
Now all agents are always selectable, existing config is overwritten with
fresh entries on re-setup, and TOML replacement correctly handles
sub-sections like http_headers.
* fix(setup): eliminate double file read and whitespace drift in TOML overwrite
Inline the server existence check into appendTomlServer to avoid reading
the file twice. Normalize whitespace around the replaced block so repeated
re-configurations do not accumulate blank lines.
* chore: add patch changeset for setup reconfiguration fix
* fix(setup): resolve all OpenCode config file variants for MCP setup
OpenCode supports 4 config file names (opencode.json, opencode.jsonc,
.opencode.json, .opencode.jsonc) but setup only checked opencode.json
and opencode.jsonc. Users with dotfile variants were never detected as
"already configured" and setup would create a duplicate opencode.json.
Changed mcp.projectPath/globalPath (single string) to
mcp.projectPaths/globalPaths (string[]) so agents can declare all valid
config paths. resolveMcpPath now takes the full candidates array and
returns the first existing file, falling back to the first entry.
Closes#2313
* chore: add patch changeset for OpenCode config variant fix
* refactor(setup): update rule template to be selective with examples
Based on eval benchmarks showing that selective rules with explicit
should/should-not examples achieve 98% recall with 0 false positives,
vs the previous broad rule.
Split RULE_CONTENT into MCP_RULE_CONTENT and CLI_RULE_CONTENT to
support both MCP and CLI setup modes with appropriate tool references.
* feat(setup): install CLI rule alongside skill in ctx7 setup --cli
Previously, CLI setup mode only installed the find-docs skill (66% trigger
rate). Now it also installs a rule file with ctx7 CLI instructions for each
selected agent, matching the MCP setup behavior.
Benchmarks show skill + rule achieves 96-98% trigger rate vs 66% skill-only.
* feat(find-docs): update skill description to improve trigger rate
Replace passive description with pushy version that explicitly names common
libraries and counters Claude's undertriggering tendency.
Eval results: 66% -> 98% clean recall, 72% -> 92% with-context recall.
* chore(setup): remove deprecated RULE_CONTENT export and alwaysApply frontmatter
alwaysApply is not a Claude Code feature (it's Cursor-specific). Claude Code
rules without paths frontmatter load unconditionally by default. Remove the
deprecated alias now that all callers use MCP_RULE_CONTENT or CLI_RULE_CONTENT.
* refactor(setup): fetch rules from GitHub, add alwaysApply for Cursor
- Rule source of truth in rules/context7-mcp.md and rules/context7-cli.md
- templates.ts fetches from GitHub raw (master then main)
- getRuleContent(mode, agent) adds alwaysApply frontmatter for Cursor
- CLI setup now logs rule install failures instead of silently swallowing
* refactor(setup): add Codex agent, remove needsAlwaysApply field, use shared installRule
- Add Codex agent config with AGENTS.md append support
- Remove needsAlwaysApply field (hardcoded cursor check in templates.ts)
- CLI setup uses shared installRule instead of inline CLI_RULE_PATHS
- installRule handles both file-based (Claude/Cursor/OpenCode) and
append-based (Codex/AGENTS.md) rule installation
* refactor(setup): unify CLI setup with MCP agent picker, group output by agent
- CLI setup now uses the same agent picker as MCP setup (no auto-detection)
- Output grouped by agent instead of repeating find-docs for each path
- Removed unused promptForInstallTargets/getTargetDirs imports
* fix(setup): add branch fallback URL for rule fetch, show error on rule failure
* fix(setup): OpenCode uses AGENTS.md, fix append logic for existing files
- OpenCode rule changed from .opencode/rules/ to AGENTS.md (append type)
since OpenCode reads AGENTS.md natively, not a rules directory
- Fixed append logic: proper spacing for empty/non-empty files, clean
idempotent replacement on re-run, preserves existing content
* test(setup): add tests for rule install, MCP config, and AGENTS.md append
* chore(setup): remove unused mergeInstructions and instructionsGlob
* fix: lint formatting, add changeset
* fix(setup): Codex global rule goes to ~/.codex/AGENTS.md
* fix(setup): align CLI output format with MCP output
* feat(setup): add --codex flag for MCP and CLI setup
* docs(rules): align trigger language with skill, use npx ctx7@latest in CLI rule
* docs(rules): prefer ctx7 over web search for library docs
* docs(find-docs): prefer skill over web search in description
* docs(rules): consolidate trigger language, add selection criteria
* docs(rules): add query quality guidance and auth env var to CLI rule
* cleanup
* fix: remove branch URL, add offline fallback matching rule files exactly
* fix(setup): support opencode.jsonc, strip JSON comments, fix detect path
- readJsonConfig now strips // and /* */ comments before parsing (JSONC support)
- resolveMcpPath checks for .jsonc variant when .json is specified
- OpenCode detect paths include both opencode.json and opencode.jsonc
- Fixed OpenCode project path from .opencode.json to opencode.json
* fix(setup): fix JSONC comment stripping to preserve URLs in strings
The regex-based comment stripper was matching // inside string values
(e.g., https:// URLs), corrupting the JSON. Replaced with a character-
level parser that skips string literals before stripping comments.
* fix(setup): Codex uses TOML config.toml, detect .opencode.json variant
- Codex MCP writes to ~/.codex/config.toml using [mcp_servers.context7]
TOML sections instead of JSON (matches Codex docs and add-mcp tool)
- OpenCode detection checks opencode.json, opencode.jsonc, and .opencode.json
- Added TOML server block writer with idempotent append
- stripJsonComments now handles URLs in strings correctly
* test(setup): add JSONC, TOML, and resolveMcpPath tests
12 new tests covering:
- JSONC: comment stripping preserves URLs, block comments, plain JSON
- resolveMcpPath: .jsonc resolution, .json fallback, non-json passthrough
- TOML: buildTomlServerBlock output, http_headers, readTomlServerExists,
appendTomlServer (empty file, preserve existing, idempotent)
* fix(setup): Codex MCP needs type=http, fix checkbox disabled item selection
- Codex TOML entry now includes type = "http" (required by Codex)
- Checkbox cursor starts on first non-disabled item
- Checkbox navigation skips disabled items
* fix: address PR review feedback on rules and skill description
- Surface libraryId format (/org/project) in step 2 where selection happens
- Suggest retrying with alternate names/queries instead of just punctuation
- MCP rule: explicitly require resolve-library-id unless /org/repo provided
- Skill description: explicitly warn against relying on training data for APIs
* fix: consistent /org/project format in MCP rule
* fix: revert opencode detection paths to original
* feat: enhance Context7 server configuration with website URL, description, and detailed usage instructions
* run format
* add changeset
* feat: align MCP server instructions with eval-proven trigger language
Based on invocation routing benchmarks (60 queries, clean + mid-session):
- Named specific libraries to counter confidence skip
- Added 'even when you think you know the answer' override
- Added 'prefer over web search' to catch WebSearch fallback
- Unified trigger paragraph to match client rule format
- Added explicit 'do not use for' negatives
---------
Co-authored-by: Fahreddin Özcan <ozcanfahrettinn@gmail.com>
* fix(cli): use ~/.agents/skills for global universal skill installs
The universal global path was ~/.config/agents/skills, but the
canonical standard (used by Vercel's skills CLI and OpenAI Codex)
is ~/.agents/skills. This aligns context7 with the broader ecosystem.
Fixes#2276
* chore: add changeset for global skills path fix
* fix(cli): remove shell:true from spawn in generate command
Removes shell:true from the child_process.spawn() call that opens
the user's editor. The editor path and preview file path are already
passed as separate arguments, so shell interpolation is unnecessary.
Using shell:true allows shell metacharacters in EDITOR or file paths
to be interpreted, which is a command injection vector.
Fixes#2240
This contribution was developed with AI assistance (Claude Code).
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* chore: add changeset for shell:true removal
---------
Co-authored-by: Matt Van Horn <455140+mvanhorn@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: Fahreddin Özcan <ozcanfahrettinn@gmail.com>
* fix(cli): prevent directory traversal in skill file installation
installSkillFiles() used path.join() with unsanitized file paths from
GitHub API responses. A malicious skill repository could include files
with "../" sequences in their paths, allowing writes outside the
intended skill directory.
Changes:
- installer.ts: use path.resolve() and verify the resolved path stays
within the skill directory boundary before writing
- github.ts: reject file paths containing ".." at download time as an
additional defense-in-depth check
* chore: add changeset for directory traversal fix
* fix: format installer.ts to pass prettier lint
---------
Co-authored-by: Fahreddin Özcan <ozcanfahrettinn@gmail.com>
* fix(mcp): support NODE_EXTRA_CA_CERTS for enterprise MITM proxies
When NODE_EXTRA_CA_CERTS is set, reads the CA certificate file and
injects it into undici's global dispatcher. This fixes fetch failures
behind enterprise transparent SSL intercept proxies (Zscaler, etc.)
where the default TLS context does not trust the corporate CA.
The CA certs are also passed through when an explicit HTTPS_PROXY is
configured, so both proxy modes work with custom certificates.
Fixes#2268
This contribution was developed with AI assistance (Claude Code).
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* chore: add changeset for NODE_EXTRA_CA_CERTS support
---------
Co-authored-by: Matt Van Horn <455140+mvanhorn@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: Fahreddin Özcan <ozcanfahrettinn@gmail.com>
The single deployment.mdx page implied Kubernetes-only deployment. Split it into
a deployment/ folder with separate Docker and Kubernetes guides, and simplify the
on-premise getting started page to link to them via Mintlify cards.
* fix(cli): add token refresh support and centralize auth constants
Expired OAuth tokens are now automatically refreshed via getValidAccessToken()
instead of silently failing. CLI_CLIENT_ID moved to constants.ts to avoid
duplication across auth.ts and setup.ts.
* refactor(cli): internalize baseUrl and clientId in refreshAccessToken
Make refreshAccessToken a private function that resolves getBaseUrl()
and CLI_CLIENT_ID internally instead of requiring them as parameters.
* test(cli): add unit tests for auth utilities and commands
Add comprehensive vitest test suite covering OAuth PKCE flow, token
persistence, token refresh, and CLI auth commands (login/logout/whoami).
* chore: add changeset for CLI auth improvements
* refactor: move CLI auth tests to src/__tests__/
Move auth test files from colocated __tests__ directories to a
centralized src/__tests__/ directory, adjusting mock import paths
accordingly.
The previous description was scoped to "programming library or framework",
causing the skill to be skipped for CLI tools, cloud services, APIs, platforms,
and general technical questions. The new description covers any developer
technology and includes common trigger scenarios to improve auto-invocation.
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
New deployment.mdx page under the On-Premise section covering
StatefulSet, Service, Ingress manifests, registry auth, networking
requirements, operations, and troubleshooting for K8s deployments.
* feat(cli): add teamspace name to whoami command
Replace direct Clerk userinfo call with new /api/dashboard/whoami
endpoint that returns name, email, and active teamspace in one request.
* chore: add changeset for whoami teamspace feature
github-actions[bot]