promptexecution/just-mcp

**👋 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.
🎯 **Why Just + MCP = Better Agent Execution**
**Context-Saving Abstraction**
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 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."
**Eliminates the Justfile Learning Curve**
No 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.
**Safer Than Raw Bash Access**
Just-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.
**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.
**Powerful Agent Execution Tool**
Just-mcp is perfect for anybody doing agent execution:
- **Ultra-low overhead** - probably better than every other tool
- **Human-friendly** - justfiles are easy for humans and low overhead for LLMs
- **Quick and dirty** - while some prefer full Python FastAPI servers, just-mcp is just easy-as
- **sm0l model friendly** - works great with self-hostable GPU/CPU open source models with 8k-32k context limits
**Built-in Safety Patterns**
Just has useful patterns for introducing:
- **Transparent logging** without distracting the agent
- **Secondary model inspection** - use sm0l models to scan commands asking "is this harmful?" before execution
- **Python decorator-like patterns** for command validation
- **Idempotent execution** backed by git repos
b00t
🚀 Current Status: **67% Complete** (8/12 core tasks)
✅ **Implemented Features**
- **🏗️ Complete MCP Server** - Full rmcp 0.3.0 integration with MCP 2024-11-05 protocol
- **📋 Recipe Discovery** - Parse and list all available Justfile recipes
- **⚡ Recipe Execution** - Execute recipes with parameters and capture structured output
- **🔍 Recipe Introspection** - Get detailed recipe information, parameters, and documentation
- **✅ Justfile Validation** - Syntax and semantic validation with error reporting
- **🌍 Environment Management** - Comprehensive .env file support and variable expansion
- **🧪 Full Test Coverage** - 33 passing tests across integration and unit test suites
🎯 **MCP Tools Available**
1. **list_recipes** - List all available recipes in the justfile
2. **run_recipe** - Execute a specific recipe with optional arguments
3. **get_recipe_info** - Get detailed information about a specific recipe
4. **validate_justfile** - Validate the justfile for syntax and semantic errors