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 publishesskills; 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_KEYsends an Authorization header, and a user-defined MCP server namedcontext7takes precedence. - If OpenCode plugin API types change in
@opencode-ai/pluginor@opencode/plugin, check both the v2setupbranch and the v1serverbranch 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
skillsor 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
ConfigWithSkillsbecause the@opencode-ai/pluginConfigtype does not declareskillseven though the schema accepts it. If OpenCode renames or reshapes theskills.pathsconfig, 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) underpackages/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.