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 文件。