* feat(plugins): add Context7 plugin for OpenCode
Adds @upstash/context7-opencode, an OpenCode plugin that registers the
hosted Context7 MCP server, the context7-mcp skill, a docs-researcher
subagent, and the /context7-docs command through the config hook.
* docs(opencode): keep ctx7 setup as the primary install path
* refactor(opencode): drop the component toggles and tighten the option boundary
The skill/agent/command toggles were speculative: OpenCode dedupes skills by
name, so running ctx7 setup alongside the plugin is already safe, and a user
who wants a component gone can define it themselves, which the plugin never
overwrites. Removing them collapses resolveOptions into resolveApiKey and
deletes the duplicated defaulting between option parsing and config assembly.
Also assert the MCP endpoints as literals. The tests compared against the same
constants they exercised, so a wrong URL would have passed.
* refactor(opencode): drop tests and collapse the plugin into one file
config.ts existed to give the tests a seam. With the tests gone the split was
indirection with no consumer, so the constants, the config assembly, and the
plugin entry now live in src/index.ts and nothing but the default export is
public. Passing skillsDir through an ApplyInput object also stops being
necessary once it is a module constant.
* fix(opencode): run the MCP server over stdio and drop the slash command
Verified against a real OpenCode 1.18.11 session: the remote transport does
not work. OpenCode opens the optional GET SSE stream, mcp.context7.com answers
405, and OpenCode marks the server failed and registers no tools, so the model
never sees resolve-library-id and falls back to inventing bash calls. A control
project with a plain remote mcp block and no plugin fails the same way, so this
is not plugin-specific. Running the server over stdio connects and the model
calls the tools.
The bundled skill and the agent prompt also referenced the bare tool names.
OpenCode prefixes MCP tools with the server name, so they are now
context7_resolve-library-id and context7_query-docs.
Also removes the /context7-docs command. The skill already triggers on its own
and the subagent covers focused lookups.
* refactor(opencode): use the remote MCP server and drop the subagent
The plugin now adds two things: the hosted MCP server over the remote
transport, and the context7-mcp skill.
Known limitation: OpenCode opens the optional GET SSE stream on the endpoint
and mcp.context7.com answers 405, so OpenCode marks the server failed and
registers no tools. Reproduced on 1.18.11 and 1.18.16, and with a plain remote
mcp block and no plugin, so it is not plugin-specific. It resolves once
mcp.context7.com answers GET /mcp with a 200 SSE stream instead of 405.
* refactor(opencode): ship the canonical skill verbatim and drop the phantom peer dep
The bundled skill had been edited to hard-code OpenCode's context7_ tool
prefix. That divergence was unnecessary and counterproductive:
- It was fixing a misdiagnosis. The model only invented shell commands when
the MCP server had failed to connect and no context7 tools existed at all.
With the tools present, claude-haiku-4-5 calls context7_resolve-library-id
correctly from the bare-name canonical skill.
- It was defeated where it mattered. OpenCode dedupes skills by name and scans
~/.claude/skills first, so on any machine that ran ctx7 setup the bundled
copy is shadowed by the canonical one anyway.
- It was the only client copy to diverge in content. claude, copilot, codex
and cursor all ship skills/context7-mcp/SKILL.md verbatim, and there is no
tooling to keep copies in sync.
Also removes peerDependencies on @opencode-ai/plugin. The package is a
type-only import that the build erases, so the published dist has zero
references to it, and peerDependenciesMeta.optional made the declaration inert
anyway. The devDependency is what typechecking actually needs.
* refactor(opencode): strip commentary and inline the plugin function
Keeps only the two comments that stop someone breaking the plugin: why the
skills cast is needed, and why nothing but the default export may be exported.
Inlining the server function into the default export drops the Context7Plugin
binding and the Plugin type import, since satisfies PluginModule already types
the callback. 85 lines down to 56.
* docs(opencode): use the prefixed tool names consistently in the README
* fix(cli): write the API key as an Authorization header
Codex resolves a server's auth mode by checking only for
`bearer_token_env_var` or a header literally named `Authorization`
(`auth_status_before_discovery` in codex-rs/rmcp-client/src/auth_status.rs,
mirrored in `create_transport` in rmcp_client.rs). The custom
`CONTEXT7_API_KEY` header matched neither, so Codex fell through to any OAuth
credential stored for the same server name and URL and refreshed it during
startup. A dead refresh token then failed the server with `invalid_grant`
before the API key was ever sent, and re-running setup could not recover it
because setup writes config.toml and never touches the credential store.
The hosted endpoint accepts both header forms, so existing configs keep
working.
Two places keep the legacy header deliberately: the plugin .mcp.json files
default to `${CONTEXT7_API_KEY:-}`, and the server rejects `Bearer` with an
empty token while treating a missing header as anonymous; and `env` blocks in
stdio configs, where the name is an environment variable rather than a header.
* fix(plugins): send the API key via the Authorization header
The Claude and Copilot plugin configs default to `${CONTEXT7_API_KEY:-}`, and
both plugins document that an unset key still works over the anonymous tier.
The Bearer form cannot express that: the server rejects `Bearer` with an empty
token while treating an empty or missing Authorization header as anonymous.
The raw-key form satisfies both states. It is genuinely parsed rather than
ignored, verified by an invalid raw key being rejected, so a set key still
authenticates while an unset one falls back to anonymous as documented.
Once the server treats an empty-token Bearer as no header, these can move to
the `Bearer <key>` form used everywhere else.
* refactor(cli): narrow the Codex OAuth probe and trim its surface
Only `oauth` proves a stored credential exists. `not_logged_in` also covers
"no credential, server merely advertises OAuth", which is the normal state for
anyone who never logged in, so treating it as stale told most users their
config held a credential it did not.
Collapse the module to the two functions the call site needs, derive nothing
from a hand-maintained status list, and skip the subprocess entirely when the
server is not already in Codex's config. Drop the probe timeout to 1.5s and
kill with SIGKILL so it is a real ceiling rather than an intent, since the
result is only an advisory hint.
Lock the plugin manifests' raw-key form behind a test, so normalizing them to
`Bearer` for consistency with the CLI fails loudly instead of silently
breaking anonymous access.
* refactor(cli): drop the Codex OAuth cleanup note
The note existed because re-running setup could not rescue a stuck user. The
Authorization header change in this same branch makes it rescue them: Codex
never reads the stored credential once that header is present, so the
credential is inert and the hint only offered cosmetic cleanup.
Removing it drops a subprocess spawn from a user-facing path and a dependency
on the shape of `codex mcp get --json`, an external contract this repo does not
pin. The reason the header name matters moves to `withHeaders`, where the
decision is encoded.
* 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
* refactor(skills): consolidate skills under /skills with canonical sources
- Rename skills/docs → skills/find-docs (name: find-docs)
- Rename skills/ctx7-cli → skills/context7-cli (name: context7-cli)
- Add skills/context7-mcp as canonical MCP skill source
- Rename plugin skill folders to context7-mcp and unify name to context7-mcp
- MCP setup now downloads context7-mcp skill from GitHub instead of using hardcoded SKILL_CONTENT
- Remove SKILL_CONTENT from templates.ts — skills/context7-mcp/SKILL.md is the single source of truth
- Add Error Handling section to find-docs skill for quota errors
- Update agents.ts skill name: documentation-lookup → context7-mcp
- Update docs/clients/cli.mdx and setup references accordingly
* chore: add changeset for skills consolidation
* fix(skills): update plugin skill frontmatter name and setup docs to context7-mcp
* feat(cli): add CLI mode to ctx7 setup with docs skill installation
- Add MCP vs CLI mode selection prompt at the start of setup
- CLI mode authenticates user and installs docs skill via promptForInstallTargets
- Add --cli, --universal, --antigravity flags to setup command
- --yes skips the detected-locations confirmation prompt
- Default CLI install scope to global (override with --project)
- Fix checkbox selected choices to render in green (consistent with select prompt)
- Move Claude Code above Universal in IDE selection order
- Add forceUniversal=false option to promptForInstallTargets for setup flow
- Add yes? to AddOptions to support auto-confirm in promptForInstallTargets
* chore: add changeset for ctx7 setup CLI mode
* feat(cli): rename CLI mode to CLI + Skills, add --mcp flag, remove recommended label
* feat(cli): add --api-key support to CLI mode and update docs
- Pass apiKey through to resolveCliAuth in CLI mode setup
- Store provided API key as bearer token for subsequent API calls
- Update cli.mdx and setup.md to reflect both MCP and CLI + Skills modes
* docs: update setup docs to reflect --api-key for both modes and --cursor for CLI
- --api-key works in both MCP and CLI + Skills mode (not MCP-only)
- --oauth clarified as MCP-only
- Added --cursor to CLI + Skills mode examples (Cursor has a skills directory)
- Updated auth table row for ctx7 setup
* fix(cli): improve library ID validation and add telemetry headers
- Validate /owner/repo format locally before spinner starts, showing
consistent error + hint for both "react" and "/react" inputs
- Send X-Context7-Source, X-Context7-Client-IDE, X-Context7-Client-Version,
and X-Context7-Transport headers on library/docs requests so CLI
appears in the admin telemetry dashboard
* feat(docs): add dedicated docs skill and restructure CLI documentation
- Add new `docs` skill as a single-file skill for documentation retrieval
- Align skill prompts with MCP tool descriptions (selection process, query guidance, 3-call limit)
- Enrich CLI docs page with result fields, query tips, and version-specific IDs
- Move CLI page to Overview section in docs nav
- Make `query` required for `ctx7 library` across all skills and docs
- Update trust score display label in skills.mdx
* feat(cli): align library output format with MCP labels
Use labeled fields and categorical Source Reputation labels
(High/Medium/Low/Unknown) instead of numeric trust scores to match
the MCP transport format.
* refactor: move skills from .agents/skills to skills/ at repo root
Source-control location for skills — users install them into
.agents/, .claude/, etc. via the CLI. Also updates install
instructions to use `npm install -g ctx7@latest` or `npx ctx7@latest`.
* docs: use natural-language query examples across skills and CLI docs
Replace keyword-style queries ("useEffect cleanup") with full
question-style queries ("How to clean up useEffect with async
operations") to better demonstrate how the query parameter works.
* docs: fix trust score description to show numeric range
Replaces the cli.mdx redirect stub with a full CLI reference covering library
documentation, setup, authentication, and all skills commands. Trims skills.mdx
to conceptual content only with a reference back to the CLI page. Updates the
ctx7-cli skill's docs reference with selection algorithm and query quality
guidance from the MCP tool prompts.
* fix: claude code plugin name and details image
* fix: claude code plugin name and details image
* update skill prompt
* fix: update plugin.json name and improve agent/skill instructions
* fix: update plugin README with correct install commands
* fix: remove max 3 calls warning
Fahreddin Özcan