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

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

License: MIT Node Version TypeScript 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

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

npm start

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

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

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

Файловая система (18 инструментов): Чтение, запись, список, поиск файлов
HTTP (16 инструментов): Запросы, парсинг, API
Git (15 инструментов): Клонирование, коммиты, ветки, PR
Система (8 инструментов): Команды, процессы, системная информация
ИИ (8 инструментов): Чат с Ollama, Gemini, OpenAI, Anthropic
Утилиты (8 инструментов): JSON, YAML, сжатие, шифрование

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

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

Сделайте форк репозитория
Создайте ветку для вашей функции (git checkout -b feature/amazing-feature)
Закоммитьте изменения (git commit -m 'Add amazing feature')
Отправьте изменения в ветку (git push origin feature/amazing-feature)
Откройте Pull Request

📄 Лицензия

Этот проект лицензирован по лицензии MIT — подробности см. в файле LICENSE.

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

Model Context Protocol
Anthropic Claude
MCP SDK TypeScript
App Migración SOUL — вдохновение для шаблонов конфигурации и контекстного логирования

📞 Поддержка

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

Nexus-MCP