{
  "markdown": "# just-mcp\n\n[![CI](https://github.com/PromptExecution/just-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/PromptExecution/just-mcp/actions/workflows/ci.yml)\n[![Release](https://github.com/PromptExecution/just-mcp/actions/workflows/release.yml/badge.svg)](https://github.com/PromptExecution/just-mcp/actions/workflows/release.yml)\n[![Crates.io](https://img.shields.io/crates/v/just-mcp.svg)](https://crates.io/crates/just-mcp)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n[![Trust Score](https://archestra.ai/mcp-catalog/api/badge/quality/promptexecution/just-mcp)](https://archestra.ai/mcp-catalog/promptexecution__just-mcp)\n\n**👋 A way to let LLMs speak Just**\n\nA 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.\n\n## 🎯 **Why Just + MCP = Better Agent Execution**\n\n### **Context-Saving Abstraction**\nIf 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.\"\n\n### **Eliminates the Justfile Learning Curve**\nNo 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.\n\n### **Safer Than Raw Bash Access**\nJust-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.\n\n**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.  \n\n### **Powerful Agent Execution Tool**\nJust-mcp is perfect for anybody doing agent execution:\n- **Ultra-low overhead** - probably better than every other tool\n- **Human-friendly** - justfiles are easy for humans and low overhead for LLMs  \n- **Quick and dirty** - while some prefer full Python FastAPI servers, just-mcp is just easy-as\n- **sm0l model friendly** - works great with self-hostable GPU/CPU open source models with 8k-32k context limits\n\n### **Built-in Safety Patterns**\nJust has useful patterns for introducing:\n- **Transparent logging** without distracting the agent\n- **Secondary model inspection** - use sm0l models to scan commands asking \"is this harmful?\" before execution\n- **Python decorator-like patterns** for command validation\n- **Idempotent execution** backed by git repos\n\n## b00t\n```\nb00t mcp create just-mcp -- bash just-mcp --stdio \"${REPO_ROOT}\"\nb00t mcp export just-mcp\n```\n\n## 🚀 Current Status: **67% Complete** (8/12 core tasks)\n\n### ✅ **Implemented Features**\n- **🏗️ Complete MCP Server** - Full rmcp 0.3.0 integration with MCP 2024-11-05 protocol\n- **📋 Recipe Discovery** - Parse and list all available Justfile recipes\n- **⚡ Recipe Execution** - Execute recipes with parameters and capture structured output\n- **🔍 Recipe Introspection** - Get detailed recipe information, parameters, and documentation\n- **✅ Justfile Validation** - Syntax and semantic validation with error reporting\n- **🌍 Environment Management** - Comprehensive .env file support and variable expansion\n- **🧪 Full Test Coverage** - 33 passing tests across integration and unit test suites\n\n### 🎯 **MCP Tools Available**\n1. **`list_recipes`** - List all available recipes in the justfile\n2. **`run_recipe`** - Execute a specific recipe with optional arguments  \n3. **`get_recipe_info`** - Get detailed information about a specific recipe\n4. **`validate_justfile`** - Validate the justfile for syntax and semantic errors\n\n## 🏃 **Quick Start**\n\n### Installation\n\nChoose your preferred installation method:\n\n#### npm (JavaScript/TypeScript)\n```bash\n# Install globally\nnpm install -g just-mcp\n\n# Or use with npx (no installation required)\nnpx just-mcp --stdio\n```\n\n#### pip (Python)\n```bash\n# Install with pip\npip install just-mcp\n\n# Or use with uvx (recommended)\nuvx just-mcp --stdio\n```\n\n#### Cargo (Rust)\n```bash\n# Install from crates.io\ncargo install just-mcp\n\n# Or build from source\ngit clone https://github.com/promptexecution/just-mcp\ncd just-mcp\ncargo build --release\n```\n\n#### pkgx (pkgxdev)\n```bash\npkgx just-mcp --stdio\n```\n\n`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.\n\n#### Using Docker\n```bash\n# Pull the latest image from GitHub Container Registry\ndocker pull ghcr.io/promptexecution/just-mcp:latest\n\n# Run with Docker\ndocker run --rm -v $(pwd):/workspace ghcr.io/promptexecution/just-mcp:latest --stdio\n\n# Build locally\ndocker build -t just-mcp:local .\ndocker run --rm -v $(pwd):/workspace just-mcp:local --stdio\n```\n\nAvailable Docker image tags:\n- `latest` - Latest stable release\n- `X.Y.Z` - Specific version (e.g., `0.1.0`)\n- `X.Y` - Latest patch version (e.g., `0.1`)\n- `X` - Latest minor version (e.g., `0`)\n\n### Claude Desktop Integration\n\n#### Using npm/npx\nAdd to your Claude Desktop MCP configuration:\n\n#### Using Binary\n```json\n{\n  \"mcpServers\": {\n    \"just-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"just-mcp\", \"--stdio\"]\n    }\n  }\n}\n```\n\n#### Using pip/uvx\n```json\n{\n  \"mcpServers\": {\n    \"just-mcp\": {\n      \"command\": \"uvx\",\n      \"args\": [\"just-mcp\", \"--stdio\"]\n    }\n  }\n}\n```\n\n#### Using cargo or manual install\n```json\n{\n  \"mcpServers\": {\n    \"just-mcp\": {\n      \"command\": \"/path/to/just-mcp\",\n      \"args\": [\"--stdio\"]\n    }\n  }\n}\n```\n\n#### Using Docker\n```json\n{\n  \"mcpServers\": {\n    \"just-mcp\": {\n      \"command\": \"docker\",\n      \"args\": [\n        \"run\",\n        \"--rm\",\n        \"-i\",\n        \"-v\",\n        \"${workspaceFolder}:/workspace\",\n        \"ghcr.io/promptexecution/just-mcp:latest\",\n        \"--stdio\"\n      ]\n    }\n  }\n}\n```\n\n### Usage Examples\n```bash\n# Run as MCP server\njust-mcp --stdio\n\n# Run in specific directory  \njust-mcp --directory /path/to/project --stdio\n\n# Using Docker\ndocker run --rm -v $(pwd):/workspace ghcr.io/promptexecution/just-mcp:latest --stdio\n```\n\n## 🧪 **Testing**\n\n### Comprehensive Test Suite\n```bash\n# Run all tests (33 tests)\ncargo test\n\n# Run specific test suites\ncargo test --test basic_mcp_test      # Protocol compliance testing\ncargo test --test mcp_integration_working  # SDK integration testing\n```\n\n### Test Architecture\n- **`basic_mcp_test.rs`** - Direct protocol compliance testing using raw JSON-RPC\n- **`mcp_integration_working.rs`** - Type-safe SDK integration testing with rmcp client\n- **Unit tests** - 25+ tests covering parser, executor, validator, and environment modules\n\n## 📚 **Architecture**\n\n### Project Structure\n```\njust-mcp/\n├── src/main.rs              # CLI binary\n├── just-mcp-lib/           # Core library\n│   ├── parser.rs           # Justfile parsing\n│   ├── executor.rs         # Recipe execution  \n│   ├── validator.rs        # Validation logic\n│   ├── environment.rs      # Environment management\n│   └── mcp_server.rs       # MCP protocol implementation\n├── tests/                  # Integration tests\n└── justfile               # Demo recipes\n```\n\n### Tech Stack\n- **Rust 1.82+** with async/await support\n- **rmcp 0.3.0** - Official MCP SDK for Rust\n- **serde/serde_json** - JSON serialization  \n- **snafu** - Structured error handling\n- **tokio** - Async runtime\n\n## 🔄 **Development Roadmap**\n\n### 🎯 **Next Priority Tasks** (Remaining 33%)\n1. **LSP-Style Completion System** - Intelligent autocompletion for recipes and parameters\n2. **Enhanced Diagnostics** - Advanced syntax error reporting and suggestions  \n3. **Virtual File System** - Support for stdin, remote sources, and in-memory buffers\n4. **Release Preparation** - Documentation, CI/CD, and crate publication\n\n### 🚀 **Future Enhancements**\n- Plugin system for custom recipe types\n- Integration with other build tools\n- Performance optimizations for large justfiles\n- Advanced dependency visualization\n\n## 📖 **Usage Patterns**\n\n### Recipe Execution\n```javascript\n// List available recipes\nawait client.callTool(\"list_recipes\", {});\n\n// Execute recipe with parameters  \nawait client.callTool(\"run_recipe\", {\n  \"recipe_name\": \"build\",\n  \"args\": \"[\\\"--release\\\"]\"\n});\n\n// Get recipe information\nawait client.callTool(\"get_recipe_info\", {\n  \"recipe_name\": \"test\"\n});\n```\n\n### Validation\n```javascript\n// Validate justfile\nawait client.callTool(\"validate_justfile\", {\n  \"justfile_path\": \"./custom.justfile\"  \n});\n```\n\n## 🤝 **Contributing**\n\nThis project follows the [_b00t_ development methodology](AGENTS.md):\n- **TDD Approach** - Tests first, implementation second\n- **Feature Branches** - Never work directly on main branch\n- **Structured Errors** - Use snafu for error management\n- **Git Workflow** - Clean commits with descriptive messages\n\n### Development Commands\n```bash\njust build    # Build the project\njust test     # Run tests  \njust server   # Start MCP server\njust clean    # Clean build artifacts\n```\n\n## 📄 **License**\n\nThis project is licensed under [LICENSE](LICENSE).\n\n## 🚀 **Release Setup & CI/CD**\n\n### ✅ **Completed Setup**\n\n#### **Cocogitto & Conventional Commits**\n- Installed cocogitto for conventional commit enforcement\n- Configured `cog.toml` with proper commit types and changelog settings\n- Set up git hooks for commit message linting (`commit-msg`) and pre-push testing\n\n#### **GitHub Actions CI/CD**\n- **CI Pipeline** (`ci.yml`): Multi-platform testing (Ubuntu, Windows, macOS), formatting, clippy, commit linting\n- **Release Pipeline** (`release.yml`): Automated versioning, changelog generation, GitHub releases, and crates.io publishing\n- **Binary Builds** (`build-binaries.yml`): Cross-platform binary compilation for npm and pip packages\n- **Container Pipeline** (`container.yaml`): Multi-platform Docker image builds (linux/amd64, linux/arm64) pushed to GitHub Container Registry\n\n#### **Docker Images**\n- Multi-platform builds for `linux/amd64` and `linux/arm64`\n- Minimal image size using static musl binaries and scratch base image\n- Automatic tagging with semantic versioning (major, major.minor, major.minor.patch, latest)\n- Published to GitHub Container Registry (ghcr.io)\n- Integrated with release workflow for automatic deployment\n\n#### **Crates.io Preparation**\n- Updated both `Cargo.toml` files with complete metadata (description, keywords, categories, license, etc.)\n- Added proper exclusions for development-only files\n- Verified MIT license is in place\n\n#### **Documentation & Structure**\n- README.md is production-ready with installation and usage instructions\n- Created initial `CHANGELOG.md` for release tracking\n- Updated `.gitignore` with Rust-specific entries\n\n### 🚀 **Production Deployment**\n\n#### **Development Workflow:**\n- All commits must follow conventional commit format (enforced by git hooks)\n- Use `feat:`, `fix:`, `docs:`, etc. prefixes for automatic versioning\n- Push to `main` branch triggers automated releases and crates.io publishing\n- Library tests pass ✅ (25/25) with comprehensive test coverage\n\n#### **Release Process:**\n- **Automated Versioning**: Cocogitto analyzes commit messages for semantic versioning\n- **GitHub Releases**: Automatic changelog generation and GitHub release creation\n- **Binary Distribution**: Pre-built binaries for Linux (x86_64, aarch64), macOS (x86_64, aarch64), and Windows (x86_64)\n- **Crates.io Publishing**: Library crate (`just-mcp-lib`) publishes first, then binary crate (`just-mcp`)\n- **npm Publishing**: Wrapper package for easy Node.js/TypeScript integration\n- **PyPI Publishing**: Python wrapper package for pip/uvx installation\n- **CI/CD Pipeline**: Multi-platform testing (Ubuntu, Windows, macOS) with formatting and clippy checks\n\n#### **Installation Methods:**\n```bash\n# npm (JavaScript/TypeScript ecosystems)\nnpm install -g just-mcp\n# or\nnpx just-mcp --stdio\n\n# pip (Python ecosystems)\npip install just-mcp\n# or\nuvx just-mcp --stdio\n\n# cargo (Rust ecosystem)\ncargo install just-mcp\n\n# Download pre-built binaries\nwget https://github.com/promptexecution/just-mcp/releases/latest/download/just-mcp-x86_64-unknown-linux-gnu.tar.gz\n# Or use Docker\ndocker pull ghcr.io/promptexecution/just-mcp:latest\n\n# Or download from GitHub releases\nwget https://github.com/promptexecution/just-mcp/releases/latest/download/just-mcp\n```\n\n## 🔗 **Related Projects**\n\n- [Just](https://github.com/casey/just) - The command runner this integrates with\n- [Model Context Protocol](https://modelcontextprotocol.io/) - The protocol specification\n- [rmcp](https://github.com/modelcontextprotocol/rust-sdk) - Official Rust MCP SDK\n\n### **Friends of just-mcp**\n\n- [just-vscode](https://github.com/promptexecution/just-vscode) - VSCode extension with LSP integration for enhanced Just authoring\n- [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 hook\n",
  "bytes": 14150,
  "sha": "234d92c47476ea3af0a2c93fc1d1e5247f50d4b9ab0fb02408bce7cf27f3925e",
  "repo_slug": "promptexecution/just-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_promptexecution_just_mcp_cf5654a0/readme"
}