Just MCP Server

just-mcp

👋 让大模型说 Just

一个可用于生产环境的 MCP 服务，可与 Just 命令运行器无缝集成，让 AI 助手能够通过标准化的 MCP 协议发现、执行和检查 Justfile 配方。

🎯 Just + MCP = 更出色的 Agent 执行

节省上下文的抽象层

其好处或许一目了然：与使用 bash 相比，让大模型使用 Just 命令（通过 MCP）可以提供一种节省上下文的抽象层，无需浪费上下文来打开或读取 bash 文件、Python 脚本或其他构建产物。大模型通过 MCP 只需获取命令、参数和提示——这些内容会记在它们的记忆中，作为“这些是你可以使用的命令”。

消除 Justfile 的学习曲线

不必再看着大模型执行 just -l 获取命令列表，接着不可避免地开始阅读 justfile，然后尝试编写 justfile 语法（把它当成 Makefile），最终损坏 justfile，带来糟糕的体验。Just 不断演进的语法在当前前沿模型的训练数据中仍缺乏足够多的语料——我们需要更多包含 justfile 的热门仓库进入训练数据集。

比直接访问 Bash 更安全

从根本上说，Just-mcp 比 bash 更安全。如果你阅读 HackerNews，就会发现每天至少有一个故事，讲述操作人员的大模型开始遗忘、产生幻觉，最终失控——删除文件并做出令人厌恶的非预期操作。在没有仔细监控上下文消耗的情况下，向大模型提供不受监督、不受限制的 bash 访问权限，无异于自找灾难。

使用 Justfile 可以解决这个问题。 即使大模型修改了自己的 justfile，下一个上下文也会由 justfile 进行记忆（希望它位于一个幂等的 git 仓库中）。这种抽象层能让大模型免受命令行复杂性的影响，避免幻觉或注意力跟踪当前工作目录导致它们偏离正轨、坠入深渊。

强大的 Agent 执行工具

Just-mcp 非常适合任何进行 Agent 执行的人：

• 极低的开销 - 可能比其他所有工具都好
• 对人类友好 - justfile 对人类而言易于使用，对大模型而言开销低
• 简单粗暴 - 有些人偏好完整的 Python FastAPI 服务，而 just-mcp 就是简单易用
• sm0l 模型友好 - 在可自托管的 GPU/CPU 开源模型上表现出色，支持 8k-32k 的上下文限制

内置安全模式

Just 提供了实用模式，可用于实现：

• 透明日志记录，不干扰 Agent
• 二级模型检查 - 使用 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。如果你希望长期使用 just-mcp，请将该 bin 目录添加到 shell 的 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 和 crate 发布

🚀 未来增强

• 用于自定义配方类型的插件系统
• 与其他构建工具集成
• 针对大型 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

• 安装 cocogitto，以强制使用 conventional commit 规范
• 配置 cog.toml，设置合适的提交类型和变更日志选项
• 设置 git hooks，用于提交消息检查（commit-msg）和推送前测试

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，用于跟踪发布记录
• 在 .gitignore 中添加了 Rust 特有的条目

🚀 生产部署

开发工作流：

• 所有提交都必须遵循 conventional commit 格式（由 git hooks 强制执行）
• 使用 feat:、fix:、docs: 等前缀，以便自动管理版本
• 推送到 main 分支会触发自动发布和 crates.io 发布
• 库测试通过 ✅（25/25），测试覆盖全面

发布流程：

• 自动版本管理：Cocogitto 会分析提交消息并进行语义化版本管理
• GitHub 发布版本：自动生成变更日志并创建 GitHub 发布版本
• 二进制分发：提供适用于 Linux（x86_64、aarch64）、macOS（x86_64、aarch64）和 Windows（x86_64）的预构建二进制文件
• Crates.io 发布：先发布库 crate（just-mcp-lib），再发布二进制 crate（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 MCP SDK

just-mcp 的伙伴项目

• just-vscode - 提供 LSP 集成的 VSCode 扩展，助力更高效地编写 Just
• just-awesome-agents - 汇集了使用 Just 执行 Agent 的模式和工具# 测试更改以触发推送前钩子