Devpipe MCP Server

# Devpipe MCP Server A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that enables AI assistants to interact with [devpipe](https://github.com/drewkhoury/devpipe) - a fast, local pipeline runner for development workflows. ## Features This MCP server provides AI assistants with the ability to: - 📋 **List and analyze tasks** from devpipe configurations (with verbose stats) - 🚀 **Run pipelines** with full control over execution flags - ✅ **Validate configurations** before running - 📊 **Access run results** and metrics (JUnit, SARIF) - 🔍 **Debug failures** by reading task logs - 💡 **Suggest optimizations** for pipeline configurations - 🛡️ **Review security findings** from SARIF reports - 🔧 **Auto-detect technologies** and suggest missing tasks - ⚡ **Generate task configurations** from templates - 📝 **Create complete configs** from scratch - 🔄 **Generate CI/CD configs** (GitHub Actions, GitLab CI) ## Requirements - **Node.js** 18 or higher - devpipe v0.2.0 or later installed and accessible in PATH ```bash brew install drewkhoury/tap/devpipe ``` **Note:** This MCP requires devpipe v0.2.0+ which uses outputType/outputPath fields (renamed from metricsFormat/metricsPath). ## Installation ### Option 1: Install from npm (recommended) ```bash npm install -g devpipe-mcp ``` ### Option 2: Install from source ```bash git clone https://github.com/drewkhoury/devpipe-mcp.git cd devpipe-mcp npm install npm run build npm link ``` ## Configuration Add to your MCP configuration file: - **Windsurf/Cascade**: `~/.codeium/windsurf/mcp_config.json` - **Claude Desktop**: `~/Library/Application Support/Claude/claude_desktop_config.json` ```json { "mcpServers": { "devpipe": { "command": "npx", "args": [ "-y", "devpipe-mcp@latest" ] } } } ``` ### For Other MCP Clients The server runs on stdio, so you can connect any MCP client using: ```bash devpipe-mcp ``` ## Usage Once configured, you can interact with devpipe through your AI assistant using **natural language**. The AI will automatically translate your requests into the appropriate tool calls. > 📖 **[Complete Prompting Guide](./docs/PROMPTING_GUIDE.md)** - Learn all the ways to effectively prompt the MCP server ### 🎯 How to Prompt **The key is to specify which project you want to work with:** - **"this project"** or **"this repo"** - Uses your current workspace - **Project name** - e.g., "the devpipe project", "my go-app" - **Absolute path** - e.g., "/Users/you/projects/my-app" ### List Tasks ``` "Show me all the tasks in this project" "What tasks are defined in /Users/you/projects/my-app/config.toml?" "List tasks from the devpipe project" ``` ### Run Pipeline ``` "Run devpipe in this project" "Run the pipeline for /Users/you/projects/my-app" "Run only the lint and test tasks in this repo" "Execute devpipe in dry-run mode for the go-app project" ``` ### Validate Configuration ``` "Validate my devpipe config" "Check if config.toml is valid" ``` ### Debug Failures ``` "Why did the lint task fail?" "Show me the logs for the build task" "What went wrong in the last run?" ``` ### Analyze and Optimize ``` "Analyze my pipeline configuration" "Suggest optimizations for my devpipe setup" "How can I make my pipeline faster?" ``` ### Create Tasks ``` "Create a devpipe task for running Go tests" "Help me add a Python linting task" "Generate a task configuration for ESLint" ``` ### Bootstrap New Projects ``` "Create a devpipe config for this project" "Analyze the project at /Users/you/projects/new-app" "What technologies are in this repo?" "Generate a config for /path/to/project" ``` ### Working with Multiple Projects ``` "Analyze /Users/you/projects/project-a" "Run devpipe in /Users/you/projects/project-b" "Compare tasks between this project and /Users/you/projects/other-project" ``` **Pro Tip:** You don't need to configure anything special - just tell the AI which project you want to work with in your prompt! ### Generate CI/CD ``` "Generate a GitHub Actions workflow for devpipe" "Create a GitLab CI config from my devpipe setup" ``` ### Security Review ``` "Review the security findings from my last run" "What security issues were found?" "Analyze SARIF results" ``` ## MCP Tools The server provides the following tools: ### `list_tasks` Parse and list all tasks from a config.toml file. **Parameters:** - `config` (optional): Path to config.toml file **Example:** ```json { "config": "./config.toml" } ``` ### `run_pipeline` Execute devpipe with specified flags. **Parameters:** - `config` (optional): Path to config.toml - `only` (optional): Array of task IDs to run - `skip` (optional): Array of task IDs to skip - `since` (optional): Git reference for change-based runs - `fixType` (optional): `auto`, `helper`, or `none` - `ui` (optional): `basic` or `full` - `dashboard` (optional): Show dashboard view - `failFast` (optional): Stop on first failure - `fast` (optional): Skip slow tasks - `ignoreWatchPaths` (optional): Ignore watchPaths and run all tasks - `dryRun` (optional): Show what would run - `verbose` (optional): Verbose output - `noColor` (optional): Disable colors **Example:** ```json { "only": ["lint", "test"], "fast": true, "failFast": true, "ignoreWatchPaths": true } ``` ### `validate_config` Validate devpipe configuration files. **Parameters:** - `configs` (optional): Array of config file paths **Example:** ```json { "configs": ["config.toml", "config.prod.toml"] } ``` ### `get_last_run` Get results from the most recent pipeline run. **Parameters:** - `config` (optional): Path to config.toml ### `view_run_logs` Read logs from a specific task or the entire pipeline. **Parameters:** - `taskId` (optional): Task ID to view logs for - `config` (optional): Path to config.toml **Example:** ```json { "taskId": "lint" } ``` ### `parse_metrics` Parse JUnit or SARIF metrics files. **Parameters:** - `metricsPath` (required): Path to metrics file - `format` (required): `junit` or `sarif` **Example:** ```json { "metricsPath": ".devpipe/runs/latest/metrics.sarif", "format": "sarif" } ``` ### `get_dashboard_data` Extract aggregated data from summary.json. **Parameters:** - `config` (optional): Path to config.toml ### `check_devpipe` Check if devpipe is installed and get version info. ### `list_tasks_verbose` List tasks using `devpipe list --verbose` command with execution statistics. **Parameters:** - `config` (optional): Path to config.toml file **Example:** ```json { "config": "./config.toml" } ``` **Output:** Shows task table with average execution times and statistics. ### `analyze_project` Analyze project directory to detect technologies and suggest missing tasks. **Parameters:** - `projectPath` (optional): Path to project directory (defaults to current) **Example:** ```json { "projectPath": "/path/to/project" } ``` **Output:** ```json { "projectPath": "/path/to/project", "detectedTechnologies": ["Go", "Docker"], "suggestedTasks": [ { "technology": "Go", "taskType": "check-format", "reason": "go fmt for formatting" }, { "technology": "Go", "taskType": "check-lint", "reason": "golangci-lint for linting" } ], "summary": "Found 2 technologies with 5 suggested tasks" } ``` ### `generate_task` Generate task configuration from template for a specific technology or phase header. **Parameters:** - `technology` (required): Technology name (e.g., "Go", "Python", "Node.js", "TypeScript", "Rust") or "phase" for phase headers - `taskType` (required): Task type (e.g., "check-format", "check-lint", "test-unit", "build") or phase name - `taskId` (optional): Custom task ID for regular tasks, or description for phase headers **Example (Regular Task):** ```json { "technology": "Go", "taskType": "check-lint", "taskId": "golangci-lint" } ``` **Output:** ```toml [tasks.golangci-lint] name = "Golang CI Lint" desc = "Runs comprehensive linting on Go code" type = "check" command = "golangci-lint run" fixType = "auto" fixCommand = "golangci-lint run --fix" ``` **Example (Phase Header):** ```json { "technology": "phase", "taskType": "Validation", "taskId": "Static analysis and tests" } ``` **Output:** ```toml [tasks.phase-validation] name = "Validation" desc = "Static analysis and tests" ``` **Note:** Phase headers have **no required fields** - they're organizational markers. Common practice is to include `name` or `desc` (or both), but neither is strictly required. **Supported Technologies:** - **Go**: check-format, check-lint, check-static, test-unit, build - **Python**: check-format, check-lint, check-types, test-unit - **Node.js**: check-lint, test-unit, build - **TypeScript**: check-types - **phase**: Creates phase headers (organizational markers, no command/type) ### `create_config` Create a complete config.toml file from scratch with auto-detected tasks. **Parameters:** - `projectPath` (optional): Path to project directory (defaults to current) - `includeDefaults` (optional): Include [defaults] section (default: true) - `autoDetect` (optional): Auto-detect technologies and generate tasks (default: true) **Example:** ```json { "projectPath": "/path/to/project", "includeDefaults": true, "autoDetect": true } ``` **Output:** Complete config.toml with: - Defaults section (outputRoot, fastThreshold=300s, animationRefreshMs=500ms, git settings) - Task defaults (enabled, workdir) - Auto-detected tasks organized by phase - Ready-to-use TOML configuration compatible with devpipe v0.1.0+ **Use Case:** Bootstrap a new project with devpipe configuration. **Note:** Generated configs use devpipe v0.1.0 defaults (fastThreshold=300s, not 5000ms). ### `get_pipeline_health` Calculate overall pipeline health score with trend analysis, failure rates, and performance metrics. Returns health score (0-100), issues, warnings, and recommendations. ### `compare_runs` Compare two pipeline runs to identify changes in failures, performance, and metrics. **Parameters:** - `run1` (required): First run ID (e.g., `2024-12-07_20-00-00`) or `latest` - `run2` (required): Second run ID or `previous` **Returns:** New failures, fixed tasks, performance changes, and detailed task comparisons. ### `predict_impact` Predict which tasks are likely to fail based on changed files and historical patterns. **Returns:** Risk scores per task, recommended tasks to run, and suggested devpipe command. **Risk scoring:** - WatchPaths matching (40 points) - Historical failure correlation (30 points) - Recent failure rate (30 points) ### `generate_ci_config` Generate CI/CD configuration file (GitHub Actions or GitLab CI) from devpipe config. **Parameters:** - `config` (optional): Path to config.toml file - `platform` (required): `github` or `gitlab` **Example:** ```json { "config": "./config.toml", "platform": "github" } ``` **Output (GitHub Actions):** ```yaml name: CI Pipeline on: push: branches: [ main, develop ] pull_request: branches: [ main ] jobs: devpipe: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Install devpipe run: | curl -L https://github.com/drewkhoury/devpipe/releases/latest/download/devpipe-linux-amd64 -o devpipe chmod +x devpipe sudo mv devpipe /usr/local/bin/ - name: Run devpipe run: devpipe --fail-fast - name: Upload results if: always() uses: actions/upload-artifact@v4 with: name: devpipe-results path: .devpipe/ ``` ## MCP Resources The server exposes these resources: - `devpipe://config` - Current config.toml contents - `devpipe://tasks` - All task definitions - `devpipe://last-run` - Most recent run results - `devpipe://summary` - Aggregated pipeline summary - `devpipe://schema` - JSON Schema for config.toml validation (fetched from official devpipe repo) - `devpipe://template-dashboard` - HTML template for dashboard reports (fetched from devpipe source) - `devpipe://template-ide` - HTML template for IDE-optimized views (fetched from devpipe source) - `devpipe://releases-latest` - Latest devpipe release notes (from GitHub releases) - `devpipe://releases-all` - Complete release history (from GitHub releases) - `devpipe://readme` - Complete devpipe documentation (from GitHub) - `devpipe://docs-configuration` - Official configuration guide (from GitHub) - `devpipe://docs-examples` - Example config.toml with all options (from GitHub) - `devpipe://docs-cli-reference` - CLI commands and flags reference (from GitHub) - `devpipe://docs-config-validation` - Configuration validation rules (from GitHub) - `devpipe://docs-features` - Complete features guide (from GitHub) - `devpipe://docs-project-root` - Project root configuration (from GitHub) - `devpipe://docs-safety-checks` - Safety checks documentation (from GitHub) - `devpipe://version-info` - Installed devpipe version and capabilities (from local binary) - `devpipe://available-commands` - All CLI commands and flags (from local binary) - `devpipe://git-status` - Current git repository status (from local git) - `devpipe://changed-files` - Files changed based on git mode (from local git) - `devpipe://task-history` - Historical task performance across all runs (from local runs) - `devpipe://metrics-summary` - Aggregated test and security metrics (from local runs) - `devpipe://watchpaths-analysis` - Analyze which tasks will run based on watchPaths (from local config + git) - `devpipe://recent-failures` - Recent task failures with error details and patterns (from local runs) - `devpipe://flakiness-report` - Flaky task detection with pass/fail patterns (from local runs) - `devpipe://performance-regressions` - Tasks that have gotten slower over time (from local runs) - `devpipe://change-correlation` - Correlate failures with recent commits and file changes (from local git + runs) ## MCP Prompts Pre-configured prompts for common workflows: ### `mcp-info` Get information about this MCP server version and devpipe compatibility. Shows supported field names, run structure, and upgrade guidance. ### `analyze-config` Analyze the devpipe configuration and suggest improvements. ### `debug-failure` Help debug why a specific task failed. **Arguments:** - `taskId` (required): The task that failed ### `optimize-pipeline` Suggest optimizations for the pipeline. ### `create-task` Help create a new task for a technology. **Arguments:** - `technology` (required): Technology name (e.g., "Go", "Python") - `taskType` (optional): `check`, `build`, or `test` ### `security-review` Review SARIF security findings and provide recommendations. ### `configure-metrics` Help configure JUnit, SARIF, or artifact metrics for a task. Provides guidance on proper metricsFormat and metricsPath configuration. ## Examples See [EXAMPLES.md](./EXAMPLES.md) for detailed usage examples and workflows. ### Quick Example ``` User: "Run my devpipe pipeline with fast mode" Assistant: *Uses run_pipeline tool with { "fast": true }* Result: Pipeline executes, skipping slow tasks ``` ## Development ### Building from Source ```bash git clone https://github.com/drewkhoury/devpipe-mcp.git cd devpipe-mcp npm install npm run build ``` ### Project Structure ``` devpipe-mcp/ ├── src/ │ ├── index.ts # Main MCP server │ ├── types.ts # Type definitions │ └── utils.ts # Utility functions ├── examples/ # Example configs ├── dist/ # Compiled output └── README.md ``` ### Watch Mode ```bash npm run watch ``` ## Troubleshooting ### devpipe not found If you get "devpipe not found" errors: ```bash # Install devpipe brew install drewkhoury/tap/devpipe # Verify installation devpipe --version ``` ### Config file not found The MCP server searches for `config.toml` in: 1. Current directory 2. Parent directories (up to root) You can also specify the config path explicitly in tool calls. ### Permission errors Ensure the MCP server has permission to: - Read config files - Execute devpipe commands - Access the `.devpipe` output directory ## Contributing Contributions are welcome! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines. ## License MIT License - see [LICENSE](./LICENSE) file for details. ## Related Projects - [devpipe](https://github.com/drewkhoury/devpipe) - The pipeline runner this MCP server integrates with - [Model Context Protocol](https://modelcontextprotocol.io) - The protocol specification ## Support - **Issues**: [GitHub Issues](https://github.com/drewkhoury/devpipe-mcp/issues) - **Discussions**: [GitHub Discussions](https://github.com/drewkhoury/devpipe-mcp/discussions) - **devpipe**: [devpipe GitHub](https://github.com/drewkhoury/devpipe) ## Changelog See [CHANGELOG.md](./CHANGELOG.md) for version history and changes.