drjaniuk 学习知识库

Appearance

故障排除 ​

本指南帮助您解决设置或使用 Context7 MCP 时的常见问题。

快速检查清单 ​

  • 确认已安装 Node.js v18+ (node --version)
  • 更新到最新的 Context7 MCP 包 (@upstash/context7-mcp@latest)
  • 使用 curl https://mcp.context7.com/mcp/ping 验证连接性
  • 如果遇到速率限制，请将您的 API 密钥添加到配置中
  • 在收集支持信息之前启用调试日志 (DEBUG=*)

安装问题 ​

模块未找到错误 ​

如果遇到 ERR_MODULE_NOT_FOUND，请尝试使用 bunx 代替 npx：

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

当您使用 npx 遇到模块解析错误时，请使用此方法。

ESM 解析问题 ​

对于诸如 Error: Cannot find module 'uriTemplate.js' 之类的错误，请尝试使用 --experimental-vm-modules 标志：

json
{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "--node-options=--experimental-vm-modules", "@upstash/context7-mcp@1.0.6"]
    }
  }
}

TLS/证书问题 ​

使用 --experimental-fetch 标志来绕过 TLS 相关问题：

json
{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "--node-options=--experimental-fetch", "@upstash/context7-mcp"]
    }
  }
}

快速修复 ​

  1. 尝试将 @latest 添加 到包名称，以确保您使用的是最新版本：
json
{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp@latest", "--api-key", "YOUR_API_KEY"]
    }
  }
}
  1. 使用 bunx 作为 npx 的替代方案：
json
{
  "mcpServers": {
    "context7": {
      "command": "bunx",
      "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"]
    }
  }
}
  1. 考虑使用 deno 作为另一种运行时替代方案：
json
{
  "mcpServers": {
    "context7": {
      "command": "deno",
      "args": [
        "run",
        "--allow-env=NO_DEPRECATION,TRACE_DEPRECATION",
        "--allow-net",
        "npm:@upstash/context7-mcp"
      ]
    }
  }
}
  1. 确保您使用的是 Node.js v18 或更高版本 以获得原生 fetch 支持：
bash
node --version

如果您使用的是旧版本，请将 Node.js 升级到 v18 或更高版本。

特定平台问题 ​

Windows 问题 ​

请求超时错误 ​

在 Windows 上，一些用户可能会在使用默认配置时遇到请求超时错误。尝试使用 Node.js 和已安装包的完整路径：

json
{
  "mcpServers": {
    "context7": {
      "command": "C:\\Program Files\\nodejs\\node.exe",
      "args": [
        "C:\\Users\\yourname\\AppData\\Roaming\\npm\\node_modules\\@upstash\\context7-mcp\\dist\\index.js",
        "--transport",
        "stdio",
        "--api-key",
        "YOUR_API_KEY"
      ]
    }
  }
}

或者，使用 cmd 的此配置：

json
{
  "mcpServers": {
    "context7": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"]
    }
  }
}

macOS 问题 ​

请求超时错误 ​

在 macOS 上，一些用户可能会遇到相同的请求超时错误。使用 Node.js 和已安装包的完整路径：

json
{
  "mcpServers": {
    "context7": {
      "command": "/Users/yourname/.nvm/versions/node/v22.14.0/bin/node",
      "args": [
        "/Users/yourname/.nvm/versions/node/v22.14.0/lib/node_modules/@upstash/context7-mcp/dist/index.js",
        "--transport",
        "stdio",
        "--api-key",
        "YOUR_API_KEY"
      ]
    }
  }
}

API 和连接问题 ​

速率限制 ​

如果遇到速率限制错误：

  • 获取 API 密钥：在 context7.com/dashboard 注册以获得更高的速率限制
  • 将 API 密钥添加到您的配置中：
json
{
  "mcpServers": {
    "context7": {
      "url": "https://mcp.context7.com/mcp",
      "headers": {
        "CONTEXT7_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

身份验证错误 ​

如果看到 401 Unauthorized 错误：

  1. 验证您的 API 密钥 是否正确且以 ctx7sk 开头
  2. 检查头部格式 - 确保正确设置了 API 密钥：

对于 HTTP 传输：

json
{
  "headers": {
    "CONTEXT7_API_KEY": "YOUR_API_KEY"
  }
}

对于 stdio 传输：

json
{
  "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"]
}

库未找到 ​

如果收到 404 Not Found 错误：

  1. 验证库 ID 格式是否正确：/owner/repo 或 /owner/repo/version
  2. 搜索库 首先使用 resolve-library-id 工具
  3. 检查库是否存在 于 context7.com

MCP 客户端特定问题 ​

Cursor ​

  • 确保您使用的是 Cursor 1.0 或更高版本以获得最佳 MCP 支持
  • 尝试全局 (~/.cursor/mcp.json) 和项目特定 (.cursor/mcp.json) 配置
  • 更改 MCP 配置后重新启动 Cursor

VS Code ​

  • 确保您拥有支持 MCP 的最新版 VS Code
  • 检查 Copilot 扩展是否已安装并更新
  • 配置更改后重新启动 VS Code

Claude Code ​

  • 使用 claude mcp list 验证 MCP 服务器是否已正确添加
  • 使用 claude mcp logs context7 检查日志
  • 尝试移除并重新添加服务器

代理问题 ​

如果您在企业代理后面：

  1. 在启动 MCP 客户端之前设置环境变量：
bash
export https_proxy=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
  1. 或添加到您的 MCP 配置中：
json
{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"],
      "env": {
        "https_proxy": "http://proxy.example.com:8080",
        "HTTPS_PROXY": "http://proxy.example.com:8080"
      }
    }
  }
}

查看 使用指南 - 配置 HTTPS 代理 了解更多详情。

调试提示 ​

启用详细日志记录 ​

将调试输出添加到您的配置中：

json
{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"],
      "env": {
        "DEBUG": "*"
      }
    }
  }
}

使用 MCP Inspector 进行测试 ​

独立测试您的设置：

bash
npx -y @modelcontextprotocol/inspector npx @upstash/context7-mcp

这将打开一个交互式检查器来测试 Context7 工具。

检查服务器状态 ​

测试远程服务器是否可达：

bash
curl https://mcp.context7.com/mcp/ping

预期响应：{"status": "ok", "message": "pong"}

额外支持 ​

如果这些解决方案无法解决您的问题：

  1. 检查 GitHub Issues：在 github.com/upstash/context7/issues 搜索类似问题
  2. 创建新 Issue：包括您的：
    • 操作系统和版本
    • Node.js 版本 (node --version)
    • MCP 客户端和版本
    • 配置（移除敏感数据如 API 密钥）
    • 错误消息和日志
  3. 加入 Discord：在 upstash.com/discord 获取社区帮助

其他资源 ​