feat(plugins): add portable Agent Plugin for Context7 (#2998)

Co-authored-by: enesgules <abdullah.enes.gules@gmail.com>
2026-09-14 19:09:34 +08:00 · 2026-08-09 22:09:19 +03:00
parent 8276a7c35f
commit 6a799754d0
5 changed files with 200 additions and 0 deletions
@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2021 Upstash, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
@@ -0,0 +1,99 @@
+# Context7 Agent Plugin
+
+A portable [Agent Plugin](https://agent-plugins.org) (spec 1.0.0) that gives any compatible agent
+current, version-specific library documentation through the Context7 MCP server.
+
+AI coding assistants rely on training data that goes stale and invents APIs that never existed.
+Context7 fetches real documentation from source repositories at query time instead.
+
+## What's Included
+
+| Component  | Location               | Description                                                      |
+| ---------- | ---------------------- | ---------------------------------------------------------------- |
+| MCP server | `mcp.json`             | Remote Context7 server over Streamable HTTP, authorized by OAuth |
+| Skill      | `skills/context7-mcp/` | Triggers documentation lookups when you ask about a library      |
+
+## Layout
+
+```text
+context7/
+├── plugin.json
+├── mcp.json
+├── skills/
+│   └── context7-mcp/
+│       └── SKILL.md
+├── LICENSE
+└── README.md
+```
+
+This is the entire plugin. Agent Plugins uses fixed locations, so every compatible client reads
+the same two files: `plugin.json` at the root, and `mcp.json` for MCP configuration. Clients that
+support skills discover them under `skills/`.
+
+## Installation
+
+Install the directory with your client's plugin command. The exact command differs per client,
+but every conformant client accepts a plugin directory path:
+
+```bash
+<your-agent> plugin install ./plugins/agent-plugins/context7
+```
+
+You can also install straight from the repository if your client supports remote sources.
+
+## Authentication
+
+The plugin points at `https://mcp.context7.com/mcp/oauth`, which authorizes with OAuth 2.1.
+
+On first connection the server answers `401` with a `WWW-Authenticate` header. Your client then
+discovers the authorization server, registers itself dynamically, and opens a browser for you to
+approve access. Tokens are stored by the client. You do not paste a key anywhere, and no secret
+is written into this repository.
+
+The flow supports Dynamic Client Registration and PKCE (`S256`), so no pre-registration is needed.
+
+### Why not an API key?
+
+Agent Plugins 1.0 deliberately has no field for credentials. Two rules in the spec make an API
+key impossible to ship here:
+
+- Clients must not expand `${VAR}` placeholders in `url` or in header names and values.
+- Header values are "visible package data" and plugins must not embed secrets in them.
+
+So the `"Authorization": "${CONTEXT7_API_KEY}"` pattern used by some client-specific plugins in
+this repository is not portable. OAuth is the only way a user can authenticate their own account
+in this format, which is why this plugin uses the OAuth endpoint.
+
+### Client support
+
+Authorization is client-managed in this spec version. A client that cannot run an OAuth flow will
+fail to connect to this server. The spec treats that as a connection failure for one server, not
+as a broken plugin, so the skill still loads. If your client has no OAuth support, use the
+client-specific plugin for it in [`plugins/`](../../) instead.
+
+## Available Tools
+
+### `resolve-library-id`
+
+Searches for libraries and returns Context7-compatible identifiers such as `/vercel/next.js`.
+
+### `query-docs`
+
+Fetches documentation for a resolved library ID, scoped to a single concept per call.
+
+## Notes on Portability
+
+- `plugin.json` uses a closed schema. Only `$schema`, `name`, `version`, `description`, `author`,
+  `homepage`, `repository`, `license`, `keywords`, and `extensions` are permitted at the top level.
+  Component paths cannot be declared in the manifest, unlike the Codex and Copilot manifests in
+  this repository.
+- No `extensions` namespace is set. Client-specific data belongs under a reverse-domain key that
+  the client itself defines, so nothing is claimed here.
+- Commands, agents, hooks, and rules are not portable component types in version 1.0. The
+  `/context7:docs` command and the `docs-researcher` agent stay in the client-specific plugins.
+
+## Links
+
+- [Context7](https://context7.com) · [Dashboard](https://context7.com/dashboard)
+- [Agent Plugins specification](https://agent-plugins.org/specification)
+- [Agent Skills specification](https://agentskills.io/specification)
@@ -0,0 +1,9 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
+  "mcpServers": {
+    "context7": {
+      "type": "streamable-http",
+      "url": "https://mcp.context7.com/mcp/oauth"
+    }
+  }
+}
@@ -0,0 +1,15 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "context7",
+  "version": "1.0.0",
+  "description": "Up-to-date documentation lookup. Pull version-specific documentation and code examples directly from source repositories into your LLM context.",
+  "author": {
+    "name": "Upstash",
+    "email": "context7@upstash.com",
+    "url": "https://upstash.com"
+  },
+  "homepage": "https://context7.com",
+  "repository": "https://github.com/upstash/context7",
+  "license": "MIT",
+  "keywords": ["documentation", "context", "mcp", "library-docs"]
+}
@@ -0,0 +1,56 @@
+---
+name: context7-mcp
+description: Fetches current, version-specific library documentation and code examples through the Context7 MCP server. Use whenever the user asks about a library, framework, SDK, API, CLI tool, or cloud service, including API syntax, configuration, setup instructions, version migration, CLI usage, and library-specific debugging. Use when generating code that calls a third-party library, and when the user names a version such as Next.js 15 or React 19. Use even for well-known libraries like React, Vue, Next.js, Prisma, Supabase, Express, Tailwind, Django, and Spring Boot, because training data may not reflect recent changes. Prefer this over web search for library documentation. Do not use it for refactoring, writing scripts from scratch, debugging business logic, code review, or general programming concepts, or when the user has already supplied the relevant documentation.
+---
+
+When the user asks about libraries, frameworks, or needs code examples, use Context7 to fetch current documentation instead of relying on training data.
+
+## When to Use This Skill
+
+Activate this skill when the user:
+
+- Asks setup or configuration questions ("How do I configure Next.js middleware?")
+- Requests code involving libraries ("Write a Prisma query for...")
+- Needs API references ("What are the Supabase auth methods?")
+- Mentions specific frameworks (React, Vue, Svelte, Express, Tailwind, etc.)
+
+## How to Fetch Documentation
+
+### Step 1: Resolve the Library ID
+
+Call `resolve-library-id` with:
+
+- `libraryName`: The library name extracted from the user's question
+- `query`: What to look up in the library's documentation (improves relevance ranking)
+
+### Step 2: Select the Best Match
+
+From the resolution results, choose based on:
+
+- Exact or closest name match to what the user asked for
+- Higher benchmark scores indicate better documentation quality
+- If the user mentioned a version (e.g., "React 19"), prefer version-specific IDs
+
+### Step 3: Fetch the Documentation
+
+Call `query-docs` with:
+
+- `libraryId`: The selected Context7 library ID (e.g., `/vercel/next.js`)
+- `query`: What to look up in the library's documentation, scoped to a single concept
+
+If the user's question spans multiple distinct concepts (e.g. routing and auth and caching), make a separate `query-docs` call per concept with the same library ID, unless the question is about how the concepts interact. Combined queries dilute ranking and return shallow results for each topic.
+
+### Step 4: Use the Documentation
+
+Incorporate the fetched documentation into your response:
+
+- Answer the user's question using current, accurate information
+- Include relevant code examples from the docs
+- Cite the library version when relevant
+
+## Guidelines
+
+- **Be specific**: Describe what to look up in the library's documentation, but keep each query to a single concept
+- **One topic per query**: Split multi-topic questions into separate `query-docs` calls. Resolve the library ID once, then query per concept, unless the question is about how the concepts interact
+- **Version awareness**: When users mention versions ("Next.js 15", "React 19"), use version-specific library IDs if available from the resolution step
+- **Prefer official sources**: When multiple matches exist, prefer official/primary packages over community forks