just-mcp

Transform justfiles into AI-accessible automation tools through the Model Context Protocol

just-mcp bridges justfiles and Coding Agents by exposing justfile recipes as dynamically discoverable MCP tools.

This enables AI assistants to understand, explore, and execute a project's common development workflows similar to how a human would.

Quick Start

1. Install just-mcp

# Using cargo-binstall (fastest - downloads pre-built binary)
cargo binstall --git https://github.com/toolprint/just-mcp just-mcp

# Or download latest release
curl -L https://github.com/toolprint/just-mcp/releases/latest/download/just-mcp-$(uname -m)-$(uname -s).tar.gz | tar xz
sudo mv just-mcp /usr/local/bin/

2. Configure your Agent (see MCP Client Setup below)

3. Use the Slash Command:

/just:do-it build the project

It will find the appropriate justfile task to run as an MCP Tool.

That's it. Your AI can now use your justfile tasks.

MCP Client Setup

Claude Code

claude mcp add -s user -t stdio just -- just-mcp

Or manually add to ~/.claude.json:

{
  "mcpServers": {
    "just": {
      "type": "stdio", 
      "command": "just-mcp"
    }
  }
}

Verification: Start a new session and check /mcp for 'just' and view details to see how many tools loaded.

Claude Desktop

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "just": {
      "command": "just-mcp", 
      "args": ["--watch-dir", "/Users/username/workspace/your-project-dir"],
    }
  }
}

Verification: Restart Claude Desktop, check the settings button for custom connection tools.

Cline (VS Code Extension)

1. Click Cline icon → MCP Servers → Configure MCP Servers
2. Add configuration:

{
  "mcpServers": {
    "just": {
      "disabled": false,
      "timeout": 60,
      "type": "stdio",
      "command": "just-mcp",
      "args": [
        "-w",
        "/Users/username/your-project-dir"
      ]
    }
}

Verification: Look for MCP server status in Cline's interface.

NOTE: Since cline runs outside of your current project working directory you MUST specify the watch-dir or use the admin tools at runtime to ask Cline to switch the watch-dir for you.

Key Features

🔍 Smart Justfile Discovery

• Real-time monitoring with hot reloading
• Defaults to use the current project root directory to look for your justfile
• Dynamic tool generation from your tasks

📝 Advanced Parsing

• AST-based parser using Tree-sitter for complete syntax support
• Parameter documentation from comments: # {{param}}: description
• Three-tier fallback: AST → CLI → Regex for maximum compatibility

🛡️ Security First

• Input validation prevents command injection
• Configurable timeouts and resource limits
• Directory whitelisting and parameter sanitization

⚙️ Admin Tools

• admin_sync: Refresh tool registry
• admin_create_task: AI-assisted task creation with backup

🔍 Vector Search (Optional)

• Offline semantic search with local embeddings (no API keys)
• Natural language queries: "deploy to production"
• Cross-project discovery of similar automation patterns
• See Vector Search docs

Example Workflow

Given this justfile:

# Deploy the application
deploy env="prod":
  echo "Deploying to {{env}}"
  ./deploy.sh {{env}}

# Run tests with coverage
test coverage="false":
  cargo test {{if coverage == "true" { "--coverage" } else { "" }}}

Your AI assistant can:

• Discover: "What tasks are available?"
• Execute: "Deploy to staging" → runs deploy env="staging"
• Understand: Sees parameters, descriptions, and dependencies

Installation Options

Pre-built Binaries (Recommended)

Download from GitHub Releases:

# Linux x86_64
curl -L https://github.com/toolprint/just-mcp/releases/latest/download/just-mcp-x86_64-unknown-linux-gnu.tar.gz | tar xz

# Linux ARM64  
curl -L https://github.com/toolprint/just-mcp/releases/latest/download/just-mcp-aarch64-unknown-linux-gnu.tar.gz | tar xz

# macOS (Universal - works on Intel and Apple Silicon)
curl -L https://github.com/toolprint/just-mcp/releases/latest/download/just-mcp-universal2-apple-darwin.tar.gz | tar xz

From Source

git clone https://github.com/toolprint/just-mcp.git
cd just-mcp
just quickstart  # Complete setup + install

Or manually:

cargo install --path . --features all  # All features including vector search

Development

Setup

just quickstart     # Complete setup for new developers
just dev-setup      # Comprehensive development environment

Workspace Structure

• ./ - Main MCP server
• dev-tools/ - Performance analysis utilities

Common Commands

just build              # Build main server  
just build-dev-tools    # Build development utilities
just test               # Run tests
just check              # Format, lint, test (pre-commit)

Multi-Project Example

Monitor multiple projects with custom names:

just-mcp \
  --watch-dir ~/projects/api:backend \
  --watch-dir ~/projects/web:frontend \
  --watch-dir ~/infrastructure:infra

Tools will be available as:

• just_deploy@backend
• just_build@frontend
• just_apply@infra

Documentation

• Configuration Guide - Detailed setup for all MCP clients
• Vector Search - Semantic search with natural language
• Troubleshooting - Common issues and solutions
• Contributing - Development workflow and guidelines

Architecture

Justfile Watcher → AST Parser → Tool Registry → MCP Server → AI Assistant
     ↓                ↓             ↓            ↓
File Changes → Dynamic Updates → Real-time → Task Execution

Key Design Principles:

• Async-first: Tokio-based for concurrent operations
• Security-focused: All inputs validated, resources limited
• Hot-reload: File changes trigger automatic tool updates
• Zero-config: Works with existing justfiles

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Quick steps:

1. just quickstart - Set up development environment
2. Make your changes and add tests
3. just check - Ensure code quality
4. Submit a Pull Request

License

MIT License - see LICENSE for details.

Acknowledgments

• just - The command runner that inspired this project
• Model Context Protocol - Enabling AI-tool communication
• Anthropic - For developing the MCP standard

---

Need help? Check troubleshooting or open an issue on GitHub.