diff --git a/QUICKSTART.md b/QUICKSTART.md index 272f3ef..f197ba7 100644 --- a/QUICKSTART.md +++ b/QUICKSTART.md @@ -96,3 +96,25 @@ claude plugin list ``` 👉 詳情:[playwright-plugin-notes.md](./playwright-plugin-notes.md) + +--- + +## Context7 Plugin — 即時文件查詢 + +安裝: + +```bash +claude plugin install context7@claude-plugins-official +``` + +使用(在 prompt 尾端加上關鍵字): + +> 幫我寫一段 Next.js middleware 檢查 cookie 中的 JWT。**use context7** + +指定函式庫: + +```text +use library /supabase/supabase for API and docs +``` + +👉 詳情:[context7-plugin-notes.md](./context7-plugin-notes.md) diff --git a/README.md b/README.md index c566a4d..b357a88 100644 --- a/README.md +++ b/README.md @@ -10,6 +10,7 @@ | **MemPalace** | 階層式本地記憶庫(Wing / Room / Drawer),支援向量搜尋與 MCP 整合 | [mempalace-notes.md](./mempalace-notes.md) | | **Playwright (Python)** | 瀏覽器自動化、E2E 測試、截圖與 PDF 輸出 | [playwright-notes.md](./playwright-notes.md) | | **Playwright Plugin (Claude Code)** | 讓 Claude 直接操作瀏覽器的官方 plugin(MCP server) | [playwright-plugin-notes.md](./playwright-plugin-notes.md) | +| **Context7 Plugin (Claude Code)** | Upstash 出品,即時拉取 library 官方文件餵給 Claude | [context7-plugin-notes.md](./context7-plugin-notes.md) | ## 目錄結構 @@ -23,6 +24,7 @@ tool-notes/ ├── mempalace-notes.md ├── playwright-notes.md ├── playwright-plugin-notes.md +├── context7-plugin-notes.md └── mempalace.yaml # 本目錄的 MemPalace 設定 ``` diff --git a/SUMMARY.md b/SUMMARY.md index d99b541..a33b1b3 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -10,6 +10,7 @@ | MemPalace | 本地記憶庫 | 向量搜尋、階層式組織、LLM 壓縮 | Python / CLI / MCP | MIT | | Playwright (Python) | 瀏覽器自動化 | 多瀏覽器控制、E2E 測試、截圖/PDF | Python / CLI | Apache-2.0 | | Playwright Plugin | Claude Code 外掛 | 讓 Claude 直接操作瀏覽器(透過 MCP)| Claude Code / MCP | Apache-2.0 | +| Context7 Plugin | Claude Code 外掛 | 即時拉取 library 文件到 Claude context | Claude Code / MCP | MIT | ## MarkItDown @@ -55,6 +56,17 @@ - Python 版寫在專案裡做 CI / 長期腳本。 - Plugin 版給 Claude 在對話中臨場操作。 +## Context7 Plugin (Claude Code) + +- **一句話**:Upstash 的 MCP server,讓 Claude 在回答 library 問題前即時查到最新官方文件。 +- **亮點**: + - 兩個工具:`resolve-library-id`、`query-docs`。 + - 支援版本指定,能對付「我用的是 Next.js 15 而不是 13」這種情境。 + - 觸發簡單:prompt 加 `use context7` 即可。 + - 解決訓練資料過時 → 幻覺 API / 廢棄寫法的問題。 +- **不適用**:重構、業務邏輯、通用程式概念、code review。 +- **適用時機**:寫 library-specific 程式、版本遷移、API 語法確認、冷門套件查詢。 + ## 三者如何一起用? 一個常見組合: diff --git a/context7-plugin-notes.md b/context7-plugin-notes.md new file mode 100644 index 0000000..543be8f --- /dev/null +++ b/context7-plugin-notes.md @@ -0,0 +1,144 @@ +# 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 查文件,減少雜訊。