faxenoff/ultrascript-tools-mcp

        ██  ██
        ██  ██  ██    ██████ █████▄  ▄████▄
        ██  ██  ██      ██   ██▄▄██▄ ██▄▄██
        ██  ██  ██      ██   ██   ██ ██  ██
        ██  ██  ██████  ██   ██   ██ ██  ██
        ▀████▀            ▄▄▄▄  ▄▄▄▄ ▄▄▄▄  ▄▄ ▄▄▄▄ ▄▄▄▄▄▄
                         ███▄▄ ██▀▀▀ ██▄█▄ ██ ██▄█▀  ██
                         ▄▄██▀ ▀████ ██ ██ ██ ██     ██

     ╔═════════════════════════════════════════════════════╗
     ║            ULTRASCRIPT TOOLS MCP SERVER             ║
     ╚═════════════════════════════════════════════════════╝

Мультиагентный MCP-сервер для анализа кода с продвинутым графовым пониманием

Мощный инструмент анализа кода, который понимает структуру вашей кодовой базы, находит дубликаты, анализирует влияние изменений и предоставляет интеллектуальные предложения по рефакторингу через Model Context Protocol (MCP).

Возможности

• 🔍 Семантический поиск по коду - Поиск кода по смыслу, а не только по ключевым словам
• 🔄 Обнаружение дубликатов - Автоматический поиск похожих блоков кода
• 📊 Анализ влияния - Узнайте, что сломается при изменении кода
• 🎯 Умный рефакторинг - Получайте AI-предложения по рефакторингу
• 🌳 Поддержка Git-веток - Анализ кода в разных ветках
• ⚡ SIMD/CUDA ускорение - Быстрая обработка с аппаратным ускорением
• 🌍 10 языков - TypeScript, JavaScript, Python, Go, Rust, Java, C++, Swift, Kotlin, Bash

Для проектов с C# - используйте аналогичный ultrasharp-tools-mcp

1. Установка

Проект оптимизирован под Bun (это альтернативный JavaScript-runtime). Под npm проект тоже работает, но 4-10 раз медленней (нет смысла его так использовать).

Установка Bun (одной командой):

# Windows (PowerShell)
powershell -c "irm bun.sh/install.ps1 | iex"

# macOS / Linux
curl -fsSL https://bun.sh/install | bash

Установка Ultrascript-tools

# Bun (рекомендуется) — два шага:

# 1. Установка пакета
bun install -g ultrascript-tools-mcp

# 2. Разрешить и выполнить postinstall скрипты (компиляция нативных модулей)
bun pm -g trust ultrascript-tools-mcp openvino-node webgpu

# npm (альтернатива) — один шаг:
npm install -g ultrascript-tools-mcp

Почему два шага для Bun? Bun блокирует postinstall скрипты для безопасности. Команда bun pm trust разрешает выполнение скриптов и сразу их запускает — повторная установка не нужна.

Примечание: Для полноценного анализа кода на разных языках требуются соответствующие runtime:

• TypeScript/JavaScript — встроено (TypeScript Compiler API)
• Python — требуется Python 3.8+ (python --version)
• Java/Kotlin — требуется JRE 11+ (java --version)
• Go — требуется Go 1.18+ (go version)
• Rust — требуется Rust toolchain (rustc --version)
• C/C++ — требуется Clang 12+ (clang --version)

Конфиг Claude Code (~/.claude.json):

{
  "mcpServers": {
    "ultrascript-tools": {
      "command": "ultrascript"
    }
  }
}

Способы подключения к Claude Code

Способ 1 — Cosmopolitan Proxy (рекомендуется):

{
  "mcpServers": {
    "ultrascript-tools": {
      "type": "stdio",
      "command": "path\\to\\ultrascript-tools.cmd",
      "args": ["."]
    }
  }
}

Способ 3 — Ultra-режим (максимальная производительность):

# Запуск Claude Code через Bun
bun "$env:USERPROFILE\.bun\install\global\node_modules\@anthropic-ai\claude-code\cli.js" --continue --permission-mode bypassPermissions

Подробная документация:

Настройка семантических эмбеддингов (локальная LLM) Для небольших интеллектуальных задач по анализу/модификации кода используется небольшая локальная модель, запускаемся через ollama/TEI. Это снимает затраты токенов и времени с вашего основного ИИ-агента. Особенно важно для анализа сотен и тысяч изменений в коде.

После установки проекта - запустите

# Интерактивный мастер настройки
bunx ultrascript-tools-mcp setup

Мастер настройки:

• Автоматически определит вашу GPU (NVIDIA Turing/Ampere/Ada/Hopper/Blackwood*)
• Поможет выбрать лучшую модель эмбеддингов
• Автоматически установит TEI (Docker) или Ollama
• Сохранит конфигурацию в системную директорию

*Для Blackwood (GTX 50xxx) используется неофициальный форк TEI

2. MCP Prompts (встроенная документация)

Сервер предоставляет MCP Prompts — встроенную документацию, доступную прямо из Claude:

Совет: В системные промпты можно добавить который поможет ИИ-агенту узнать о способе получения информации о работе Ultrascript-tools.

Доступные инструменты

MCP-сервер предоставляет 55+ инструментов для анализа и модификации кода:

Индексация и поиск

Анализ сущностей

Качество кода

Модификация кода

Снапшоты и откат

Git-интеграция

Граф и система

Статический анализ потока

Метрики и отладка

Конфигурация

Настройка через переменные окружения или конфиг-файл config/default.yaml.

Базовая конфигурация

# Минимальный конфиг - работает из коробки
mcp:
  embedding:
    provider: "memory"  # Без ML
    enabled: true

Опционально: ML-семантический поиск

Для улучшенного семантического поиска запустите мастер настройки:

# Интерактивная настройка
bunx ultrascript-tools-mcp setup

Сравнение провайдеров эмбеддингов

Auto-detection (рекомендуется)

По умолчанию используется provider: "auto" — система автоматически определяет доступный провайдер в порядке приоритета:

1. OVMS Native (порт 8083) — локальный OpenVINO
2. vLLM (порт 8000) — Docker контейнер
3. TEI (порт 8081) — Docker контейнер
4. Ollama (порт 11434) — локальный сервер

OVMS Native — для CPU/NPU

• Автоустановка через bunx ultrascript-tools-mcp setup
• Поддержка V3 OpenAI-compatible API (/v3/embeddings)
• Автоматическое управление жизненным циклом процесса
• Определение устройства: NPU → NVIDIA GPU → Intel GPU → CPU

vLLM — для NVIDIA GPU (Production)

• Максимальная производительность для NVIDIA GPU
• Поддержка больших batch размеров
• Docker: ghcr.io/vllm-project/vllm-openai

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

# Интерактивный мастер настройки (рекомендуется)
bunx ultrascript-tools-mcp setup

# Или с конкретным провайдером
bunx ultrascript-tools-mcp setup --provider tei     # NVIDIA GPU
bunx ultrascript-tools-mcp setup --provider ollama  # Универсальный
bunx ultrascript-tools-mcp setup --provider ovms-native  # CPU/NPU

Расположение конфигурации

• Windows: %LOCALAPPDATA%\UltraScriptTools\config\semantic-config.json
• macOS: ~/Library/Application Support/UltraScriptTools/config/semantic-config.json
• Linux: ~/.local/share/UltraScriptTools/config/semantic-config.json

Производительность

• В 5 раз быстрее встроенных инструментов Claude для больших кодовых баз
• Streaming Mode — парсинг и индексация происходят параллельно:
  • 37% быстрее (16.8s → 10.5s для 150+ файлов)
  • 91.6% файлов индексируется сразу через IPC streaming
• Parallel Data Files — JSON/YAML обрабатываются параллельно:
  • 34x быстрее (6.7s → 195ms для 174 файлов)
  • 892 файла/сек вместо 26 файлов/сек
• WASM SIMD — встроен в npm-пакет, работает везде (ускорение ещё в 2-4 раза)
• CUDA Worker — отдельный процесс для GPU-операций (ускорение 10-50x для больших проектов)
  • Изолированный Node.js subprocess для стабильности (не влияет на основной Bun процесс)
  • FAISS + CUDA для быстрого векторного поиска
  • Автоматический fallback на CPU при отсутствии GPU
• WebGPU/Dawn — кросс-платформенное ускорение (Windows/Linux, включён в npm-пакет)

Архитектура хранения (v2.5)

• libSQL/SQLite — единая база данных для графа и векторов
• Внешняя индексация — поддержка удалённых libSQL серверов для масштабирования
• Инкрементальная индексация — обновление только изменённых файлов

FAISS HNSW (быстрый векторный поиск)

FAISS обеспечивает 10-100x ускорение векторного поиска для больших индексов (10k+ векторов).

Зависимости (автоматически устанавливаются):

• faiss-node — Node.js bindings для FAISS
• OpenBLAS/LAPACK — матричные операции (DLLs включены для Windows)

Если FAISS не работает:

# Переустановить с копированием DLL
node scripts/postinstall.js

# Или проверить наличие DLL в:
# node_modules/faiss-node/lib/binding/node-v137-win32-x64/

Без FAISS система автоматически использует LibSQL DiskANN (медленнее, но работает везде).

2. Начало работы

Откройте Claude Desktop и спросите:

• "Проиндексируй мой проект в /path/to/my-project"
• "Найди все функции связанные с аутентификацией"
• "Покажи дублирующийся код в этом проекте"
• "Что сломается если изменить класс UserManager?"

Поиск похожего кода

Вы: "Найди дублирующийся код в моём проекте"

Ответ:
✓ Найдено 12 групп дубликатов
  - auth/login.ts и auth/verify.ts (схожесть: 89%)
  - utils/format.ts и helpers/formatter.ts (схожесть: 85%)

Анализ влияния

Вы: "Что сломается если изменить UserManager.login()?"

Ответ:
✓ Анализ влияния:
  - 15 файлов зависят от этого метода
  - Найдено 23 места вызова
  - Высокий риск: AuthController, SessionService

Семантический поиск

Вы: "Найди код который валидирует email адреса"

Ответ:
✓ Найдено 4 совпадения:
  - validators/email.ts: validateEmail()
  - utils/auth.ts: checkEmailFormat()
  - services/user.ts: verifyUserEmail()

Расширенный семантический поиск (NEW)

Вы: "Найди сложный код с цикломатической сложностью больше 10"

semantic_search query="data processing" minCyclomatic=10

Ответ:
✓ Найдено 3 совпадения:
  - parsers/complex-handler.ts: processData()
    complexity: cyclomatic=15, cognitive=22
    controlFlow: 8 branches, 3 loops, 2 exceptions
    calls: 12 функций

Вы: "Найди async код без обработки ошибок"

semantic_search query="API calls" hasAwaits=true hasExceptions=false

Ответ:
✓ Найдено 5 потенциальных проблем:
  - api/users.ts: fetchUsers() - await без try-catch
  - api/orders.ts: getOrders() - await без try-catch

Вы: "Найди недокументированный публичный API"

semantic_search query="export function" hasDocumentation=false

Ответ:
✓ Найдено 12 функций без документации:
  - utils/format.ts: formatDate()
  - helpers/validation.ts: validateInput()

Проблемы с установкой

Bun: заблокированы postinstall скрипты

Если при установке видите Blocked N postinstalls:

# Посмотреть заблокированные скрипты
bun pm -g untrusted

# Разрешить нужные пакеты
bun pm -g trust ultrascript-tools-mcp openvino-node webgpu

# Или разрешить все сразу
bun pm -g trust --all

# Переустановить
bun install -g ultrascript-tools-mcp

Очистка кеша и переустановка

# Bun
bun pm cache rm
bun install -g ultrascript-tools-mcp

# npm
npm cache clean --force
npm install -g ultrascript-tools-mcp

Настройка эмбеддингов

Если настройка эмбеддингов не удалась или хотите переконфигурировать:

# Запустите мастер настройки
bunx ultrascript-tools-mcp setup

Продвинутые возможности

GPU ускорение

macOS (Apple Silicon):

# При установке предлагается собрать Metal backend
# Требования для сборки:
#   - Xcode Command Line Tools: xcode-select --install
#   - Homebrew: https://brew.sh
#   - CMake: brew install cmake

# Можно собрать позже:
./node_modules/ultrascript-tools-mcp/scripts/build-native-libs-macos.sh

CLI команды

# Настройка семантических эмбеддингов (интерактивный мастер)
bunx ultrascript-tools-mcp setup

# Настройка с конкретным провайдером
bunx ultrascript-tools-mcp setup --provider tei         # NVIDIA GPU
bunx ultrascript-tools-mcp setup --provider ollama      # Универсальный
bunx ultrascript-tools-mcp setup --provider ovms-native # CPU/NPU
bunx ultrascript-tools-mcp setup --provider vllm        # NVIDIA GPU (Production)

Примечание: Индексирование проекта выполняется автоматически при открытии через MCP-клиент (Claude Desktop и др.). Git-интеграция следит за изменениями веток и файлов.

Переменные окружения

# Уровень логирования (debug, info, warn, error)
LOG_LEVEL=info

# Провайдер эмбеддингов (auto, tei, ollama, ovms-native, vllm, openai, cloudru, huggingface)
MCP_EMBEDDING_PROVIDER=auto

# Модель эмбеддингов
MCP_EMBEDDING_MODEL=all-MiniLM-L6-v2

# API ключ (для cloud провайдеров: openai, huggingface, cloudru)
MCP_EMBEDDING_API_KEY=

# Включить/отключить эмбеддинги
MCP_EMBEDDING_ENABLED=true

# Размер батча для индексации
MCP_DEV_INDEX_BATCH=100

# Таймаут агента (мс)
MCP_AGENT_TIMEOUT=90000

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

Этот пакет с открытым исходным кодом под лицензией MIT.

Репозиторий: https://github.com/faxenoff/ultrascript-tools-mcp

Лицензия

MIT © faxenoff