Just MCP Server

just-mcp

👋 LLM に Just を使わせる方法

Just コマンドランナーとシームレスに統合し、AI アシスタントが標準化された MCP プロトコルを通じて Justfile のレシピを検出、実行、調査できる、本番環境対応の MCP サーバーです。

🎯 Just + MCP = より優れたエージェント実行

コンテキストを節約する抽象化

すぐには明らかでないかもしれませんが、LLM が bash ではなく Just を使う利点は、MCP 経由で Just コマンドを実行することでコンテキストを節約できる抽象化が得られる点です。これにより、bash ファイル、Python スクリプト、その他のビルド成果物を開いて読み込むためにコンテキストを無駄にする必要がありません。MCP 経由で LLM が受け取るのはコマンド、パラメーター、ヒントだけです。つまり「これらは使用できるコマンド」として記憶に残ります。

Justfile の学習コストをなくす

LLM がコマンド一覧を取得するために just -l を実行し、必然的に justfile を読み始め、Makefile のように Justfile の構文を書こうとして、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% 完了（コアタスク 12 件中 8 件）

✅ 実装済みの機能

• 🏗️ 完全な MCP サーバー - MCP 2024-11-05 プロトコルに対応した rmcp 0.3.0 の完全な統合
• 📋 レシピの検出 - 利用可能なすべての 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 のリリースで公開されているプラットフォーム固有の tarball（just-mcp-*-*.tar.gz）をダウンロードし、実行ファイルを ${PKGX_DIR:-$HOME/.pkgx}/bin に展開して、渡された引数を使って CLI を実行します。長期的に just-mcp を利用できるようにするには、この bin ディレクトリをシェルの PATH に追加してください。パッケージングマニフェストは 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 を使用

Claude Desktop の MCP 設定に追加します。

バイナリを使用

{
  "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 - rmcp クライアントを使用した型安全な SDK 統合テスト
• 単体テスト - パーサー、エグゼキューター、バリデーター、環境モジュールを対象とする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 - Rust 用の公式 MCP SDK
• serde/serde_json - JSON シリアライズ
• snafu - 構造化されたエラー処理
• tokio - 非同期ランタイム

🔄 開発ロードマップ

🎯 次の優先タスク（残り33%）

1. LSP スタイルの補完システム - レシピとパラメーターのインテリジェントな自動補完
2. 診断機能の強化 - 高度な構文エラー報告と提案
3. 仮想ファイルシステム - stdin、リモートソース、メモリ内バッファーのサポート
4. リリース準備 - ドキュメント、CI/CD、クレートの公開

🚀 今後の拡張

• カスタムレシピタイプ向けのプラグインシステム
• 他のビルドツールとの統合
• 大規模な justfile 向けのパフォーマンス最適化
• 高度な依存関係の可視化

📖 使用パターン

レシピの実行

// 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 アプローチ - まずテストを作成し、その後に実装
• フィーチャーブランチ - main ブランチ上で直接作業しない
• 構造化されたエラー - エラー管理に 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 と Conventional Commits

• Conventional Commits に準拠したコミットを強制するため、cocogitto をインストール
• 適切なコミットタイプと変更履歴の設定を含む cog.toml を構成
• コミットメッセージのリンティング用（commit-msg）およびプッシュ前テスト用の Git フックを設定

GitHub Actions CI/CD

• 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 への公開準備

• 両方の Cargo.toml ファイルに完全なメタデータ（説明、キーワード、カテゴリー、ライセンスなど）を追加
• 開発専用ファイルを適切に除外
• MIT ライセンスが設定されていることを確認

ドキュメントと構成

• README.md にインストール方法と使い方を記載し、本番環境で使用できる状態に整備
• リリース管理用の初期 CHANGELOG.md を作成
• Rust 固有の項目を .gitignore に追加

🚀 本番環境へのデプロイ

開発ワークフロー：

• すべてのコミットは Conventional Commits の形式に従う必要があります（Git フックで強制）
• 自動バージョニングには feat:、fix:、docs: などのプレフィックスを使用
• main ブランチへのプッシュで、自動リリースと crates.io への公開を実行
• ライブラリのテストに合格 ✅（25/25）。包括的なテストカバレッジを確保

リリースプロセス：

• 自動バージョニング：Cocogitto がコミットメッセージを分析し、セマンティックバージョニングを適用
• GitHub リリース：変更履歴の自動生成と GitHub リリースの作成
• バイナリ配布：Linux（x86_64、aarch64）、macOS（x86_64、aarch64）、Windows（x86_64）向けのビルド済みバイナリ
• Crates.io への公開：ライブラリクレート（just-mcp-lib）を先に公開し、その後バイナリクレート（just-mcp）を公開
• npm への公開：Node.js/TypeScript と簡単に連携できるラッパーパッケージ
• PyPI への公開：pip/uvx でインストールできる Python ラッパーパッケージ
• CI/CD パイプライン：フォーマットと clippy のチェックを含む、複数プラットフォームでのテスト（Ubuntu、Windows、macOS）

インストール方法：

# 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 MCP SDK

just-mcp の仲間

• just-vscode - Just の記述を強化する LSP 連携機能付き VSCode 拡張機能
• just-awesome-agents - Just を使ったエージェント実行のためのパターンとツール集# Test change to trigger pre-push hook