Context7 MCP - 为AI代码编辑器提供最新代码文档

解决AI编程的核心痛点

Context7彻底改变了AI代码助手获取文档的方式，让每次代码生成都基于最新、准确的信息

❌ 没有Context7的问题

❌ 代码示例过时，基于年前的训练数据
❌ 幻觉API根本不存在
❌ 针对旧版本包的通用答案

✅ 使用Context7的优势

✅ 实时获取最新版本文档
✅ 版本特定的代码示例
✅ 直接从源码获取准确信息

技术架构

基于现代TypeScript和MCP协议构建的高性能文档服务器

🏗️ 核心架构

// 主要技术栈
• TypeScript
• Model Context Protocol (MCP)
• Node.js 18+
• Zod 验证
• Commander.js CLI
• Context7 API

⚡ 传输协议

// 支持的传输方式
stdio
  标准输入输出，默认模式
http
  HTTP服务器，端口3000
sse
  服务器发送事件

🔄

实时文档同步

通过Context7 API实时获取最新版本的库文档，支持版本特定的文档检索，确保代码生成始终基于当前版本

🎯

智能库匹配算法

基于名称相似度、描述相关性、文档覆盖率和信任评分的多维度匹配算法，精确识别目标库

📚

海量文档库

支持数千个主流开源项目，包括Next.js、React、Vue、Supabase、MongoDB、Prisma等热门框架和库

⚡

多协议传输

支持stdio、HTTP、SSE三种传输协议，自动端口检测和故障转移，适配各种MCP客户端环境

🔧

高级配置选项

支持主题聚焦、令牌数量控制、版本选择等高级配置，可根据具体需求定制文档检索范围和深度

🌐

生态系统兼容

原生支持20+主流AI代码编辑器和IDE，包括Cursor、Windsurf、VS Code、Claude Desktop、JetBrains等

🛡️

企业级稳定性

内置错误处理、速率限制、自动重试机制，支持Docker容器化部署，确保生产环境稳定运行

📊

性能优化

基于Alpine Linux的轻量级镜像，内存占用低，响应速度快，支持高并发请求处理

🔍

智能搜索引擎

基于语义理解的搜索算法，支持模糊匹配、同义词识别，即使输入不准确也能找到正确的库

详细使用示例

从基础用法到高级配置，全面掌握Context7的强大功能

🚀 基础使用示例

Next.js 中间件认证

// 用户提示
"Create a Next.js middleware that checks for a valid JWT in cookies and redirects unauthenticated users to /login. use context7"

Context7 提供： Next.js 14最新中间件API、JWT验证最佳实践、TypeScript类型定义

Supabase 数据库操作

// 用户提示
"Create a Supabase function to handle user registration with email verification. use context7"

Context7 提供： Supabase Auth API、Edge Functions、RLS策略配置

⚡ 高级使用技巧

🎯 指定特定库版本

// 直接使用库ID，跳过匹配步骤
"implement basic authentication with supabase. use library /supabase/supabase for api and docs"
// 指定特定主题
"show me mongodb aggregation pipeline examples. use context7 with topic 'aggregation'"

💡 专业提示： 使用具体的库ID可以获得更精确的文档，避免库匹配的不确定性

🔧 自动化规则配置

# .windsurfrules 或 Cursor Rules
[[calls]]
match = "when the user requests code examples, setup or configuration steps, or library/API documentation"
tool = "context7"
# 自动为特定框架调用Context7
[[calls]]
match = "when the user mentions Next.js, React, Vue, Supabase, or MongoDB"
tool = "context7"
args = { "auto_resolve": true }

⚙️ 自动化优势： 无需每次手动添加"use context7"，编辑器会自动调用相关文档

📝 实际代码输出示例

❌ 没有Context7的输出

// 可能过时的API
import { NextRequest } from 'next/server'
// 使用已废弃的方法
export function middleware(req: NextRequest) {
  // 错误的JWT验证方式
}

⚠️ 基于过时训练数据，可能包含已废弃的API

✅ 使用Context7的输出

// Next.js 14最新API
import { NextRequest, NextResponse } from 'next/server'
import { jwtVerify } from 'jose'
export async function middleware(request: NextRequest) {
  // 最新的JWT验证实现
}

✨ 基于最新文档，使用当前最佳实践

🚀 三步即可开始

1

描述需求

清晰描述你想要实现的功能或解决的问题

2

添加Context7

在提示末尾添加"use context7"或配置自动规则

3

获得精确代码

基于最新文档生成的可执行、准确的代码

安装指南

选择适合你的AI代码编辑器的安装方式

🎯

Cursor

在Cursor中配置Context7 MCP服务器

Settings → Cursor Settings → MCP
→ Add new global MCP server

// ~/.cursor/mcp.json
{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"]
    }
  }
}

🚀 一键安装到Cursor

💻

VS Code

在VS Code中配置Context7 MCP服务器

// settings.json
"mcp": {
  "servers": {
    "context7": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"]
    }
  }
}

🚀 一键安装到VS Code

🤖

Claude Desktop

在Claude Desktop中配置Context7

// claude_desktop_config.json
{
  "mcpServers": {
    "Context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"]
    }
  }
}

🏄

Windsurf

在Windsurf中配置Context7 MCP服务器

// Windsurf MCP config
{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"]
    }
  }
}

💡 专业提示

如果你不想每次都添加"use context7"，可以在编辑器中设置规则自动调用Context7

# .windsurfrules 或 Cursor Rules
[[calls]]
match = "when the user requests code examples, setup or configuration steps, or library/API documentation"
tool = "context7"

开发指南

深入了解Context7的开发配置和高级用法

🛠️ 本地开发环境

环境要求

✅ Node.js 18.0.0+
✅ npm 8.0.0+ 或 yarn 1.22.0+
✅ TypeScript 5.0+
✅ Git 2.25.0+
// 可选
🔶 Docker 20.0.0+
🔶 Bun 1.0.0+

快速启动

# 克隆仓库
git clone https://github.com/upstash/context7.git
cd context7
# 安装依赖
npm install
# 开发模式
npm run dev

⚙️ 高级配置选项

命令行参数

// 基础用法
npx @upstash/context7-mcp
// HTTP模式
npx @upstash/context7-mcp --transport http --port 3000
// SSE模式
npx @upstash/context7-mcp --transport sse --port 3001
// 调试模式
npx @upstash/context7-mcp --debug --log-level verbose

环境变量配置

# .env 文件配置
CONTEXT7_API_URL=https://api.context7.com
CONTEXT7_TIMEOUT=30000
CONTEXT7_MAX_TOKENS=10000
CONTEXT7_CACHE_TTL=3600
CONTEXT7_DEBUG=false
# 代理配置（可选）
HTTP_PROXY=http://proxy.company.com:8080
HTTPS_PROXY=https://proxy.company.com:8080

🐳 Docker容器化部署

Docker运行

# 拉取镜像
docker pull upstash/context7-mcp
# HTTP模式运行
docker run -p 8080:8080 \\
  upstash/context7-mcp \\
  --transport http --port 8080

Docker Compose

# docker-compose.yml
version: '3.8'
services:
  context7:
    image: upstash/context7-mcp
    ports:
      - "8080:8080"
    environment:
      - CONTEXT7_DEBUG=true

性能基准测试

Context7在各种场景下的性能表现和优化建议

📊 核心性能指标

< 200ms

平均响应时间

库匹配和文档检索

99.9%

可用性

月度平均正常运行时间

50MB

内存占用

Docker容器运行时

1000+

并发请求

单实例处理能力

🚀 基准测试结果

库匹配性能

// 测试场景：1000次库匹配请求
平均响应时间: 156ms
P95响应时间: 280ms
P99响应时间: 450ms
成功率: 99.8%
// 匹配准确率
精确匹配: 94.2%
相关匹配: 5.6%
无匹配: 0.2%

文档检索性能

// 测试场景：不同文档大小检索
小型文档 (<1MB): 89ms
中型文档 (1-5MB): 145ms
大型文档 (5-10MB): 234ms
超大文档 (>10MB): 456ms
// 缓存命中率
热门库: 89.3%
一般库: 67.8%

⚡ 性能优化建议

🎯 客户端优化

• 使用具体的库ID避免匹配延迟
• 限制tokens参数减少传输时间
• 启用本地缓存减少重复请求
• 使用topic参数聚焦文档范围

🏗️ 服务端优化

• 使用HTTP模式提高并发性能
• 配置适当的超时时间
• 部署多实例实现负载均衡
• 监控内存使用避免OOM

API工具详解

深入了解Context7 MCP提供的两个核心工具及其高级用法

🔍

resolve-library-id

智能库名称解析工具，支持模糊匹配和同义词识别

输入参数：

libraryName: string
要搜索的库名称（必需）
支持：完整名称、简称、别名

返回格式：

// 成功匹配
{
  "id": "/vercel/next.js",
  "name": "Next.js",
  "confidence": 0.95,
  "description": "The React Framework"
}

// 使用示例
resolve-library-id("nextjs")
resolve-library-id("react router")
resolve-library-id("mongodb")
resolve-library-id("tailwind")

📚

get-library-docs

高性能文档检索工具，支持主题聚焦和令牌控制

输入参数：

context7CompatibleLibraryID: string
精确的Context7库ID（必需）
topic?: string
聚焦特定主题（可选）
tokens?: number
最大令牌数，默认10000（可选）

返回内容：

• API参考文档
• 使用指南和教程
• 代码示例
• 最佳实践
• 配置选项

// 使用示例
get-library-docs("/mongodb/docs")
get-library-docs("/vercel/next.js", "middleware")
get-library-docs("/supabase/supabase", "auth", 5000)

🎯 高级用法示例

工作流组合

// 1. 先解析库ID
const result = resolve-library-id("prisma")
// 返回: /prisma/prisma
// 2. 获取特定主题文档
get-library-docs("/prisma/prisma", "migrations")
// 3. 限制令牌数量
get-library-docs("/prisma/prisma", "schema", 3000)

错误处理

// 库未找到
resolve-library-id("nonexistent-lib")
// 返回: null 或建议列表
// 无效库ID
get-library-docs("/invalid/id")
// 返回: 错误信息
// 超时处理
// 自动重试 + 降级策略

⚡ API性能优化技巧

🎯 直接使用库ID

// 跳过匹配步骤，直接获取文档
"use library /vercel/next.js for middleware docs"

节省 ~100ms 匹配时间

🔍 主题聚焦

// 只获取相关部分，减少传输
get-library-docs("/mongodb/docs", "aggregation")

减少 60-80% 数据传输

项目配置指南

为你的开源项目添加Context7支持，让AI更好地理解和使用你的库

📝 context7.json配置文件

完整配置示例

// context7.json - 放在项目根目录
{
  "$schema": "https://context7.com/schema/context7.json",
  "projectTitle": "Upstash Ratelimit",
  "description": "Ratelimiting library based on Upstash Redis",
  "folders": ["docs", "examples", "guides"],
  "excludeFolders": ["src", "build", "node_modules"],
  "excludeFiles": ["CHANGELOG.md", "LICENSE"],
  "rules": [
    "Use Upstash Redis as a database",
    "Use single region set up",
    "Always handle rate limit errors gracefully"
  ],
  "previousVersions": [
    { "tag": "v1.2.1", "title": "version 1.2.1" }
  ]
}

配置字段说明

projectTitle
项目显示名称，覆盖仓库名
description
简短描述，帮助AI理解项目用途
folders
包含的文档目录，支持正则表达式
excludeFolders
排除的目录，避免索引源码

最佳实践建议

✅ 描述简洁明确： 一句话说明库的核心功能
✅ 排除无关内容： 避免索引源码、测试、构建文件
✅ 添加使用规则： 包含常见陷阱和最佳实践
✅ 维护版本历史： 保持重要版本的可访问性

🚀 提交你的项目

🌐

在线提交

通过Context7官网快速提交GitHub仓库

🔗 提交项目

📝

添加配置

在项目根目录添加context7.json配置文件

                                    your-project/

                                    ├── context7.json

                                    ├── README.md

                                    └── docs/

🔄

自动同步

Context7自动检测更新并重新索引文档

✅ 自动检测推送
✅ 增量更新
✅ 版本管理

故障排除

常见问题解决方案和调试技巧

🔧 常见问题

❌ MCP服务器无法启动

可能原因：

• Node.js版本过低（需要18.0.0+）
• 端口被占用（HTTP模式）
• 网络连接问题
• 权限不足

解决方案：

# 检查Node.js版本
node --version
# 检查端口占用
lsof -i :3000
# 使用不同端口
npx @upstash/context7-mcp --port 3001

❌ 库匹配失败或不准确

可能原因：

• 库名称拼写错误
• 库未被Context7收录
• 使用了非标准名称

解决方案：

# 尝试不同的名称变体
resolve-library-id("nextjs")
resolve-library-id("next.js")
resolve-library-id("next")
# 直接使用库ID
get-library-docs("/vercel/next.js")

❌ 响应速度慢或超时

可能原因：

• 网络延迟高
• 请求的文档过大
• Context7服务器负载高

解决方案：

# 限制令牌数量
get-library-docs("/mongodb/docs", "aggregation", 3000)
# 使用主题聚焦
get-library-docs("/vercel/next.js", "middleware")
# 增加超时时间
CONTEXT7_TIMEOUT=60000 npx @upstash/context7-mcp

🐛 调试技巧

启用详细日志

# 启用调试模式
npx @upstash/context7-mcp --debug
# 详细日志级别
CONTEXT7_DEBUG=true npx @upstash/context7-mcp

检查网络连接

# 测试API连接
curl -I https://api.context7.com
# 检查代理设置
echo $HTTP_PROXY

社区与支持

加入Context7社区，获取帮助和最新动态

📦

GitHub仓库

查看源码、提交问题、参与开发

17.1K Stars ⭐

🌐

官方网站

浏览文档库、添加新项目

💬

Discord社区

加入讨论、获取实时帮助

📢

关注动态

获取最新更新和功能发布

⚠️ 免责声明

Context7项目由社区贡献，虽然我们努力维护高质量，但不能保证所有库文档的准确性、完整性或安全性。项目由各自所有者开发和维护，而非Context7。如果遇到可疑、不当或潜在有害内容，请使用项目页面的"举报"按钮立即通知我们。