🚀 NexusHub

---

✨ 功能

• 📡 双接口 - 同时支持 HTTP 和 stdio MCP 协议
• 💅 现代化仪表板 - 美观的 Protocol 设计系统管理界面，默认启用深色模式
• 🔌 集成服务 - 整合多个 MCP 服务（Memory、GitHub、Brave Search）
• 🔍 向量数据库 - 支持文档导入和语义搜索
• 🔑 API 管理 - 安全管理 API 密钥和服务配置
• 🐳 Docker 集成 - 使用 Docker 和 Docker Compose 轻松部署
• 📋 高级提示词 - 预配置提示词，助力高效 AI 交互
• 🔄 实时状态 - 监控所有已连接服务的运行状况

🏛️ 架构

NexusHub 使用 Node.js 后端，通过 Express 提供 HTTP 接口，并为命令行接口原生处理 stdio。该服务集成了多个关键服务：

┌─────────────────────────────────────────────────────┐
│                  Claude Desktop                     │
└───────────┬─────────────────┬───────────┬───────────┘
            │                 │           │
            ▼                 ▼           ▼           
┌───────────────────┐ ┌─────────────┐ ┌─────────────┐ 
│    NexusHub MCP   │ │ Memory MCP  │ │ GitHub MCP  │ 
│       Server      │ │   Server    │ │   Server    │ 
└─────────┬─────────┘ └─────────────┘ └─────────────┘ 
          │                  ▲                ▲        
          ▼                  │                │        
┌─────────────────┐          │                │        
│  Vector Store   │          │                │        
└─────────────────┘          │                │        
          │                  │                │        
          ▼                  │                │        
┌─────────────────┐ ┌─────────────┐ ┌─────────────────┐
│ Filesystem API  │ │ Database API│ │   Docker API    │
└─────────────────┘ └─────────────┘ └─────────────────┘

🛠️ 可用工具

NexusHub 为 Claude AI 提供以下工具：

类别	工具	描述
文件系统	fs_list_files	列出目录中的文件
	fs_read_file	读取文件内容
	fs_write_file	写入文件
数据库	db_execute_query	执行只读 SQL 查询
	db_list_tables	列出数据库中的所有表
	db_describe_table	获取表结构
	db_insert_data	向表中插入数据
Docker	docker_list_containers	列出 Docker 容器
	docker_start_container	启动容器
	docker_stop_container	停止容器
	docker_get_container_logs	获取容器日志
搜索	serper_search	通过 Serper API 执行网络搜索
向量数据库	ingest_docs	将文档导入向量存储
	vector_search	搜索相似文档

🚀 开始使用

前置条件

• Docker 和 Docker Compose
• Node.js 18+
• Python 3.8+（用于向量嵌入）

安装

1. 克隆仓库：

   git clone https://github.com/webdevtodayjason/NexusHub.git
   cd NexusHub
   

2. 设置环境变量：

   cp .env.example .env
   # Edit .env file with your API keys
   

3. 启动服务：

   docker-compose up -d
   

4. 访问仪表板： 在浏览器中打开 http://localhost:8001/dashboard

Claude Desktop 配置

NexusHub 支持两种不同的 Claude Desktop 集成方式：

1. HTTP 模式

此模式通过 HTTP 端点连接到 NexusHub。将以下内容添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "nexushub": {
      "name": "NexusHub MCP Server",
      "description": "Centralized MCP server with multiple capabilities",
      "url": "http://localhost:8001/mcp",
      "enabled": true
    }
  }
}

2. STDIO 模式（推荐）

此模式使用直接进程通信，性能和可靠性更佳。需要在本地提供 NexusHub 代码：

1. 准备包装脚本：

   # Make the wrapper script executable
   chmod +x /path/to/nexushub/nexushub-mcp.sh
   chmod +x /path/to/nexushub/src/mcp/adapters/stdio-wrapper.js
   chmod +x /path/to/nexushub/src/mcp/stdio-adapter.js
   

2. 添加到你的 claude_desktop_config.json：

   {
     "mcpServers": {
       "nexushub": {
         "name": "NexusHub MCP Server",
         "description": "Centralized MCP server with multiple capabilities",
         "command": "/path/to/nexushub/nexushub-mcp.sh",
         "enabled": true
       },
       "brave-search": {
         "name": "Brave Search MCP",
         "description": "Provides web search capabilities via Brave Search API.",
         "command": "docker",
         "args": ["exec", "-i", "mcp_brave_search", "node", "dist/index.js"],
         "enabled": true
       },
       "github": {
         "name": "GitHub MCP",
         "description": "Provides GitHub repository interaction.",
         "command": "docker",
         "args": ["exec", "-i", "mcp_github", "node", "dist/index.js"],
         "enabled": true
       },
       "memory": {
         "name": "Memory MCP",
         "description": "Persistent knowledge graph memory.",
         "command": "docker",
         "args": ["exec", "-i", "mcp_memory", "node", "dist/index.js"],
         "enabled": true
       }
     }
   }
   

注意： 将 /path/to/nexushub 替换为你的实际 NexusHub 安装路径。

Docker 容器

启动 Claude Desktop 前，请确保所有 Docker 容器都在运行：

cd /path/to/nexushub
docker-compose up -d

这将启动所有必需的 MCP 服务：

• NexusHub（主服务，提供文件系统、数据库和 Docker 工具）
• Brave Search MCP（网页搜索功能）
• GitHub MCP（仓库交互）
• Memory MCP（知识图谱／持久化记忆）

💡 使用示例

以下是将 NexusHub 与 Claude AI 搭配使用的一些示例：

文件操作

Please use fs_list_files to show me all the JavaScript files in the src directory, 
then read the content of any interesting files you find.

数据库查询

Can you use db_execute_query to find all users in the database who joined 
in the last month and have the "admin" role?

向量搜索

Please use vector_search to find documentation related to "authentication flow" 
and summarize the key points.

组合工具

First, use brave_web_search to find the latest best practices for React error boundaries. 
Then, use fs_read_file to examine our current implementation in ErrorBoundary.jsx, 
and suggest improvements based on what you found.

🧩 如何添加自己的工具

你可以在 /src/mcp/tools/ 目录中添加新的工具定义，以扩展 NexusHub：

// src/mcp/tools/my-custom-tools.js

export function getToolDefinitions() {
  return {
    my_custom_tool: {
      name: 'my_custom_tool',
      description: 'Description of what the tool does.',
      inputSchema: {
        type: 'object',
        properties: {
          param1: {
            type: 'string',
            description: 'Description of parameter 1'
          }
          // Add more parameters as needed
        },
        required: ['param1']
      }
    }
  };
}

// Tool implementation
export async function myCustomTool(param1) {
  // Your custom tool logic here
  return { result: 'Success!' };
}

然后将该工具添加到 /src/mcp/tools/index.js 和 /src/mcp/tools/handler.js。

🔄 本地开发

1. 安装依赖项：

   npm install
   

2. 在开发模式下运行：

   npm run dev
   

3. 测试 stdio 模式：

   npm run stdio
   

🧪 运行测试

# Run all tests
npm test

# Run specific test suite
npm test -- --grep "API Keys"

🔧 故障排除

Claude Desktop 集成问题

1. 启动 Claude Desktop 时出现“Unexpected token”错误：

   • 确保包装脚本具有正确的权限：chmod +x nexushub-mcp.sh
   • 确认所有脚本都能正确过滤非 JSON 输出
   • 查看 /tmp/nexushub-debug-*.log 中的日志文件，了解详情

2. MCP 服务未加载或工具未显示：

   • 确保 Docker 容器正在运行：docker ps | grep mcp
   • 检查容器日志：docker logs mcp_brave_search
   • 确认 Claude Desktop 配置中的路径／命令正确
   • 修改后尝试重启 Claude Desktop

3. Docker 容器问题：

   • 如果 Docker 日志过大，请清理：docker system prune
   • 重启容器：docker-compose restart
   • 检查端口冲突：lsof -i :8001

常见错误消息

错误	解决方案
"Method not found"	MCP 服务不支持此方法。检查你使用的工具名称是否正确。
"Socket hang up"	连接问题。检查 MCP 服务是否正在运行。
"ENOENT"	未找到文件或目录。检查配置中的路径。
"Permission denied"	文件权限问题。检查脚本权限。
"Unexpected token"	JSON 解析错误。检查 MCP 服务的标准输出。

📚 文档

工具开发指南

• 快速入门指南 - 5 分钟内完成设置并开始使用
• 工具开发指南 - 创建工具的完整指南
• AI 工具创建提示词 - 用于 AI 辅助创建工具的优化提示词

集成指南

• Claude Desktop 集成 - 将 NexusHub 连接到 Claude Desktop
• Claude CLI 集成 - 将 NexusHub 与 Claude CLI 搭配使用

MCP 资源

• Model Context Protocol 官方网站
• 面向 Claude Desktop 用户的 MCP 快速入门
• Claude Code 文档

如需完整文档，请访问 NexusHub Wiki。

🤝 贡献

贡献让开源社区成为一个令人惊叹的学习、启发和创造之地。我们非常感谢你做出的任何贡献。

1. Fork 此项目
2. 创建功能分支（git checkout -b feature/AmazingFeature）
3. 提交更改（git commit -m 'Add some AmazingFeature'）
4. 推送到分支（git push origin feature/AmazingFeature）
5. 发起 Pull Request

📝 许可证

本项目基于 MIT License 发布。更多信息请参阅 LICENSE。

👨‍💻 作者

Jason Brashear

🙏 致谢

• Claude AI - 感谢其出色的 AI 能力
• Model Context Protocol - 感谢其提供协议规范
• Protocol Design System - 感谢其提供现代化的 UI 设计语言
• Tailwind CSS - 感谢其提供实用优先的 CSS 框架

---