Introducing a new way to review your PRs.

Read the announcement

upstash / context7

Context7 Platform -- Up-to-date docs for AI agents

View on GitHub

13 documents · Updated Nov 16, 2026

docs / opencode

OpenCode integration package

Overview

packages/opencode publishes @upstash/context7-opencode, the OpenCode plugin that registers the hosted Context7 MCP server and the bundled context7-mcp skill. The package entrypoint is packages/…/index.ts, exported as ESM from packages/…/package.json through ./…/index.js with declarations at ./…/index.d.ts.

The runtime entrypoint supports both OpenCode plugin APIs from the same default export. For OpenCode v2, src/index.ts exports a plugin object with id: "context7" and an async setup(ctx) method. setup resolves an API key from ctx.options.apiKey or process.env.CONTEXT7_API_KEY, then uses ctx.mcp.transform to add a context7 remote MCP server only when the user has not already configured one, and ctx.skill.transform to add the bundled skill only when a context7-mcp skill is not already present. For OpenCode v1, the same default export also exposes server(_input, options), which returns a config(config) hook that mutates the OpenCode config object in place: it ensures config.mcp.context7 exists and appends the package skills directory to config.skills.paths.

Authentication behavior is centralized in packages/…/index.ts. Without an API key, the MCP server points at https://mcp.context7.com/mcp/oauth, letting OpenCode start OAuth on first use. With an apiKey option or CONTEXT7_API_KEY, the server points at https://mcp.context7.com/mcp and sends Authorization: Bearer <key> with oauth: false. In both v1 and v2 paths, existing user configuration wins: the v2 transforms skip an existing context7 MCP server or context7-mcp skill, and the v1 config hook uses nullish assignment before adding its defaults.

The bundled skill lives at packages/…/SKILL.md. src/index.ts loads it directly from disk with readFileSync, parses the YAML-style frontmatter for the description, strips the frontmatter from the content, and registers it with id, name, and path all tied to context7-mcp/the concrete SKILL.md path. The skill tells OpenCode when to use Context7 for library, framework, API-reference, setup, code-generation, and exact-source-fact questions. It instructs the agent to resolve a library first with resolve-library-id, query docs with query-docs, split multi-topic questions into separate doc queries, and optionally use query-code for source-level facts such as signatures, defaults, option names, and error origins.

User-facing package documentation is in packages/…/README.md. It documents OpenCode v2 installation with opencode plugin add @upstash/context7-opencode, OpenCode v1 installation with opencode plugin @upstash/context7-opencode, project config shapes for the v2 plugins key and v1 plugin key, OAuth-vs-API-key setup, override semantics for a preconfigured context7 MCP server, and the context7_resolve-library-id / context7_query-docs tools. Release notes are maintained in packages/…/CHANGELOG.md; the current history records the initial v1 plugin, v2 setup support, and later prompt/example updates. packages/opencode/LICENSE is the MIT license included in the published package.

Build and package configuration are local to packages/opencode. packages/…/tsup.config.ts builds src/index.ts to Node 20 ESM, emits sourcemaps and declarations, cleans dist, and keeps @opencode-ai/plugin external while suppressing tsup's TypeScript 6 baseUrl deprecation only in the declaration worker. packages/…/tsconfig.json typechecks the source, tsup config, and eslint config under strict ESNext/bundler settings with noEmit. packages/…/eslint.config.js applies TypeScript ESLint and Prettier rules to TS/TSX files, using packages/…/tsconfig.json as the parser project. packages/…/package.json publishes only dist, skills, LICENSE, and README.md, so the runtime ../…/SKILL.md lookup depends on the skills directory remaining in files.

Coupling

  • If packages/…/index.ts changes SKILL_NAME, SKILLS_DIR, SKILL_FILE, or the way skill frontmatter is parsed, also update packages/…/SKILL.md and verify packages/…/package.json still publishes skills; otherwise OpenCode can load the plugin but fail to register the skill or register it without a useful description.
  • If packages/…/SKILL.md changes tool names or call guidance, also update packages/…/README.md where it describes the available Context7 tools; users otherwise see install documentation that disagrees with the agent behavior shipped in the skill.
  • If the Context7 MCP host, OAuth path, server name, or API-key header changes in packages/…/index.ts, update packages/…/README.md authentication and override sections at the same time; the README promises that OAuth is the default, CONTEXT7_API_KEY sends an Authorization header, and a user-defined MCP server named context7 takes precedence.
  • If OpenCode plugin API types change in @opencode-ai/plugin or @opencode/plugin, check both the v2 setup branch and the v1 server branch in packages/…/index.ts; the package intentionally has only a default export because the legacy loader treats extra exports as additional plugins.
  • If the package output path, module format, or published file list changes in packages/…/package.json or packages/…/tsup.config.ts, verify the runtime file-relative skill lookup from built dist/index.js to ../…/SKILL.md; changing only the build layout can break skill loading without TypeScript noticing.

Risks

  • packages/…/index.ts reads packages/…/SKILL.md synchronously at plugin setup time using a file path relative to the emitted dist/index.js. If packages/…/package.json stops publishing skills or packages/…/tsup.config.ts changes the output layout, plugin setup can fail before OpenCode gets the skill.
  • packages/…/index.ts casts OpenCode v1 config to ConfigWithSkills because the @opencode-ai/plugin Config type does not declare skills even though the schema accepts it. If OpenCode renames or reshapes the skills.paths config, TypeScript may not catch the break and v1 users would lose the bundled skill path.
  • Recent package history includes compatibility work for OpenCode v2 (635cfc8) and prompt/tool guidance updates (2111b92, d80a84c) under packages/opencode. Changes in packages/…/index.ts or packages/…/SKILL.md should be checked against both OpenCode versions and the current MCP tool names, because this package has already needed updates for API-version and tool-surface drift.