Nexus AI 工具

面向 AI 助手的全面模型上下文协议工具包

将任何 AI 助手转变为能够执行现实任务的自主智能体。

文档 • 入门指南 • 路线图 • 架构

🎯 概述

Nexus-MCP 是一个功能强大的 模型上下文协议 (MCP) 服务器，使用 TypeScript/Node.js 构建，为 AI 模型提供通用工具，用于：

• 📁 文件系统操作 (18 个工具) - 读取、写入、搜索和监控文件

• 🌐 HTTP/Web 请求 (16 个工具) - 获取数据、抓取网站、调用 API

• 🔄 Git 工作流 (15 个工具) - 克隆、提交、分支和管理仓库

• 系统命令 (8 个工具) - 执行 shell 命令和管理进程

• 🔧 实用工具 (8 个工具，代码就绪) - JSON/YAML 解析、压缩、加密等

当前状态：49 个工具已可用于生产环境，8 个实用工具已完成代码实现（等待配置集成）

🚀 快速开始

安装

npm install -g nexus-ai-tools

配置

# Copy example environment file
cp .env.example .env

# Edit with your settings
nano .env

运行

# Build the project
npm run build

# Run the MCP server (production)
npm start
# or
npm run start:mcp

# Run with CLI
npm run mcp

# Run in development mode
npm run dev

与 Claude Code 集成

添加到您的 Claude Desktop 配置中：

{
  "mcpServers": {
    "nexus-mcp": {
      "command": "node",
      "args": ["/path/to/nexus-mcp/dist/index.js"]
    }
  }
}

使用环境变量替换

创建一个 .env 文件：

NEXUS_LOG_LEVEL=debug
DB_PASSWORD=secret123
ANTHROPIC_API_KEY=sk-ant-...

在 config.yaml 中使用：

server:
  log_level: "${NEXUS_LOG_LEVEL:-info}"
database:
  postgresql:
    password: "${DB_PASSWORD}"
ai:
  anthropic:
    api_key: "${ANTHROPIC_API_KEY}"

启动前验证所需变量：

import { validateEnvironment, loadConfig } from './config.js';

validateEnvironment(['ANTHROPIC_API_KEY', 'DB_PASSWORD']);
const config = loadConfig();

使用上下文日志记录器

import { ContextualLogger } from './logger.js';
import path from 'path';

const workDir = path.join(process.cwd(), 'logs');
const logger = ContextualLogger.create(workDir, 'workflow-001');

logger.info('workflow.started', { step: 1 });
logger.info('processing.data', { items: 100 });
logger.info('workflow.completed', { success: true });

logger.close();

有关完整详细信息，请参阅 配置改进指南。

📦 功能

文件系统工具

• nexus_read_file - 支持编码的文件读取

• nexus_write_file - 写入/创建文件

• nexus_list_directory - 列出目录内容

• nexus_search_files - 按模式搜索文件

• nexus_search_content - 搜索文件内容

• nexus_watch_directory - 监控目录更改

HTTP 工具

• nexus_http_get - HTTP GET 请求

• nexus_http_post - HTTP POST 请求

• nexus_fetch_url - 获取并解析 Web 内容

• nexus_parse_html - 使用 Cheerio 解析 HTML

• nexus_call_api - 通用 API 调用

Git 工具

• nexus_git_clone - 克隆仓库

• nexus_git_commit - 创建提交

• nexus_git_push - 推送到远程

• nexus_git_pr_create - 创建拉取请求

• 与 GitHub、GitLab、Bitbucket 集成

数据库工具

• nexus_db_query - 执行 SQL 查询

• nexus_db_list_tables - 列出数据库表

• nexus_db_describe_table - 描述表结构

• 支持 PostgreSQL、MySQL、SQLite、SQL Server、MongoDB

系统工具

• nexus_exec_command - 执行 shell 命令

• nexus_system_info - 获取系统信息

• nexus_process_list - 列出运行中的进程

• nexus_service_start/stop - 管理服务

AI 工具

• nexus_llm_chat - 与 LLM 聊天 (Anthropic, OpenAI)

• nexus_embedding_create - 创建文本嵌入

• nexus_text_summarize - 文本摘要

• nexus_code_generate - 生成代码

实用工具

• nexus_json_parse/stringify - JSON 操作

• nexus_yaml_parse/stringify - YAML 操作

• nexus_zip_create/extract - ZIP 压缩

• nexus_encrypt/decrypt - 加密/解密

🏗️ 架构

┌─────────────────────────────────────────┐
│         Claude / LLM Client              │
└──────────────┬──────────────────────────┘
               │ MCP Protocol (stdio)
               ▼
┌─────────────────────────────────────────┐
│           Nexus-MCP Server               │
│  ┌───────────────────────────────────┐  │
│  │      MCP Server Core             │  │
│  └───────────────────────────────────┘  │
│         ┌───────┴───────┐                │
│         │               │                │
│    ┌────▼────┐    ┌────▼────┐           │
│    │ Filesys │    │   HTTP  │           │
│    └─────────┘    └─────────┘           │
│    ┌─────────┐    ┌─────────┐           │
│    │   Git   │    │ Database│           │
│    └─────────┘    └─────────┘           │
│    ┌─────────┐    ┌─────────┐           │
│    │  System │    │    AI   │           │
│    └─────────┘    └─────────┘           │
└─────────────────────────────────────────┘

有关详细架构，请参阅 docs/architecture.md

🏛️ 生产级质量

Nexus-MCP 在构建时充分考虑了 架构卓越性，专为生产环境使用和社区采用而设计。我们遵循严格的原则：

• ✅ 类型安全：TypeScript 严格模式 + Zod 验证

• ✅ 错误处理：结构化、可操作的错误消息

• ✅ 性能：异步操作、缓存、流式传输

• ✅ 安全性：输入验证、清理、审计日志

• ✅ 可观测性：结构化日志、指标、追踪

• ✅ 可测试性：80%+ 覆盖率，依赖注入

• ✅ 文档：JSDoc、示例、综合指南

• ✅ 开发者体验：清晰的错误提示、IDE 支持、快速反馈

有关完整详细信息，请参阅 架构原则。

⚙️ 配置与日志增强

Nexus-MCP 包含受生产系统启发的先进配置和日志记录功能：

环境变量替换

在 YAML 文件中使用 ${VAR_NAME} 语法来替换环境变量：

server:
  log_level: "${NEXUS_LOG_LEVEL:-info}"  # Uses env var, defaults to "info"
database:
  postgresql:
    password: "${DB_PASSWORD}"  # Required - warns if not set

优势：

• 将敏感数据（API 密钥、密码）保留在环境变量中

• 为不同环境使用不同的配置

• 无需编辑 YAML 文件即可覆盖特定值

上下文日志记录器

针对工作流的特定日志记录，每个上下文都有单独的日志文件：

import { ContextualLogger } from './logger.js';

const logger = ContextualLogger.create(workDir, 'migration-123');
logger.info('workflow.started', { step: 1 });
logger.info('extract.completed', { schemaPath: '/path/to/schema.json' });
logger.close();

优势：

• 追踪端到端工作流（迁移、任务、批处理作业）

• 调试复杂的多步骤操作

• 按工作流/关联 ID 组织日志

• 对特定工作流进行历史分析

文档： 有关完整详细信息，请参阅 配置改进指南。

📖 文档

• 入门指南 - 快速开始和基本用法

• 架构文档 - 系统架构和设计

• 架构原则 - 设计原则和最佳实践

• 配置改进 - 环境变量替换与上下文日志记录

• API 参考 - 完整的 API 文档

• 工具参考 - 详细的工具文档

• 路线图 - 开发路线图和进度

🛠️ 开发

# Clone repository
git clone https://github.com/your-org/Nexus-MCP.git
cd Nexus-MCP

# Install dependencies
npm install

# Run in development mode
npm run dev

# Run tests
npm test

# Build for production
npm run build

# Lint code
npm run lint

📊 项目状态

• 当前版本：1.0.0-alpha

• 开发状态：活跃开发中

• 核心进度：36% (9/12 个阶段已完成)

• 已实现工具：57 个生产就绪，8 个代码实现（等待配置）

• 目标工具：50+ ✅ (已超出)

• AI 集成：Ollama + Gemini + OpenAI + Anthropic Claude ✅ (8 个工具)

• 增强型 CLI：带有颜色和指标的交互式 AI 工具 CLI ✅

• 测试覆盖率：已实现 49 个测试 (35 个单元 + 1 个集成 + 13 个 E2E)

• 测试状态：✅ 全部通过 (49/49)

• 文档：85% 完成（安装、配置、API、示例、AI 指南）

• 构建状态：✅ 通过

• 可执行文件：✅ 已准备好部署

• CLI：✅ 功能正常

有关详细进度，请参阅 ROADMAP.md。

🤖 AI 工具集成

Nexus-MCP 包含与 4 大 AI 提供商的集成：

• Ollama (2 个工具)：本地 LLM - 聊天 + 列出模型

• Gemini (2 个工具)：Google AI - 聊天 + 列出模型

• OpenAI (2 个工具)：GPT 模型 - 聊天 + 列出模型

• Anthropic (2 个工具)：Claude 模型 - 聊天 + 列出模型

AI 工具快速开始

# Configure API keys
export OPENAI_API_KEY="your-key"
export GEMINI_API_KEY="your-key"
export ANTHROPIC_API_KEY="your-key"
export OLLAMA_HOST="http://localhost:11434"

# Run the interactive AI CLI
node examples/ai-interactive-cli.js

# Or run the enhanced demo
node examples/ai-enhanced-demo.js

有关详细文档，请参阅 AI 工具指南。

🔌 MCP 集成

Nexus-MCP 是一个 MCP（模型上下文协议）服务器，允许像 Claude Code 这样的 AI 助手使用其 57 个工具。

MCP 快速开始

1. 启动服务器：

npm start

2. 配置 Claude Desktop 以连接到 Nexus-MCP

有关详细设置说明，请参阅 MCP 配置指南。

可用工具类别

• 文件系统 (18 个工具)：读取、写入、列出、搜索文件

• HTTP (16 个工具)：请求、抓取、API

• Git (15 个工具)：克隆、提交、分支、PR

• 系统 (8 个工具)：命令、进程、系统信息

• AI (8 个工具)：与 Ollama、Gemini、OpenAI、Anthropic 聊天

• 实用工具 (8 个工具)：JSON、YAML、压缩、加密

🤝 贡献

欢迎贡献！在提交 PR 之前，请阅读我们的贡献指南。

1. Fork 本仓库

2. 创建您的功能分支 (git checkout -b feature/amazing-feature)

3. 提交您的更改 (git commit -m 'Add amazing feature')

4. 推送到分支 (git push origin feature/amazing-feature)

5. 打开 Pull Request

📄 许可证

本项目采用 MIT 许可证 - 有关详细信息，请参阅 LICENSE 文件。

🙏 致谢

• 模型上下文协议

• Anthropic Claude

• MCP SDK TypeScript

• App Migración SOUL - 配置模式和上下文日志记录灵感

📞 支持

• 📖 文档

• 🐛 问题追踪

• 💬 Discord 社区

• ✉️ 电子邮件：support@nexus-mcp.dev

由 Nexus 团队用心构建 ❤️