Nexus AI 工具

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

License: MIT Node Version TypeScript MCP

将任何 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 快速开始

启动服务器：

npm start

配置 Claude Desktop 以连接到 Nexus-MCP

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

可用工具类别

文件系统 (18 个工具)：读取、写入、列出、搜索文件
HTTP (16 个工具)：请求、抓取、API
Git (15 个工具)：克隆、提交、分支、PR
系统 (8 个工具)：命令、进程、系统信息
AI (8 个工具)：与 Ollama、Gemini、OpenAI、Anthropic 聊天
实用工具 (8 个工具)：JSON、YAML、压缩、加密

🤝 贡献

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

Fork 本仓库
创建您的功能分支 (git checkout -b feature/amazing-feature)
提交您的更改 (git commit -m 'Add amazing feature')
推送到分支 (git push origin feature/amazing-feature)
打开 Pull Request

📄 许可证

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

🙏 致谢

模型上下文协议
Anthropic Claude
MCP SDK TypeScript
App Migración SOUL - 配置模式和上下文日志记录灵感

📞 支持

📖 文档
🐛 问题追踪
💬 Discord 社区
✉️ 电子邮件：support@nexus-mcp.dev

由 Nexus 团队用心构建 ❤️

Nexus-MCP