# Context7 Plugin (Claude Code) 安裝與使用筆記

## 基本資訊

- **專案頁**: https://claude.com/plugins/context7
- **官方**: [Upstash](https://upstash.com)
- **原始碼**: https://github.com/upstash/context7
- **Marketplace**: `claude-plugins-official`（Anthropic 官方）
- **類型**: Claude Code 外掛（包裝 `@upstash/context7-mcp` MCP server）
- **核心套件**: [`@upstash/context7-mcp`](https://www.npmjs.com/package/@upstash/context7-mcp)（`npx -y @upstash/context7-mcp`）
- **安裝規模**: 230,000+（官方 marketplace 顯示）
- **安裝日期**: 2026-04-19

## 是什麼

Context7 是 Upstash 推出的 MCP server，用來解決 LLM 訓練資料過時、產生幻覺 API 或沿用已廢棄寫法的問題。它從各函式庫的**原始 repo 直接抓取文件**餵給 Claude，支援指定版本。

Plugin 提供兩個工具：

| 工具 | 用途 |
|------|------|
| `resolve-library-id` | 把「react」「supabase」這類自然語言名稱解析成 Context7 內部 ID |
| `query-docs` | 依據 library ID 取回該版本的官方文件與範例程式 |

**適用**：寫 library-specific 程式（API 呼叫、框架設定、CLI 用法、版本升級）、debug 特定套件問題、確認某個 API 在 vX 版是否存在。

**不適用**：重構、從頭寫業務邏輯、一般程式概念、code review。

## 安裝

### CLI（推薦）

```bash
claude plugin install context7@claude-plugins-official
```

### Claude Code 對話內

```text
/plugin install context7@claude-plugins-official
```

官方 marketplace `claude-plugins-official` 預設已加入，不需額外設定。

### 安裝後驗證

```bash
claude plugin list                                         # 應列出 context7@claude-plugins-official
ls ~/.claude/plugins/cache/claude-plugins-official/context7/
```

Plugin 真正的能力來自 `@upstash/context7-mcp`，第一次使用時 `npx` 會自動下載。

## 架構

和 Playwright plugin 一樣，這是一層薄殼：

```
context7/
├── .claude-plugin/plugin.json   # plugin metadata
└── .mcp.json                    # 啟動 MCP server 的指令
```

`.mcp.json`：

```json
{
  "context7": {
    "command": "npx",
    "args": ["-y", "@upstash/context7-mcp"]
  }
}
```

### 系統需求

- Node.js（`npx` 可用即可）
- 第一次啟動會從 npm 下載 `@upstash/context7-mcp`，需要網路

## 使用方式

安裝並重啟 Claude Code 後，對話中會出現 `mcp__context7__resolve-library-id` 與 `mcp__context7__query-docs` 兩個工具。觸發方式有兩種：

### 1. 在 prompt 尾端加 `use context7`

Upstash 官方建議寫法，最直覺：

> 「寫一段 Next.js middleware 檢查 cookie 中的 JWT。use context7」
>
> 「用 Cloudflare Workers 寫一個會快取 JSON API 回應的 script。use context7」

### 2. 指定特定 library 版本

```text
use library /supabase/supabase for API and docs
```

或在問題中直接提到 library 與版本：

> 「我在用 Prisma 5.10，幫我寫一個 soft delete 的 middleware。use context7」

### 觸發時機（本 repo CLAUDE 規範）

本 repo 的工具層規範已指定：**當使用者問到 library / framework / SDK / API / CLI / cloud service 的用法時，即使是很熟的（React、Next.js、Django…）也應優先用 Context7**，理由是訓練資料可能過時。不適用於一般重構或業務邏輯。

## 常見使用情境

- **版本遷移**：Next.js 13 → 15、React 18 → 19、Prisma 4 → 5。
- **API 語法確認**：某個 method 的參數、deprecated 警告、replacement。
- **設定檔樣板**：`vite.config.ts`、`tailwind.config.js`、`drizzle.config.ts` 的最新格式。
- **CLI 指令查詢**：`gh`、`wrangler`、`supabase` 等工具的現行子指令。
- **冷門 library**：訓練資料很少、但 repo 裡有文件的專案。

## 常用檢查與移除

```bash
# 檢查安裝狀態
claude plugin list

# 檢視 plugin metadata
cat ~/.claude/plugins/marketplaces/claude-plugins-official/external_plugins/context7/.claude-plugin/plugin.json
cat ~/.claude/plugins/marketplaces/claude-plugins-official/external_plugins/context7/.mcp.json

# 手動測試 MCP server
npx -y @upstash/context7-mcp --help
```

移除：

```bash
claude plugin uninstall context7@claude-plugins-official
```

或在 Claude Code 對話中：

```text
/plugin uninstall context7@claude-plugins-official
```

## 備註

- Plugin 本體沒有鎖版本（顯示為 `unknown`），能力跟著 `@upstash/context7-mcp` 的 latest 走。
- Context7 是 Upstash 提供的線上服務，每次查詢會連到他們的 endpoint；離線環境無法使用。
- 與 web search 的差異：Context7 專注在 library docs（結構化、版本化），web search 則是通用搜尋；優先用 Context7 查文件，減少雜訊。