{"id":31810885,"url":"https://github.com/toolprint/just-mcp","last_synced_at":"2025-10-11T06:17:35.191Z","repository":{"id":305405401,"uuid":"1015095326","full_name":"toolprint/just-mcp","owner":"toolprint","description":"Share the same project justfile tasks with your AI Coding Agent.","archived":false,"fork":false,"pushed_at":"2025-08-18T00:37:45.000Z","size":235,"stargazers_count":9,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-18T02:27:39.294Z","etag":null,"topics":["agents","claude-code","gemini-cli","just","justfile","llm","mcp","mcp-server","vibe-coding"],"latest_commit_sha":null,"homepage":"https://toolprint.ai/","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/toolprint.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-07T02:07:17.000Z","updated_at":"2025-08-18T00:21:33.000Z","dependencies_parsed_at":"2025-07-20T00:05:26.189Z","dependency_job_id":null,"html_url":"https://github.com/toolprint/just-mcp","commit_stats":null,"previous_names":["toolprint/just-mcp"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/toolprint/just-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toolprint%2Fjust-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toolprint%2Fjust-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toolprint%2Fjust-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toolprint%2Fjust-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/toolprint","download_url":"https://codeload.github.com/toolprint/just-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toolprint%2Fjust-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279006450,"owners_count":26084107,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-11T02:00:06.511Z","response_time":55,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agents","claude-code","gemini-cli","just","justfile","llm","mcp","mcp-server","vibe-coding"],"created_at":"2025-10-11T06:17:27.084Z","updated_at":"2025-10-11T06:17:35.182Z","avatar_url":"https://github.com/toolprint.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# just-mcp\n\n[![CI](https://github.com/onegrep/just-mcp/actions/workflows/dagger-ci.yml/badge.svg)](https://github.com/onegrep/just-mcp/actions/workflows/dagger-ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Rust](https://img.shields.io/badge/rust-1.88+-blue.svg)](https://www.rust-lang.org)\n[![MCP](https://img.shields.io/badge/MCP-1.0-green.svg)](https://modelcontextprotocol.io/)\n[![Vector Search](https://img.shields.io/badge/Vector%20Search-Optional-orange.svg)](https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2)\n\n\u003e Transform justfiles into AI-accessible automation tools through the Model Context Protocol\n\n**just-mcp** bridges [justfiles](https://just.systems/) and Coding Agents by exposing justfile recipes as dynamically discoverable MCP tools.\n\nThis enables AI assistants to understand, explore, and execute a project's common development workflows similar to how a human would.\n\n\u003cimg width=\"676\" height=\"331\" alt=\"just-mcp\" src=\"https://github.com/user-attachments/assets/c1222e9b-e440-4e7e-ab8c-629e727d1849\" /\u003e\n\n## Quick Start\n\n**1. Install just-mcp**\n```bash\n# Using cargo-binstall (fastest - downloads pre-built binary)\ncargo binstall --git https://github.com/toolprint/just-mcp just-mcp\n\n# Or download latest release\ncurl -L https://github.com/toolprint/just-mcp/releases/latest/download/just-mcp-$(uname -m)-$(uname -s).tar.gz | tar xz\nsudo mv just-mcp /usr/local/bin/\n```\n\n**2. Configure your Agent** (see [MCP Client Setup](#mcp-client-setup) below)\n\n**3. Use the Slash Command**:\n\n```bash\n/just:do-it build the project\n```\n\nIt will find the appropriate justfile task to run as an MCP Tool.\n\nThat's it. Your AI can now use your justfile tasks.\n\n## MCP Client Setup\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eClaude Code\u003c/strong\u003e\u003c/summary\u003e\n\n```bash\nclaude mcp add -s user -t stdio just -- just-mcp\n```\n\nOr manually add to `~/.claude.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"just\": {\n      \"type\": \"stdio\", \n      \"command\": \"just-mcp\"\n    }\n  }\n}\n```\n\n**Verification**: Start a new session and check /mcp for 'just' and view details to see how many tools loaded.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eClaude Desktop\u003c/strong\u003e\u003c/summary\u003e\n\n**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n**Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"just\": {\n      \"command\": \"just-mcp\", \n      \"args\": [\"--watch-dir\", \"/Users/username/workspace/your-project-dir\"],\n    }\n  }\n}\n```\n\n**Verification**: Restart Claude Desktop, check the settings button for custom connection tools.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eCline (VS Code Extension)\u003c/strong\u003e\u003c/summary\u003e\n\n1. Click Cline icon → **MCP Servers** → **Configure MCP Servers**\n2. Add configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"just\": {\n      \"disabled\": false,\n      \"timeout\": 60,\n      \"type\": \"stdio\",\n      \"command\": \"just-mcp\",\n      \"args\": [\n        \"-w\",\n        \"/Users/username/your-project-dir\"\n      ]\n    }\n}\n```\n\n**Verification**: Look for MCP server status in Cline's interface.\n\n**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.\n\n\u003c/details\u003e\n\n## Key Features\n\n### 🔍 **Smart Justfile Discovery**\n- Real-time monitoring with hot reloading\n- Defaults to use the current project root directory to look for your justfile\n- Dynamic tool generation from your tasks\n\n### 📝 **Advanced Parsing**\n- AST-based parser using Tree-sitter for complete syntax support\n- Parameter documentation from comments: `# {{param}}: description`\n- Three-tier fallback: AST → CLI → Regex for maximum compatibility\n\n### 🛡️ **Security First**\n- Input validation prevents command injection\n- Configurable timeouts and resource limits\n- Directory whitelisting and parameter sanitization\n\n### ⚙️ **Admin Tools**\n- `admin_sync`: Refresh tool registry\n- `admin_create_task`: AI-assisted task creation with backup\n\n### 🔍 **Vector Search** *(Optional)*\n- **Offline semantic search** with local embeddings (no API keys)\n- Natural language queries: *\"deploy to production\"*\n- Cross-project discovery of similar automation patterns\n- See [Vector Search docs](docs/features/vector-search.md)\n\n## Example Workflow\n\nGiven this justfile:\n```just\n# Deploy the application\ndeploy env=\"prod\":\n  echo \"Deploying to {{env}}\"\n  ./deploy.sh {{env}}\n\n# Run tests with coverage\ntest coverage=\"false\":\n  cargo test {{if coverage == \"true\" { \"--coverage\" } else { \"\" }}}\n```\n\nYour AI assistant can:\n- **Discover**: \"What tasks are available?\"\n- **Execute**: \"Deploy to staging\" → runs `deploy env=\"staging\"`\n- **Understand**: Sees parameters, descriptions, and dependencies\n\n## Installation Options\n\n### Pre-built Binaries (Recommended)\n\nDownload from [GitHub Releases](https://github.com/toolprint/just-mcp/releases/latest):\n\n```bash\n# Linux x86_64\ncurl -L https://github.com/toolprint/just-mcp/releases/latest/download/just-mcp-x86_64-unknown-linux-gnu.tar.gz | tar xz\n\n# Linux ARM64  \ncurl -L https://github.com/toolprint/just-mcp/releases/latest/download/just-mcp-aarch64-unknown-linux-gnu.tar.gz | tar xz\n\n# macOS (Universal - works on Intel and Apple Silicon)\ncurl -L https://github.com/toolprint/just-mcp/releases/latest/download/just-mcp-universal2-apple-darwin.tar.gz | tar xz\n```\n\n### From Source\n\n```bash\ngit clone https://github.com/toolprint/just-mcp.git\ncd just-mcp\njust quickstart  # Complete setup + install\n```\n\nOr manually:\n```bash\ncargo install --path . --features all  # All features including vector search\n```\n\n## Development\n\n### Setup\n```bash\njust quickstart     # Complete setup for new developers\njust dev-setup      # Comprehensive development environment\n```\n\n### Workspace Structure\n- `./` - Main MCP server\n- `dev-tools/` - Performance analysis utilities\n\n### Common Commands\n```bash\njust build              # Build main server  \njust build-dev-tools    # Build development utilities\njust test               # Run tests\njust check              # Format, lint, test (pre-commit)\n```\n\n## Multi-Project Example\n\nMonitor multiple projects with custom names:\n\n```bash\njust-mcp \\\n  --watch-dir ~/projects/api:backend \\\n  --watch-dir ~/projects/web:frontend \\\n  --watch-dir ~/infrastructure:infra\n```\n\nTools will be available as:\n- `just_deploy@backend`\n- `just_build@frontend`  \n- `just_apply@infra`\n\n## Documentation\n\n- **[Configuration Guide](docs/CONFIGURATION.md)** - Detailed setup for all MCP clients\n- **[Vector Search](docs/features/vector-search.md)** - Semantic search with natural language\n- **[Troubleshooting](docs/troubleshooting.md)** - Common issues and solutions\n- **[Contributing](CONTRIBUTING.md)** - Development workflow and guidelines\n\n## Architecture\n\n```\nJustfile Watcher → AST Parser → Tool Registry → MCP Server → AI Assistant\n     ↓                ↓             ↓            ↓\nFile Changes → Dynamic Updates → Real-time → Task Execution\n```\n\n**Key Design Principles:**\n- **Async-first**: Tokio-based for concurrent operations\n- **Security-focused**: All inputs validated, resources limited\n- **Hot-reload**: File changes trigger automatic tool updates\n- **Zero-config**: Works with existing justfiles\n\n## Contributing\n\nWe welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\nQuick steps:\n1. `just quickstart` - Set up development environment\n2. Make your changes and add tests  \n3. `just check` - Ensure code quality\n4. Submit a Pull Request\n\n## License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n## Acknowledgments\n\n- [just](https://just.systems/) - The command runner that inspired this project\n- [Model Context Protocol](https://modelcontextprotocol.io/) - Enabling AI-tool communication\n- [Anthropic](https://anthropic.com/) - For developing the MCP standard\n\n---\n\n**Need help?** Check [troubleshooting](docs/troubleshooting.md) or open an issue on GitHub.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftoolprint%2Fjust-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftoolprint%2Fjust-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftoolprint%2Fjust-mcp/lists"}