just-mcp

👋 Способ позволить LLM говорить на языке Just

Готовый к промышленному использованию MCP-сервер, обеспечивающий бесшовную интеграцию с Just — исполнителем команд, позволяющий ИИ-ассистентам обнаруживать, выполнять и интроспектировать рецепты Justfile через стандартизированный протокол MCP.

🎯 Почему Just + MCP = Лучшее выполнение агентов

Абстракция с сохранением контекста

Если это не очевидно сразу, преимущество использования LLM с Just вместо bash заключается в том, что выполнение команд Just (через MCP) предоставляет абстракцию с сохранением контекста, где им не нужно тратить контекст на открытие/чтение bash-файлов, Python-скриптов или других артефактов сборки. LLM через MCP просто получает команду, параметры и подсказки — это остаётся в их памяти как "эти команды доступны вам".

Устраняет кривую обучения Justfile

Больше не нужно наблюдать, как LLM выполняют just -l для получения списка команд, неизбежно начинают читать justfile, пытаются писать синтаксис justfile (как будто это Makefile), портят justfile и создают плохой опыт. Развивающийся синтаксис Just просто не имеет достаточного корпуса в современных передовых моделях — нам нужно больше популярных репозиториев с justfile в обучающем наборе данных.

Безопаснее, чем прямой доступ к bash

Just-mcp принципиально безопаснее bash. Если вы читаете HackerNews, то там почти каждый день появляется история о том, как операторы, чьи LLM начинают забывать, галлюцинировать и в итоге ломаться — удаляют файлы и совершают другие нежелательные действия. Предоставление LLM неконтролируемого, неограниченного доступа к bash без тщательного мониторинга потребления контекста — это путь к катастрофе.

Использование Justfile решает эту проблему. Даже если LLM изменит свой собственный justfile, следующий контекст запоминается justfile (желательно в идемпотентном git-репозитории). Эта абстракция защищает LLM от сложности командной строки, где галлюцинации или потеря внимания к текущему рабочему каталогу могут привести к выходу за пределы допустимого.

Мощный инструмент выполнения агентов

Just-mcp идеально подходит для всех, кто занимается выполнением агентов: - Сверхнизкие накладные расходы — вероятно, лучше, чем у любого другого инструмента - Удобство для человека — justfile просты для людей и имеют низкие накладные расходы для LLM - Быстро и просто — в то время как некоторые предпочитают полноценные Python FastAPI-серверы, just-mcp просто лёгок в использовании - Дружелюбен к sm0l-моделям — отлично работает с самодостаточными GPU/CPU моделями с открытым исходным кодом с ограничениями контекста 8k-32k

Встроенные шаблоны безопасности

Just имеет полезные шаблоны для внедрения: - Прозрачное логирование без отвлечения агента - Инспекция вторичной моделью — использование sm0l-моделей для сканирования команд с вопросом "это вредоносно?" перед выполнением - Шаблоны, подобные Python-декораторам, для валидации команд - Идемпотентное выполнение, поддерживаемое git-репозиториями

b00t

b00t mcp create just-mcp -- bash just-mcp --stdio "${REPO_ROOT}"
b00t mcp export just-mcp

🚀 Текущий статус: 67% завершено (8/12 основных задач)

✅ Реализованные функции

• 🏗️ Полноценный MCP-сервер — Полная интеграция rmcp 0.3.0 с протоколом MCP 2024-11-05
• 📋 Обнаружение рецептов — Парсинг и список всех доступных рецептов Justfile
• ⚡ Выполнение рецептов — Выполнение рецептов с параметрами и захват структурированного вывода
• 🔍 Интроспекция рецептов — Получение детальной информации о рецепте, параметрах и документации
• ✅ Валидация Justfile — Синтаксическая и семантическая валидация с отчётом об ошибках
• 🌍 Управление окружением — Полноценная поддержка .env-файлов и расширение переменных
• 🧪 Полное покрытие тестами — 33 успешных теста в интеграционных и юнит-тестах

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

1. list_recipes — Список всех доступных рецептов в justfile
2. run_recipe — Выполнение конкретного рецепта с необязательными аргументами
3. get_recipe_info — Получение детальной информации о конкретном рецепте
4. validate_justfile — Валидация justfile на наличие синтаксических и семантических ошибок

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

Установка

Выберите предпочтительный способ установки:

npm (JavaScript/TypeScript)

# Install globally
npm install -g just-mcp

# Or use with npx (no installation required)
npx just-mcp --stdio

pip (Python)

# Install with pip
pip install just-mcp

# Or use with uvx (recommended)
uvx just-mcp --stdio

Cargo (Rust)

# Install from crates.io
cargo install just-mcp

# Or build from source
git clone https://github.com/promptexecution/just-mcp
cd just-mcp
cargo build --release

pkgx (pkgxdev)

pkgx just-mcp --stdio

pkgx загружает специфичный для платформы архив, который предоставляют релизы GitHub (just-mcp-*-*.tar.gz), извлекает исполняемый файл в ${PKGX_DIR:-$HOME/.pkgx}/bin и запускает CLI с переданными вами аргументами. Добавьте этот каталог bin в переменную PATH вашей оболочки, если вам нужно долгосрочное использование just-mcp. Манифест пакетирования находится в pkgx/projects/github.com/promptexecution/just-mcp/package.yml и дублирует запись в pkgxdev/pantry.

Использование Docker

# Pull the latest image from GitHub Container Registry
docker pull ghcr.io/promptexecution/just-mcp:latest

# Run with Docker
docker run --rm -v $(pwd):/workspace ghcr.io/promptexecution/just-mcp:latest --stdio

# Build locally
docker build -t just-mcp:local .
docker run --rm -v $(pwd):/workspace just-mcp:local --stdio

Доступные теги Docker-образов: - latest — Последний стабильный релиз - X.Y.Z — Конкретная версия (например, 0.1.0) - X.Y — Последняя патч-версия (например, 0.1) - X — Последняя минорная версия (например, 0)

Интеграция с Claude Desktop

Использование npm/npx

Добавьте в конфигурацию MCP вашего Claude Desktop:

Использование бинарного файла

{
  "mcpServers": {
    "just-mcp": {
      "command": "npx",
      "args": ["-y", "just-mcp", "--stdio"]
    }
  }
}

Использование pip/uvx

{
  "mcpServers": {
    "just-mcp": {
      "command": "uvx",
      "args": ["just-mcp", "--stdio"]
    }
  }
}

Использование cargo или ручной установки

{
  "mcpServers": {
    "just-mcp": {
      "command": "/path/to/just-mcp",
      "args": ["--stdio"]
    }
  }
}

Использование Docker

{
  "mcpServers": {
    "just-mcp": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-v",
        "${workspaceFolder}:/workspace",
        "ghcr.io/promptexecution/just-mcp:latest",
        "--stdio"
      ]
    }
  }
}

Примеры использования

# Run as MCP server
just-mcp --stdio

# Run in specific directory  
just-mcp --directory /path/to/project --stdio

# Using Docker
docker run --rm -v $(pwd):/workspace ghcr.io/promptexecution/just-mcp:latest --stdio

🧪 Тестирование

Комплексный набор тестов

# Run all tests (33 tests)
cargo test

# Run specific test suites
cargo test --test basic_mcp_test      # Protocol compliance testing
cargo test --test mcp_integration_working  # SDK integration testing

Архитектура тестов

• basic_mcp_test.rs — Прямое тестирование соответствия протоколу с использованием необработанного JSON-RPC
• mcp_integration_working.rs — Интеграционное тестирование SDK с типобезопасным клиентом rmcp
• Модульные тесты — Более 25 тестов, покрывающих парсер, исполнитель, валидатор и модули окружения

📚 Архитектура

Структура проекта

just-mcp/
├── src/main.rs              # CLI binary
├── just-mcp-lib/           # Core library
│   ├── parser.rs           # Justfile parsing
│   ├── executor.rs         # Recipe execution  
│   ├── validator.rs        # Validation logic
│   ├── environment.rs      # Environment management
│   └── mcp_server.rs       # MCP protocol implementation
├── tests/                  # Integration tests
└── justfile               # Demo recipes

Технологический стек

• Rust 1.82+ с поддержкой async/await
• rmcp 0.3.0 — Официальный MCP SDK для Rust
• serde/serde_json — Сериализация JSON
• snafu — Структурированная обработка ошибок
• tokio — Асинхронная среда выполнения

🔄 Дорожная карта разработки

🎯 Следующие приоритетные задачи (Осталось 33%)

1. Система автодополнения в стиле LSP — Интеллектуальное автодополнение для рецептов и параметров
2. Расширенная диагностика — Улучшенные отчёты об ошибках синтаксиса и предложения
3. Виртуальная файловая система — Поддержка stdin, удалённых источников и буферов в памяти
4. Подготовка релиза — Документация, CI/CD и публикация пакета

🚀 Будущие улучшения

• Система плагинов для пользовательских типов рецептов
• Интеграция с другими инструментами сборки
• Оптимизация производительности для больших just-файлов
• Расширенная визуализация зависимостей

📖 Шаблоны использования

Выполнение рецептов

// List available recipes
await client.callTool("list_recipes", {});

// Execute recipe with parameters  
await client.callTool("run_recipe", {
  "recipe_name": "build",
  "args": "[\"--release\"]"
});

// Get recipe information
await client.callTool("get_recipe_info", {
  "recipe_name": "test"
});

Валидация

// Validate justfile
await client.callTool("validate_justfile", {
  "justfile_path": "./custom.justfile"  
});

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

Этот проект следует методологии разработки b00t: - Подход TDD — Сначала тесты, потом реализация - Ветки для функций — Никогда не работайте напрямую в основной ветке - Структурированные ошибки — Используйте snafu для управления ошибками - Рабочий процесс Git — Чистые коммиты с описательными сообщениями

Команды для разработки

just build    # Build the project
just test     # Run tests  
just server   # Start MCP server
just clean    # Clean build artifacts

📄 Лицензия

Этот проект лицензирован в соответствии с LICENSE.

🚀 Настройка релизов и CI/CD

✅ Завершённые настройки

Cocogitto и соглашения о коммитах

• Установлен cocogitto для соблюдения соглашений о коммитах
• Настроен cog.toml с правильными типами коммитов и параметрами журнала изменений
• Настроены git-хуки для проверки сообщений коммитов (commit-msg) и тестирования перед отправкой (pre-push)

CI/CD GitHub Actions

• Конвейер CI (ci.yml): Многоплатформенное тестирование (Ubuntu, Windows, macOS), форматирование, clippy, проверка коммитов
• Конвейер релизов (release.yml): Автоматическое версионирование, генерация журнала изменений, релизы GitHub и публикация на crates.io
• Сборка бинарных файлов (build-binaries.yml): Кросс-платформенная компиляция бинарных файлов для пакетов npm и pip
• Конвейер контейнеров (container.yaml): Сборка Docker-образов для нескольких платформ (linux/amd64, linux/arm64) с публикацией в GitHub Container Registry

Docker-образы

• Сборка для нескольких платформ: linux/amd64 и linux/arm64
• Минимальный размер образа благодаря статическим musl-бинарным файлам и базовому образу scratch
• Автоматическая расстановка тегов с семантическим версионированием (major, major.minor, major.minor.patch, latest)
• Публикация в GitHub Container Registry (ghcr.io)
• Интеграция с рабочим процессом релизов для автоматического развёртывания

Подготовка к crates.io

# npm (JavaScript/TypeScript ecosystems)
npm install -g just-mcp
# or
npx just-mcp --stdio

# pip (Python ecosystems)
pip install just-mcp
# or
uvx just-mcp --stdio

# cargo (Rust ecosystem)
cargo install just-mcp

# Download pre-built binaries
wget https://github.com/promptexecution/just-mcp/releases/latest/download/just-mcp-x86_64-unknown-linux-gnu.tar.gz
# Or use Docker
docker pull ghcr.io/promptexecution/just-mcp:latest

# Or download from GitHub releases
wget https://github.com/promptexecution/just-mcp/releases/latest/download/just-mcp

• Обновлены оба файла Cargo.toml с полной метаинформацией (описание, ключевые слова, категории, лицензия и т. д.)
• Добавлены корректные исключения для файлов, используемых только в разработке
• Проверено наличие лицензии MIT

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

• README.md готов к продакшену с инструкциями по установке и использованию
• Создан начальный CHANGELOG.md для отслеживания релизов
• Обновлён .gitignore с записями, специфичными для Rust

🚀 Развёртывание в продакшене

Рабочий процесс разработки:

• Все коммиты должны следовать формату conventional commits (контролируется git-хуками)
• Используйте префиксы feat:, fix:, docs: и т. д. для автоматического версионирования
• Пуш в ветку main запускает автоматические релизы и публикацию на crates.io
• Тесты библиотеки проходят ✅ (25/25) с полным покрытием тестами

Процесс релиза:

• Автоматическое версионирование: Cocogitto анализирует сообщения коммитов для семантического версионирования
• Релизы GitHub: Автоматическая генерация changelog и создание релизов на GitHub
• Распространение бинарных файлов: Предварительно собранные бинарные файлы для Linux (x86_64, aarch64), macOS (x86_64, aarch64) и Windows (x86_64)
• Публикация на crates.io: Сначала публикуется библиотечный крейт (just-mcp-lib), затем бинарный крейт (just-mcp)
• Публикация на npm: Обёрточный пакет для простой интеграции с Node.js/TypeScript
• Публикация на PyPI: Обёрточный пакет для Python для установки через pip/uvx
• CI/CD-конвейер: Многоплатформенное тестирование (Ubuntu, Windows, macOS) с проверками форматирования и clippy

Способы установки:

# npm (JavaScript/TypeScript ecosystems)
npm install -g just-mcp
# or
npx just-mcp --stdio

# pip (Python ecosystems)
pip install just-mcp
# or
uvx just-mcp --stdio

# cargo (Rust ecosystem)
cargo install just-mcp

# Download pre-built binaries
wget https://github.com/promptexecution/just-mcp/releases/latest/download/just-mcp-x86_64-unknown-linux-gnu.tar.gz
# Or use Docker
docker pull ghcr.io/promptexecution/just-mcp:latest

# Or download from GitHub releases
wget https://github.com/promptexecution/just-mcp/releases/latest/download/just-mcp

🔗 Связанные проекты

• Just — средство запуска команд, с которым интегрируется этот инструмент
• Model Context Protocol — спецификация протокола
• rmcp — официальный Rust SDK для MCP

Партнёры just-mcp

• just-vscode — расширение VSCode с интеграцией LSP для расширенного редактирования Just
• just-awesome-agents — коллекция шаблонов и инструментов для исполнения агентов с помощью Just

Тестовое изменение для запуска pre-push хука