JinDaGe - nexus MCP Details

article

README

🚀 🔍 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

替代方案：本地开发安装

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

克隆仓库：

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

安装依赖项：

npm install

构建服务器：

npm run build

配置你的 OpenRouter API 密钥：

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

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

测试服务器：

npm start

与 MCP 客户端集成

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

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

Claude Code

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

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

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

重启 Claude Code

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

Cursor

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

打开 Cursor 设置并导航到 MCP 服务器
添加一个新服务器，设置如下：
- 名称：nexus
- 命令：npx
- 参数：["nexus-mcp"]
- 环境变量：
  - OPENROUTER_API_KEY：your-api-key-here
重启 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 包含内置的速率限制和智能缓存

🤝 贡献

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

🚀 开始贡献

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

🐛 报告问题

💬 加入社区

🌟 认可

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

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

🔗 相关项目

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

📞 支持与社区

| 💬 需要帮助？ | 🔗 资源 | | ---- | ---- | | 快速提问 | GitHub 讨论 | | 错误报告 | GitHub 问题 | | 文档 | OpenRouter 文档 • MCP 规范 | | 功能请求 | 增强提案 |

📄 许可证

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