Nexus

🚀 🔍 Nexus MCP Server

Nexus MCP Server 是一个生产就绪的 模型上下文协议（MCP）服务器，它能将人工智能驱动的网络搜索直接集成到你的开发环境中。只需一个命令，你就能在 Claude Desktop、Cursor 或任何兼容 MCP 的客户端中获得带有正确引用的智能搜索结果。

🚀 快速开始

前置要求

• Node.js 16 或更高版本
• 一个 OpenRouter API 密钥（可在 OpenRouter 获取）

零配置安装

无需构建步骤、无需依赖项、无需设置：

# 设置你的 OpenRouter API 密钥
export OPENROUTER_API_KEY=your-api-key-here

# 立即运行服务器
npx nexus-mcp

搞定！服务器现已运行，随时准备与 MCP 客户端建立连接。

测试 NPX 安装

# 测试 CLI 帮助
npx nexus-mcp --help

# 测试版本
npx nexus-mcp --version

# 使用你的 API 密钥运行
OPENROUTER_API_KEY=your-key npx nexus-mcp

替代方案：本地开发安装

如果你想进行本地开发或定制：

1. 克隆仓库：

git clone https://github.com/adawalli/nexus.git
cd nexus

2. 安装依赖项：

npm install

3. 构建服务器：

npm run build

4. 配置你的 OpenRouter API 密钥：

# 复制示例环境文件
cp .env.example .env

# 编辑 .env 文件并添加你的实际 API 密钥
# OPENROUTER_API_KEY=your-api-key-here

5. 测试服务器：

npm start

与 MCP 客户端集成

🚀 使用 NPX 快速设置（推荐）

使用 NPX 是将其与任何 MCP 客户端集成的最简单方法：

Claude Code

将此服务器添加到你的 Claude Code MCP 设置中：

1. 打开你的 MCP 设置文件（通常为 ~/.claude/mcp_settings.json）
2. 使用 NPX 添加服务器配置：

{
  "mcpServers": {
    "nexus": {
      "command": "npx",
      "args": ["nexus-mcp"],
      "env": {
        "OPENROUTER_API_KEY": "your-api-key-here"
      }
    }
  }
}

3. 重启 Claude Code

搞定！ 无需安装、无需构建步骤、无需配置路径。

Cursor

在 Cursor 的 MCP 设置中配置服务器：

1. 打开 Cursor 设置并导航到 MCP 服务器
2. 添加一个新服务器，设置如下：
   • 名称：nexus
   • 命令：npx
   • 参数：["nexus-mcp"]
   • 环境变量：
     • OPENROUTER_API_KEY：your-api-key-here
3. 重启 Cursor

其他 MCP 客户端

对于任何兼容 MCP 的客户端，使用以下连接详细信息：

• 传输方式：stdio
• 命令：npx
• 参数：["nexus-mcp"]
• 环境变量：OPENROUTER_API_KEY=your-api-key-here

替代方案：本地安装

如果你更喜欢使用本地安装（在完成本地开发设置后）：

{
  "mcpServers": {
    "nexus": {
      "command": "node",
      "args": ["/path/to/nexus-mcp/dist/cli.js"],
      "env": {
        "OPENROUTER_API_KEY": "your-api-key-here"
      }
    }
  }
}

✨ 主要特性

🚀 零安装的简便性

• 使用 npx 只需 30 秒即可准备就绪
• 无需依赖项或构建步骤
• 跨平台兼容
• 始终保持最新

🧠 人工智能驱动的智能

• 集成 Perplexity Sonar 模型
• 实时网络内容搜索
• 上下文感知的结果排名
• 多种模型选项

📚 专业品质

• 提供来源引用和元数据
• 全面的错误处理
• 生产级可靠性
• TypeScript 实现

🔧 开发者体验

• 符合 MCP 协议
• 丰富的文档
• 可配置的参数
• 社区支持

💻 使用示例

基础用法

使用搜索工具查找有关 "人工智能的最新发展" 的信息

高级用法

使用以下参数搜索 "气候变化解决方案"：
- 模型：perplexity/sonar
- 最大令牌数：2000
- 温度：0.3

📚 详细文档

可用工具

search

主要的搜索工具，提供人工智能驱动的网络搜索功能。 参数：

• query（必需）：搜索查询（1 - 2000 个字符）
• model（可选）：要使用的 Perplexity 模型（默认："perplexity/sonar"）
• maxTokens（可选）：最大响应令牌数（1 - 4000，默认：1000）
• temperature（可选）：响应随机性（0 - 2，默认：0.7）

示例响应：

根据当前信息，以下是人工智能的最新发展...

[详细的人工智能生成的包含当前信息的响应]

---
**搜索元数据**：
- 模型：perplexity/sonar
- 响应时间：1250ms
- 使用的令牌数：850
- 找到的来源：5 个

配置

环境变量

• OPENROUTER_API_KEY（必需）：你的 OpenRouter API 密钥
• NODE_ENV（可选）：环境设置（开发、生产、测试）
• LOG_LEVEL（可选）：日志记录级别（调试、信息、警告、错误）

高级配置

服务器支持通过环境变量进行额外配置：

• OPENROUTER_TIMEOUT_MS：请求超时时间（毫秒）（默认：30000）
• OPENROUTER_MAX_RETRIES：最大重试次数（默认：3）
• OPENROUTER_BASE_URL：自定义 OpenRouter API 基础 URL

资源

服务器在 config://status 提供一个配置状态资源，显示以下信息：

• 服务器健康状态
• 配置信息（API 密钥已掩码）
• 搜索工具可用性
• 服务器正常运行时间和版本

🔧 技术细节

故障排除

NPX 特定问题

• “npx: command not found”
  • 确保已安装 Node.js 16+：node --version
  • 更新 npm：npm install -g npm@latest
• “Cannot find package 'nexus-mcp'”
  • 该软件包可能尚未发布。请使用本地安装代替
  • 验证网络连接是否可以访问 npm 注册表
• NPX 启动时间过长
  • 首次运行时这是正常的，因为 NPX 会下载软件包
  • 后续运行由于缓存会更快
  • 若想更快启动，请使用本地安装代替
• 使用 NPX 时出现 “Permission denied” 错误
  • 尝试：npx --yes nexus-mcp --stdio
  • 或者设置 npm 权限：npm config set user 0 && npm config set unsafe-perm true

常见问题

• “Search functionality is not available”
  • 确保已设置 OPENROUTER_API_KEY 环境变量
  • 在 OpenRouter 验证你的 API 密钥是否有效
  • 检查服务器日志中是否有初始化错误
• “Authentication failed: Invalid API key”
  • 仔细检查你的 API 密钥格式和有效性
  • 确保该密钥有足够的信用额度/权限
  • 在 OpenRouter 仪表板中直接测试该密钥
• “Rate limit exceeded”
  • 等待速率限制重置（通常为 1 分钟）
  • 考虑升级你的 OpenRouter 计划以获得更高的限制
  • 在你的 OpenRouter 账户中监控使用情况
• 连接超时
  • 检查你的互联网连接
  • 服务器会自动重试失败的请求
  • 如有需要，增加超时时间：OPENROUTER_TIMEOUT_MS=60000
• MCP 客户端无法连接到服务器
  • 验证你的 MCP 配置使用了正确的命令和参数
  • 检查你的 MCP 客户端环境中是否有可用的 Node.js 16+
  • 确保 API 密钥已正确设置在环境变量中

调试日志

通过以下方式启用调试日志：

• 对于本地开发：在你的 .env 文件中添加 LOG_LEVEL=debug
• 对于 MCP 客户端：在你的 MCP 配置的 env 部分添加 LOG_LEVEL: "debug"

这将提供以下详细信息：

• 配置加载
• API 请求和响应
• 错误详细信息和堆栈跟踪
• 性能指标

测试连接

你可以通过检查 MCP 客户端中的配置状态资源，或运行一个简单的搜索查询来测试服务器是否正常工作。

开发

对于开发此服务器的开发者：

# 带热重载的开发
npm run dev

# 运行测试
npm test

# 运行带覆盖率的测试
npm run test:coverage

# 代码检查
npm run lint

# 代码格式化
npm run format

API 信用额度和成本

此服务器使用 OpenRouter 的 API，该 API 根据令牌使用情况收费：

• Perplexity Sonar 模型：在 OpenRouter 模型 查看当前定价
• 使用监控：通过 OpenRouter 仪表板跟踪消耗情况
• 成本控制：在你的 OpenRouter 账户中设置使用限制
• 优化：Nexus 包含内置的速率限制和智能缓存

🤝 贡献

我们欢迎各级经验的开发者做出贡献！

🚀 开始贡献

• 分叉仓库
• 阅读我们的 贡献指南
• 查看 适合新手的问题

🐛 报告问题

• 错误报告
• 功能请求
• 提问

💬 加入社区

• GitHub 讨论
• 行为准则
• 路线图和项目板

🌟 认可

贡献者将在以下方面得到认可：

• 贡献者列表
• 重大贡献的发布说明
• 社区亮点和推荐

🔗 相关项目

• 模型上下文协议 - 我们实现的标准
• OpenRouter - 我们的人工智能模型提供商
• Claude Desktop - 主要的 MCP 客户端
• Cursor - 支持 MCP 的人工智能代码编辑器

📞 支持与社区

📄 许可证

MIT 许可证 - 详情请参阅 LICENSE 文件。