仅-MCP

Name: 仅-MCP
Author: PromptExecution

作者：PromptExecution33 星标更新：2025-11-15

安装使用来源：spider==github.com

项目介绍

技术文档摘要

just-mcp

👋 让LLMs通过Just说话的方式

这是一个生产就绪的MCP服务器，提供了与Just命令运行器的无缝集成，使AI助手能够通过标准化的MCP协议发现、执行和检查Justfile食谱。

🎯 为什么Just + MCP = 更好的代理执行

上下文保存抽象

如果不是很明显的话，让LLMs使用Just而不是bash的好处在于，通过MCP运行Just命令提供了一个上下文保存的抽象层，它们不需要浪费上下文去打开或读取bash文件、Python脚本或其他构建工件。LLM通过MCP只需获取命令、参数和提示——这些在它们的记忆中是“可用的命令”。

消除Justfile学习曲线

不再需要观看LLMs执行just -l来获取命令列表，不可避免地开始阅读justfile，然后尝试编写justfile语法（就像Makefile一样），破坏justfile并创建糟糕的体验。Just不断演进的语法在前沿模型中目前没有足够的语料库——我们需要更多包含justfile的流行仓库进入训练数据集。

比原始Bash访问更安全

Just-mcp从根本上比bash更安全。如果你经常浏览HackerNews，每天至少会看到一个关于操作员的LLMs开始忘记、产生幻觉并最终崩溃的故事——删除文件并做一些不想要的事情。给LLMs无监督且不受限制的bash访问而不仔细监控上下文消耗是一个灾难配方。

**使用Justfile解决了这个问题。**即使LLM修改了自己的justfile，下一个上下文也会被justfile记忆化（希望在一个幂等的git仓库中）。这种抽象保护了LLM免受命令行复杂性的困扰，其中幻觉或当前工作目录的注意力跟踪会导致它失控并坠落悬崖。

强大的代理执行工具

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

超低开销 - 可能比其他所有工具都好
人类友好 - justfiles对人类来说易于理解，对LLM来说开销也低
快速而简单 - 虽然有些人喜欢完整的Python FastAPI服务器，但just-mcp就是这么简单
适合小型模型 - 与具有8k-32k上下文限制的自托管GPU/CPU开源模型完美配合

内置的安全模式

Just有一些有用的模式来引入：

透明日志记录，不会分散代理的注意力
二级模型检查 - 使用小型模型扫描命令，询问“这有害吗？”在执行前
类似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工具

list_recipes - 列出justfile中的所有可用食谱
run_recipe - 执行特定食谱，可选参数
get_recipe_info - 获取特定食谱的详细信息
validate_justfile - 验证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

使用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

🧪 测试

综合测试套件

# 运行所有测试（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+，支持async/await
rmcp 0.3.0 - Rust官方MCP SDK
serde/serde_json - JSON序列化
snafu - 结构化错误处理
tokio - 异步运行时

🔄 开发路线图

🎯 接下来的优先任务（剩余33%）

LSP风格的自动完成功能 - 针对食谱和参数的智能自动完成
增强诊断 - 高级语法错误报告和建议
虚拟文件系统 - 支持stdin、远程来源和内存缓冲区
发布准备 - 文档、CI/CD和crate发布

🚀 未来改进

插件系统以支持自定义食谱类型
与其他构建工具的集成
大型justfile的性能优化
高级依赖可视化

📖 使用模式

食谱执行

// 列出可用食谱
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"
});

🤝 贡献

此项目遵循_b00t_开发方法论：

TDD方法 - 先写测试，再实现
特性分支 - 不要在主分支上直接工作
结构化错误 - 使用snafu进行错误管理
Git工作流 - 清晰的提交和描述性消息

开发命令

just build    # 构建项目
just test     # 运行测试
just server   # 启动MCP服务器
just clean    # 清理构建工件

📄 许可证

此项目根据LICENSE许可。

🚀 发布设置及CI/CD

✅ 已完成设置

Cocogitto & Conventional Commits

安装cocogitto以强制执行常规提交
配置cog.toml，包括适当的提交类型和变更日志设置
设置git钩子以进行提交消息检查（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容器注册表

Docker镜像

为linux/amd64和linux/arm64构建多平台镜像
使用静态musl二进制文件和基础镜像scratch，最小化镜像大小
自动标记为语义版本（主要、主要.次要、主要.次要.补丁、最新）
发布到GitHub容器注册表（ghcr.io）
与发布流程集成，实现自动部署

Crates.io准备

更新两个Cargo.toml文件，包含完整元数据（描述、关键词、类别、许可证等）
添加适当排除项，仅用于开发的文件
确认MIT许可证已到位

文档与结构

生产就绪的README.md，包含安装和使用说明
创建初始CHANGELOG.md，用于发布追踪
更新.gitignore，包含Rust特定条目

🚀 生产部署

开发工作流：

所有提交必须遵循常规提交格式（由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发布：首先发布库crate（just-mcp-lib），然后发布二进制crate（just-mcp）
npm发布：用于Node.js/TypeScript集成的包装程序
PyPI发布：用于pip/uvx安装的Python包装程序
CI/CD流水线：多平台测试（Ubuntu、Windows、macOS），带有格式化和clippy检查

安装方法：

# npm（JavaScript/TypeScript生态系统）
npm install -g just-mcp
# 或
npx just-m
cp --stdio

# pip（Python生态系统）
pip install just-mcp
# 或
uvx just-mcp --stdio

# cargo（Rust生态系统）
cargo install just-mcp

# 下载预构建的二进制文件
wget https://github.com/promptexecution/just-mcp/releases/latest/download/just-mcp-x86_64-unknown-linux-gnu.tar.gz
# 或使用Docker
docker pull ghcr.io/promptexecution/just-mcp:latest

# 或从GitHub发布下载
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进行代理执行的模式和工具集合