# AWS CodePipeline MCP Server This is a Model Context Protocol (MCP) server that integrates with AWS CodePipeline, allowing you to manage your pipelines through Windsurf and Cascade. The server provides a standardized interface for interacting with AWS CodePipeline services. **Author:** Cuong T Nguyen ## Features - List all pipelines - Get pipeline state and detailed pipeline definitions - List pipeline executions - Approve or reject manual approval actions - Retry failed stages - Trigger pipeline executions - View pipeline execution logs - Stop pipeline executions - Tag pipeline resources - Create webhooks for automatic pipeline triggering - Get pipeline performance metrics ## Prerequisites - Node.js (v14 or later) - AWS account with CodePipeline access - AWS credentials with permissions for CodePipeline, CloudWatch, and IAM (for tagging) - Windsurf IDE with Cascade AI assistant ## Installation 1. Clone this repository: ```bash git clone https://github.com/cuongdev/mcp-codepipeline-server.git cd mcp-codepipeline-server ``` 2. Install dependencies: ```bash npm install ``` 3. Create a `.env` file based on the `.env.example` template: ```bash cp .env.example .env ``` 4. Update the `.env` file with your AWS credentials and configuration: ``` AWS_REGION=us-east-1 AWS_ACCESS_KEY_ID=your_access_key_id AWS_SECRET_ACCESS_KEY=your_secret_access_key PORT=3000 ``` > **Note**: For security, never commit your `.env` file to version control. ## Usage ### Build the project ```bash npm run build ``` ### Start the server ```bash npm start ``` For development with auto-restart: ```bash npm run dev ``` ## Integration with Windsurf This MCP server is designed to work with Windsurf, allowing Cascade to interact with AWS CodePipeline through natural language requests. ### Setup Steps 1. Make sure the server is running: ```bash npm start ``` 2. Add the server configuration to your Windsurf MCP config file at `~/.codeium/windsurf/mcp_config.json`: ```json { "mcpServers": { "codepipeline": { "command": "npx", "args": [ "-y", "path/to/mcp-codepipeline-server/dist/index.js" ], "env": { "AWS_REGION": "us-east-1", "AWS_ACCESS_KEY_ID": "your_access_key_id", "AWS_SECRET_ACCESS_KEY": "your_secret_access_key" } } } } ``` 3. Create the directory if it doesn't exist: ```bash mkdir -p ~/.codeium/windsurf touch ~/.codeium/windsurf/mcp_config.json ``` 4. Restart Windsurf to load the new MCP server configuration ### Using with Cascade Once configured, you can interact with AWS CodePipeline using natural language in Windsurf. For example: - "List all my CodePipeline pipelines" - "Show me the current state of my 'production-deploy' pipeline" - "Trigger the 'test-build' pipeline" - "Get metrics for my 'data-processing' pipeline" - "Create a webhook for my 'frontend-deploy' pipeline" Cascade will translate these requests into the appropriate MCP tool calls. ## MCP Tools ### Core Pipeline Management | Tool Name | Description | Parameters | |-----------|-------------|------------| | `list_pipelines` | List all CodePipeline pipelines | None | | `get_pipeline_state` | Get the state of a specific pipeline | `pipelineName`: Name of the pipeline | | `list_pipeline_executions` | List executions for a specific pipeline | `pipelineName`: Name of the pipeline | | `trigger_pipeline` | Trigger a pipeline execution | `pipelineName`: Name of the pipeline | | `stop_pipeline_execution` | Stop a pipeline execution | `pipelineName`: Name of the pipeline
`executionId`: Execution ID
`reason`: Optional reason for stopping | ### Pipeline Details and Metrics | Tool Name | Description | Parameters | |-----------|-------------|------------| | `get_pipeline_details` | Get the full definition of a pipeline | `pipelineName`: Name of the pipeline | | `get_pipeline_execution_logs` | Get logs for a pipeline execution | `pipelineName`: Name of the pipeline
`executionId`: Execution ID | | `get_pipeline_metrics` | Get performance metrics for a pipeline | `pipelineName`: Name of the pipeline
`period`: Optional metric period in seconds
`startTime`: Optional start time for metrics
`endTime`: Optional end time for metrics | ### Pipeline Actions and Integrations | Tool Name | Description | Parameters | |-----------|-------------|------------| | `approve_action` | Approve or reject a manual approval action | `pipelineName`: Name of the pipeline
`stageName`: Name of the stage
`actionName`: Name of the action
`token`: Approval token
`approved`: Boolean indicating approval or rejection
`comments`: Optional comments | | `retry_stage` | Retry a failed stage | `pipelineName`: Name of the pipeline
`stageName`: Name of the stage
`pipelineExecutionId`: Execution ID | | `tag_pipeline_resource` | Add or update tags for a pipeline resource | `pipelineName`: Name of the pipeline
`tags`: Array of key-value pairs for tagging | | `create_pipeline_webhook` | Create a webhook for a pipeline | `pipelineName`: Name of the pipeline
`webhookName`: Name for the webhook
`targetAction`: Target action for the webhook
`authentication`: Authentication type
`authenticationConfiguration`: Optional auth config
`filters`: Optional event filters | ## Troubleshooting ### Common Issues 1. **Connection refused error**: - Ensure the server is running on the specified port - Check if the port is blocked by a firewall 2. **AWS credential errors**: - Verify your AWS credentials in the `.env` file - Ensure your IAM user has the necessary permissions 3. **Windsurf not detecting the MCP server**: - Check the `mcp_config.json` file format - Ensure the server URL is correct - Restart Windsurf after making changes ### Logs The server logs information to the console. Check these logs for troubleshooting: ```bash # Run with more verbose logging DEBUG=* npm start ``` ## Examples ### Creating a Webhook for GitHub Integration ```json { "pipelineName": "my-pipeline", "webhookName": "github-webhook", "targetAction": "Source", "authentication": "GITHUB_HMAC", "authenticationConfiguration": { "SecretToken": "my-secret-token" }, "filters": [ { "jsonPath": "$.ref", "matchEquals": "refs/heads/main" } ] } ``` ### Getting Pipeline Metrics ```json { "pipelineName": "my-pipeline", "period": 86400, "startTime": "2025-03-10T00:00:00Z", "endTime": "2025-03-17T23:59:59Z" } ``` ## License ISC