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 进行代理执行的模式和工具集合