Just MCP

🚀 just-mcp

👋 just-mcp 是一個可用於生產環境的 MCP 服務器，它能與 Just 命令運行器實現無縫集成，使 AI 助手可以通過標準化的 MCP 協議發現、執行和內省 Justfile 配方。

🚀 快速開始

安裝

你可以選擇以下任意一種安裝方式：

npm（JavaScript/TypeScript）

# 全局安裝
npm install -g just-mcp

# 或者使用 npx（無需安裝）
npx just-mcp --stdio

pip（Python）

# 使用 pip 安裝
pip install just-mcp

# 或者使用 uvx（推薦）
uvx just-mcp --stdio

Cargo（Rust）

# 從 crates.io 安裝
cargo install just-mcp

# 或者從源代碼構建
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。如果你需要長期使用 just-mcp，請將該 bin 目錄添加到 shell 的 PATH 中。打包清單位於 ，並與 pkgxdev/pantry 條目保持一致。

使用 Docker

# 從 GitHub 容器註冊表拉取最新鏡像
docker pull ghcr.io/promptexecution/just-mcp:latest

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

# 本地構建
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"
      ]
    }
  }
}

使用示例

# 作為 MCP 服務器運行
just-mcp --stdio

# 在特定目錄中運行
just-mcp --directory /path/to/project --stdio

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

✨ 主要特性

節省上下文的抽象

LLMs 使用 Just 而非 bash 的好處在於，通過 MCP 運行 Just 命令能提供一種節省上下文的抽象，LLMs 無需浪費上下文去打開/讀取 bash 文件、Python 腳本或其他構建工件。通過 MCP，LLMs 只需獲取命令、參數和提示信息，這些信息會存儲在它們的“記憶”中，即“這些是可供你使用的命令”。

消除 Justfile 學習曲線

無需再看著 LLMs 執行 just -l 來獲取命令列表，然後不可避免地開始閱讀 justfile，接著嘗試編寫 justfile 語法（就像它是一個 Makefile），從而破壞 justfile 並帶來糟糕的體驗。目前前沿模型中 Just 不斷發展的語法語料庫還不夠大，我們需要在訓練數據集中有更多包含 justfile 的流行倉庫。

比原始 bash 訪問更安全

Just-mcp 本質上比 bash 更安全。如果你關注 HackerNews，每天至少會看到一個關於操作員的故事，他們的 LLMs 開始遺忘、產生幻覺，最終崩潰——刪除文件並做出不良的、不想要的操作。在不仔細監控上下文消耗的情況下，給 LLMs 無監督、無限制的 bash 訪問權限是一場災難的導火索。

使用 Justfile 可以解決這個問題。即使 LLMs 修改了自己的 justfile，下一個上下文也會被 justfile 記錄（希望是在一個冪等的 git 倉庫中）。這種抽象使 LLMs 免受命令行復雜性的影響，避免因幻覺或跟蹤當前工作目錄的注意力問題而導致其偏離軌道。

強大的代理執行工具

Just-mcp 非常適合進行代理執行的任何人：

• 超低開銷 - 可能比其他任何工具都要好
• 對人類友好 - justfile 對人類來說很容易理解，對 LLMs 來說開銷也很低
• 快速簡便 - 雖然有些人更喜歡完整的 Python FastAPI 服務器，但 just-mcp 非常簡單
• 對小模型友好 - 與具有 8k - 32k 上下文限制的可自託管 GPU/CPU 開源模型配合使用效果很好

內置安全模式

Just 具有以下有用的模式：

• 透明日誌記錄 - 不會分散代理的注意力
• 二次模型檢查 - 在執行之前使用小模型掃描命令，詢問“這是否有害？”
• 類似 Python 裝飾器的模式 - 用於命令驗證
• 由 git 倉庫支持的冪等執行

💻 使用示例

基礎用法

// 列出可用的配方
await client.callTool("list_recipes", {});

// 帶參數執行配方
await client.callTool("run_recipe", {
  "recipe_name": "build",
  "args": "[\"--release\"]"
});

// 獲取配方信息
await client.callTool("get_recipe_info", {
  "recipe_name": "test"
});

高級用法

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

📚 詳細文檔

當前狀態：67% 完成（8/12 個核心任務）

已實現功能

• 🏗️ 完整的 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 的語法和語義錯誤

🔧 技術細節

測試

綜合測試套件

# 運行所有測試（33 個測試）
cargo test

# 運行特定測試套件
cargo test --test basic_mcp_test      # 協議合規性測試
cargo test --test mcp_integration_working  # SDK 集成測試

測試架構

• basic_mcp_test.rs - 使用原始 JSON - RPC 進行直接協議合規性測試
• mcp_integration_working.rs - 使用 rmcp 客戶端進行類型安全的 SDK 集成測試
• 單元測試 - 25 個以上的測試覆蓋解析器、執行器、驗證器和環境模塊

架構

項目結構

just-mcp/
├── src/main.rs              # CLI 二進制文件
├── just-mcp-lib/           # 核心庫
│   ├── parser.rs           # Justfile 解析
│   ├── executor.rs         # 配方執行  
│   ├── validator.rs        # 驗證邏輯
│   ├── environment.rs      # 環境管理
│   └── mcp_server.rs       # MCP 協議實現
├── tests/                  # 集成測試
└── justfile               # 演示配方

技術棧

• Rust 1.82+ 支持異步/等待
• rmcp 0.3.0 - 官方 Rust MCP SDK
• serde/serde_json - JSON 序列化
• snafu - 結構化錯誤處理
• tokio - 異步運行時

開發路線圖

下一個優先任務（剩餘 33%）

1. LSP 風格的自動完成系統 - 為配方和參數提供智能自動完成功能
2. 增強的診斷功能 - 高級語法錯誤報告和建議
3. 虛擬文件系統 - 支持 stdin、遠程源和內存緩衝區
4. 發佈準備 - 文檔、CI/CD 和 crate 發佈

未來增強功能

• 自定義配方類型的插件系統
• 與其他構建工具集成
• 針對大型 justfile 的性能優化
• 高級依賴可視化

🤝 貢獻

本項目遵循 ：

• 測試驅動開發（TDD）方法 - 先編寫測試，再進行實現
• 功能分支 - 絕不直接在主分支上工作
• 結構化錯誤處理 - 使用 snafu 進行錯誤管理
• Git 工作流 - 提交記錄清晰，信息描述準確

開發命令

just build    # 構建項目
just test     # 運行測試  
just server   # 啟動 MCP 服務器
just clean    # 清理構建工件

📄 許可證

本項目根據 LICENSE 進行許可。

🔗 相關項目

• Just - 本項目集成的命令運行器
• Model Context Protocol - 協議規範
• rmcp - 官方 Rust MCP SDK

just-mcp 的相關項目

• just-vscode - 具有 LSP 集成的 VSCode 擴展，用於增強 Just 編寫體驗
• just-awesome-agents - 用於使用 Just 進行代理執行的模式和工具集合