Инструменты Nexus AI

Комплексный инструментарий протокола контекста модели (MCP) для ИИ-ассистентов

Превратите любого ИИ-ассистента в автономного агента, способного выполнять реальные задачи.

Документация • Начало работы • Дорожная карта • Архитектура

🎯 Обзор

Nexus-MCP — это мощный сервер протокола контекста модели (MCP), созданный на TypeScript/Node.js, который предоставляет ИИ-моделям универсальные инструменты для:

• 📁 Операций с файловой системой (18 инструментов) — чтение, запись, поиск и мониторинг файлов

• 🌐 HTTP/веб-запросов (16 инструментов) — получение данных, парсинг веб-сайтов, вызов API

• 🔄 Рабочих процессов Git (15 инструментов) — клонирование, коммиты, ветки и управление репозиториями

• Системных команд (8 инструментов) — выполнение команд оболочки и управление процессами

• 🔧 Утилит (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 — получение и парсинг веб-контента

• nexus_parse_html — парсинг HTML с помощью Cheerio

• nexus_call_api — общие вызовы API

Инструменты Git

• nexus_git_clone — клонирование репозиториев

• nexus_git_commit — создание коммитов

• nexus_git_push — отправка в удаленный репозиторий

• nexus_git_pr_create — создание pull-реквестов

• Интеграция с GitHub, GitLab, Bitbucket

Инструменты баз данных

• nexus_db_query — выполнение SQL-запросов

• nexus_db_list_tables — список таблиц базы данных

• nexus_db_describe_table — описание схемы таблицы

• Поддержка PostgreSQL, MySQL, SQLite, SQL Server, MongoDB

Системные инструменты

• nexus_exec_command — выполнение команд оболочки

• nexus_system_info — получение системной информации

• nexus_process_list — список запущенных процессов

• nexus_service_start/stop — управление службами

Инструменты ИИ

• 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 включает расширенные функции конфигурации и логирования, вдохновленные промышленными системами:

Подстановка переменных окружения

Используйте синтаксис ${VAR_NAME} в YAML-файлах для подстановки переменных окружения:

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();

Преимущества:

• Отслеживание сквозных рабочих процессов (миграции, задачи, пакетные задания)

• Отладка сложных многошаговых операций

• Организация логов по рабочему процессу/идентификатору корреляции

• Исторический анализ конкретных рабочих процессов

Документация: Полную информацию см. в Руководстве по улучшению конфигурации.

📚 Документация

• Руководство по началу работы — быстрый старт и базовое использование

• Документация по архитектуре — системная архитектура и дизайн

• Архитектурные принципы — принципы проектирования и лучшие практики

• Улучшения конфигурации — подстановка переменных окружения и контекстное логирование

• Справочник 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+ ✅ (превышено)

• Интеграция с ИИ: Ollama + Gemini + OpenAI + Anthropic Claude ✅ (8 инструментов)

• Улучшенный CLI: Интерактивный CLI для ИИ-инструментов с цветами и метриками ✅

• Покрытие тестами: реализовано 49 тестов (35 модульных + 1 интеграционный + 13 E2E)

• Статус тестов: ✅ Все пройдены (49/49)

• Документация: завершена на 85% (Установка, Конфигурация, API, Примеры, Руководство по ИИ)

• Статус сборки: ✅ Пройдена

• Исполняемый файл: ✅ Готов к развертыванию

• CLI: ✅ Функционален

Подробный прогресс см. в ROADMAP.md.

🤖 Интеграция инструментов ИИ

Nexus-MCP включает интеграцию с 4 основными ИИ-провайдерами:

• Ollama (2 инструмента): Локальные LLM — Чат + Список моделей

• Gemini (2 инструмента): Google AI — Чат + Список моделей

• OpenAI (2 инструмента): Модели GPT — Чат + Список моделей

• Anthropic (2 инструмента): Модели Claude — Чат + Список моделей

Быстрый старт с инструментами ИИ

# 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

Подробную документацию см. в Руководстве по инструментам ИИ.

🔌 Интеграция MCP

Nexus-MCP — это сервер MCP (Model Context Protocol), который позволяет ИИ-ассистентам, таким как Claude Code, использовать его 57 инструментов.

Быстрый старт с MCP

1. Запустите сервер:

npm start

2. Настройте Claude Desktop для подключения к Nexus-MCP

Подробные инструкции по настройке см. в Руководстве по конфигурации MCP.

Доступные категории инструментов

• Файловая система (18 инструментов): Чтение, запись, список, поиск файлов

• HTTP (16 инструментов): Запросы, парсинг, API

• Git (15 инструментов): Клонирование, коммиты, ветки, PR

• Система (8 инструментов): Команды, процессы, системная информация

• ИИ (8 инструментов): Чат с Ollama, Gemini, OpenAI, Anthropic

• Утилиты (8 инструментов): JSON, YAML, сжатие, шифрование

🤝 Участие в разработке

Мы приветствуем вклад в проект! Пожалуйста, ознакомьтесь с нашими правилами участия перед отправкой PR.

1. Сделайте форк репозитория

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.

🙏 Благодарности

• Model Context Protocol

• Anthropic Claude

• MCP SDK TypeScript

• App Migración SOUL — вдохновение для шаблонов конфигурации и контекстного логирования

📞 Поддержка

• 📖 Документация

• 🐛 Трекер проблем

• 💬 Discord-сообщество

• ✉️ Email: support@nexus-mcp.dev

Создано с ❤️ командой Nexus