👋 A way to let LLMs speak Just A production-ready MCP server that provides seamless integration with Just command runner, enabling AI assistants to discover, execute, and introspect Justfile recipes through the standardized MCP protocol. If it isn't immediately obvious, the benefit of having LLMs use Just vs. bash is that running Just commands (via MCP) provides a context-saving abstraction where
Add this skill
npx mdskills install promptexecution/just-mcpProduction-ready MCP server exposing Just command runner with safety-focused architecture and excellent docs
1# just-mcp23[](https://github.com/PromptExecution/just-mcp/actions/workflows/ci.yml)4[](https://github.com/PromptExecution/just-mcp/actions/workflows/release.yml)5[](https://crates.io/crates/just-mcp)6[](https://opensource.org/licenses/MIT)78[](https://archestra.ai/mcp-catalog/promptexecution__just-mcp)910**👋 A way to let LLMs speak Just**1112A production-ready MCP server that provides seamless integration with [Just](https://github.com/casey/just) command runner, enabling AI assistants to discover, execute, and introspect Justfile recipes through the standardized MCP protocol.1314## 🎯 **Why Just + MCP = Better Agent Execution**1516### **Context-Saving Abstraction**17If it isn't immediately obvious, the benefit of having LLMs use Just vs. bash is that running Just commands (via MCP) provides a context-saving abstraction where they don't need to waste context opening/reading bash files, Python scripts, or other build artifacts. The LLM via MCP simply gets the command, parameters, and hints - it's in their memory as "these are commands available to you."1819### **Eliminates the Justfile Learning Curve**20No more watching LLMs execute `just -l` to get command lists, inevitably start reading the justfile, then try to write justfile syntax (like it's a Makefile), corrupt the justfile, and create a bad experience. Just's evolving syntax simply doesn't have a large enough corpus in frontier models today - we need more popular repos with justfiles in the training dataset.2122### **Safer Than Raw Bash Access**23Just-mcp is fundamentally safer than bash. If you read HackerNews, there's a story at least once daily about operators whose LLMs start forgetting, hallucinating, and eventually breaking down - deleting files and doing nasty unwanted things. Giving LLMs unsupervised, unrestricted bash access without carefully monitoring context consumption is a recipe for disaster.2425**Using Justfile fixes that.** Even if the LLM modifies its own justfile, the next context is memoized by the justfile (hopefully in an idempotent git repo). This abstraction shields the llm from the command line complexity where hallucinations or attention tracking the current working directory cause it to go over the rails and off the cliff.2627### **Powerful Agent Execution Tool**28Just-mcp is perfect for anybody doing agent execution:29- **Ultra-low overhead** - probably better than every other tool30- **Human-friendly** - justfiles are easy for humans and low overhead for LLMs31- **Quick and dirty** - while some prefer full Python FastAPI servers, just-mcp is just easy-as32- **sm0l model friendly** - works great with self-hostable GPU/CPU open source models with 8k-32k context limits3334### **Built-in Safety Patterns**35Just has useful patterns for introducing:36- **Transparent logging** without distracting the agent37- **Secondary model inspection** - use sm0l models to scan commands asking "is this harmful?" before execution38- **Python decorator-like patterns** for command validation39- **Idempotent execution** backed by git repos4041## b00t42```43b00t mcp create just-mcp -- bash just-mcp --stdio "${REPO_ROOT}"44b00t mcp export just-mcp45```4647## 🚀 Current Status: **67% Complete** (8/12 core tasks)4849### ✅ **Implemented Features**50- **🏗️ Complete MCP Server** - Full rmcp 0.3.0 integration with MCP 2024-11-05 protocol51- **📋 Recipe Discovery** - Parse and list all available Justfile recipes52- **⚡ Recipe Execution** - Execute recipes with parameters and capture structured output53- **🔍 Recipe Introspection** - Get detailed recipe information, parameters, and documentation54- **✅ Justfile Validation** - Syntax and semantic validation with error reporting55- **🌍 Environment Management** - Comprehensive .env file support and variable expansion56- **🧪 Full Test Coverage** - 33 passing tests across integration and unit test suites5758### 🎯 **MCP Tools Available**591. **`list_recipes`** - List all available recipes in the justfile602. **`run_recipe`** - Execute a specific recipe with optional arguments613. **`get_recipe_info`** - Get detailed information about a specific recipe624. **`validate_justfile`** - Validate the justfile for syntax and semantic errors6364## 🏃 **Quick Start**6566### Installation6768Choose your preferred installation method:6970#### npm (JavaScript/TypeScript)71```bash72# Install globally73npm install -g just-mcp7475# Or use with npx (no installation required)76npx just-mcp --stdio77```7879#### pip (Python)80```bash81# Install with pip82pip install just-mcp8384# Or use with uvx (recommended)85uvx just-mcp --stdio86```8788#### Cargo (Rust)89```bash90# Install from crates.io91cargo install just-mcp9293# Or build from source94git clone https://github.com/promptexecution/just-mcp95cd just-mcp96cargo build --release97```9899#### pkgx (pkgxdev)100```bash101pkgx just-mcp --stdio102```103104`pkgx` downloads the platform-specific tarball that GitHub releases expose (`just-mcp-*-*.tar.gz`), extracts the executable into `${PKGX_DIR:-$HOME/.pkgx}/bin`, and runs the CLI with the arguments you pass. Add that bin directory to your shell’s `PATH` if you need `just-mcp` available long-term. The packaging manifest lives in [`pkgx/projects/github.com/promptexecution/just-mcp/package.yml`](pkgx/projects/github.com/promptexecution/just-mcp/package.yml) and mirrors the `pkgxdev/pantry` entry.105106#### Using Docker107```bash108# Pull the latest image from GitHub Container Registry109docker pull ghcr.io/promptexecution/just-mcp:latest110111# Run with Docker112docker run --rm -v $(pwd):/workspace ghcr.io/promptexecution/just-mcp:latest --stdio113114# Build locally115docker build -t just-mcp:local .116docker run --rm -v $(pwd):/workspace just-mcp:local --stdio117```118119Available Docker image tags:120- `latest` - Latest stable release121- `X.Y.Z` - Specific version (e.g., `0.1.0`)122- `X.Y` - Latest patch version (e.g., `0.1`)123- `X` - Latest minor version (e.g., `0`)124125### Claude Desktop Integration126127#### Using npm/npx128Add to your Claude Desktop MCP configuration:129130#### Using Binary131```json132{133 "mcpServers": {134 "just-mcp": {135 "command": "npx",136 "args": ["-y", "just-mcp", "--stdio"]137 }138 }139}140```141142#### Using pip/uvx143```json144{145 "mcpServers": {146 "just-mcp": {147 "command": "uvx",148 "args": ["just-mcp", "--stdio"]149 }150 }151}152```153154#### Using cargo or manual install155```json156{157 "mcpServers": {158 "just-mcp": {159 "command": "/path/to/just-mcp",160 "args": ["--stdio"]161 }162 }163}164```165166#### Using Docker167```json168{169 "mcpServers": {170 "just-mcp": {171 "command": "docker",172 "args": [173 "run",174 "--rm",175 "-i",176 "-v",177 "${workspaceFolder}:/workspace",178 "ghcr.io/promptexecution/just-mcp:latest",179 "--stdio"180 ]181 }182 }183}184```185186### Usage Examples187```bash188# Run as MCP server189just-mcp --stdio190191# Run in specific directory192just-mcp --directory /path/to/project --stdio193194# Using Docker195docker run --rm -v $(pwd):/workspace ghcr.io/promptexecution/just-mcp:latest --stdio196```197198## 🧪 **Testing**199200### Comprehensive Test Suite201```bash202# Run all tests (33 tests)203cargo test204205# Run specific test suites206cargo test --test basic_mcp_test # Protocol compliance testing207cargo test --test mcp_integration_working # SDK integration testing208```209210### Test Architecture211- **`basic_mcp_test.rs`** - Direct protocol compliance testing using raw JSON-RPC212- **`mcp_integration_working.rs`** - Type-safe SDK integration testing with rmcp client213- **Unit tests** - 25+ tests covering parser, executor, validator, and environment modules214215## 📚 **Architecture**216217### Project Structure218```219just-mcp/220├── src/main.rs # CLI binary221├── just-mcp-lib/ # Core library222│ ├── parser.rs # Justfile parsing223│ ├── executor.rs # Recipe execution224│ ├── validator.rs # Validation logic225│ ├── environment.rs # Environment management226│ └── mcp_server.rs # MCP protocol implementation227├── tests/ # Integration tests228└── justfile # Demo recipes229```230231### Tech Stack232- **Rust 1.82+** with async/await support233- **rmcp 0.3.0** - Official MCP SDK for Rust234- **serde/serde_json** - JSON serialization235- **snafu** - Structured error handling236- **tokio** - Async runtime237238## 🔄 **Development Roadmap**239240### 🎯 **Next Priority Tasks** (Remaining 33%)2411. **LSP-Style Completion System** - Intelligent autocompletion for recipes and parameters2422. **Enhanced Diagnostics** - Advanced syntax error reporting and suggestions2433. **Virtual File System** - Support for stdin, remote sources, and in-memory buffers2444. **Release Preparation** - Documentation, CI/CD, and crate publication245246### 🚀 **Future Enhancements**247- Plugin system for custom recipe types248- Integration with other build tools249- Performance optimizations for large justfiles250- Advanced dependency visualization251252## 📖 **Usage Patterns**253254### Recipe Execution255```javascript256// List available recipes257await client.callTool("list_recipes", {});258259// Execute recipe with parameters260await client.callTool("run_recipe", {261 "recipe_name": "build",262 "args": "[\"--release\"]"263});264265// Get recipe information266await client.callTool("get_recipe_info", {267 "recipe_name": "test"268});269```270271### Validation272```javascript273// Validate justfile274await client.callTool("validate_justfile", {275 "justfile_path": "./custom.justfile"276});277```278279## 🤝 **Contributing**280281This project follows the [_b00t_ development methodology](AGENTS.md):282- **TDD Approach** - Tests first, implementation second283- **Feature Branches** - Never work directly on main branch284- **Structured Errors** - Use snafu for error management285- **Git Workflow** - Clean commits with descriptive messages286287### Development Commands288```bash289just build # Build the project290just test # Run tests291just server # Start MCP server292just clean # Clean build artifacts293```294295## 📄 **License**296297This project is licensed under [LICENSE](LICENSE).298299## 🚀 **Release Setup & CI/CD**300301### ✅ **Completed Setup**302303#### **Cocogitto & Conventional Commits**304- Installed cocogitto for conventional commit enforcement305- Configured `cog.toml` with proper commit types and changelog settings306- Set up git hooks for commit message linting (`commit-msg`) and pre-push testing307308#### **GitHub Actions CI/CD**309- **CI Pipeline** (`ci.yml`): Multi-platform testing (Ubuntu, Windows, macOS), formatting, clippy, commit linting310- **Release Pipeline** (`release.yml`): Automated versioning, changelog generation, GitHub releases, and crates.io publishing311- **Binary Builds** (`build-binaries.yml`): Cross-platform binary compilation for npm and pip packages312- **Container Pipeline** (`container.yaml`): Multi-platform Docker image builds (linux/amd64, linux/arm64) pushed to GitHub Container Registry313314#### **Docker Images**315- Multi-platform builds for `linux/amd64` and `linux/arm64`316- Minimal image size using static musl binaries and scratch base image317- Automatic tagging with semantic versioning (major, major.minor, major.minor.patch, latest)318- Published to GitHub Container Registry (ghcr.io)319- Integrated with release workflow for automatic deployment320321#### **Crates.io Preparation**322- Updated both `Cargo.toml` files with complete metadata (description, keywords, categories, license, etc.)323- Added proper exclusions for development-only files324- Verified MIT license is in place325326#### **Documentation & Structure**327- README.md is production-ready with installation and usage instructions328- Created initial `CHANGELOG.md` for release tracking329- Updated `.gitignore` with Rust-specific entries330331### 🚀 **Production Deployment**332333#### **Development Workflow:**334- All commits must follow conventional commit format (enforced by git hooks)335- Use `feat:`, `fix:`, `docs:`, etc. prefixes for automatic versioning336- Push to `main` branch triggers automated releases and crates.io publishing337- Library tests pass ✅ (25/25) with comprehensive test coverage338339#### **Release Process:**340- **Automated Versioning**: Cocogitto analyzes commit messages for semantic versioning341- **GitHub Releases**: Automatic changelog generation and GitHub release creation342- **Binary Distribution**: Pre-built binaries for Linux (x86_64, aarch64), macOS (x86_64, aarch64), and Windows (x86_64)343- **Crates.io Publishing**: Library crate (`just-mcp-lib`) publishes first, then binary crate (`just-mcp`)344- **npm Publishing**: Wrapper package for easy Node.js/TypeScript integration345- **PyPI Publishing**: Python wrapper package for pip/uvx installation346- **CI/CD Pipeline**: Multi-platform testing (Ubuntu, Windows, macOS) with formatting and clippy checks347348#### **Installation Methods:**349```bash350# npm (JavaScript/TypeScript ecosystems)351npm install -g just-mcp352# or353npx just-mcp --stdio354355# pip (Python ecosystems)356pip install just-mcp357# or358uvx just-mcp --stdio359360# cargo (Rust ecosystem)361cargo install just-mcp362363# Download pre-built binaries364wget https://github.com/promptexecution/just-mcp/releases/latest/download/just-mcp-x86_64-unknown-linux-gnu.tar.gz365# Or use Docker366docker pull ghcr.io/promptexecution/just-mcp:latest367368# Or download from GitHub releases369wget https://github.com/promptexecution/just-mcp/releases/latest/download/just-mcp370```371372## 🔗 **Related Projects**373374- [Just](https://github.com/casey/just) - The command runner this integrates with375- [Model Context Protocol](https://modelcontextprotocol.io/) - The protocol specification376- [rmcp](https://github.com/modelcontextprotocol/rust-sdk) - Official Rust MCP SDK377378### **Friends of just-mcp**379380- [just-vscode](https://github.com/promptexecution/just-vscode) - VSCode extension with LSP integration for enhanced Just authoring381- [just-awesome-agents](https://github.com/promptexecution/just-awesome-agents) - Collection of patterns and tools for agent execution with Just# Test change to trigger pre-push hook382
Full transparency — inspect the skill content before installing.