AWS CodePipeline MCP Server

Integra-se ao AWS CodePipeline para gerenciar pipelines de integração e entrega contínuas.

Documentação

AWS CodePipeline MCP Server

Este é um servidor Model Context Protocol (MCP) que se integra ao AWS CodePipeline, permitindo gerenciar seus pipelines por meio do Windsurf e do Cascade. O servidor fornece uma interface padronizada para interagir com os serviços do AWS CodePipeline.

Autor: Cuong T Nguyen

Recursos

Listar todos os pipelines
Obter o estado do pipeline e definições detalhadas do pipeline
Listar execuções de pipeline
Aprovar ou rejeitar ações de aprovação manual
Repetir estágios com falha
Acionar execuções de pipeline
Visualizar logs de execução do pipeline
Parar execuções de pipeline
Adicionar tags a recursos do pipeline
Criar webhooks para acionamento automático de pipelines
Obter métricas de desempenho do pipeline

Pré-requisitos

Node.js (v14 ou posterior)
Conta AWS com acesso ao CodePipeline
Credenciais AWS com permissões para CodePipeline e CloudWatch (leitura de métricas)
IDE Windsurf com assistente de IA Cascade

Instalação

Clone este repositório:

git clone https://github.com/cuongdev/mcp-codepipeline-server.git
cd mcp-codepipeline-server

Instale as dependências:

npm install

Crie um arquivo .env com base no modelo .env.example:

cp .env.example .env

Atualize o arquivo .env com sua configuração da AWS (veja .env.example):

AWS_REGION=us-east-1
AWS_PROFILE=your-aws-profile

Nota: Por segurança, nunca envie seu arquivo .env para o controle de versão.

Autenticação AWS

Você não precisa de chaves de acesso de longa duração em .env. Escolha uma abordagem:

Abordagem	Configuração
Perfil AWS (recomendado para desenvolvimento local)	`AWS_PROFILE=my-profile` — usa `~/.aws/credentials` / `~/.aws/config`
AWS SSO	`aws configure sso` depois `aws sso login --profile my-sso` e defina `AWS_PROFILE=my-sso`
Chaves estáticas	Defina `AWS_ACCESS_KEY_ID` e `AWS_SECRET_ACCESS_KEY` (e `AWS_SESSION_TOKEN` para credenciais temporárias)
Função IAM	Execute em EC2/ECS/Lambda/EKS com uma função anexada; defina apenas `AWS_REGION`

Se as chaves de acesso forem omitidas, o AWS SDK usa sua cadeia de provedores de credenciais padrão.

Criando um perfil AWS

Um perfil é uma entrada nomeada em ~/.aws/credentials e ~/.aws/config. Defina AWS_PROFILE para esse nome em .env ou na configuração do MCP.

Opção A: Chaves de acesso (usuário IAM)

Requer AWS CLI.

aws configure --profile codepipeline-dev

Você será solicitado a fornecer:

Prompt	Exemplo
AWS Access Key ID	`AKIA...`
AWS Secret Access Key	(secreto)
Default region name	`us-east-1`
Default output format	`json`

Em seguida, em .env:

AWS_REGION=us-east-1
AWS_PROFILE=codepipeline-dev

Opção B: AWS SSO (IAM Identity Center)

aws configure sso --profile codepipeline-sso

Siga os prompts (URL de início do SSO, região do SSO, conta, função). Em seguida, faça login antes de iniciar o servidor MCP:

aws sso login --profile codepipeline-sso

Em .env:

AWS_REGION=us-east-1
AWS_PROFILE=codepipeline-sso

As sessões SSO expiram; execute aws sso login novamente quando vir erros de credenciais.

Verificar o perfil

aws sts get-caller-identity --profile codepipeline-dev
aws codepipeline list-pipelines --region us-east-1 --profile codepipeline-dev

Se ambos os comandos forem bem-sucedidos, o servidor MCP poderá usar o mesmo AWS_PROFILE e AWS_REGION.

Arquivos criados (referência)

~/.aws/credentials:

[codepipeline-dev]
aws_access_key_id = AKIA...
aws_secret_access_key = ...

~/.aws/config:

[profile codepipeline-dev]
region = us-east-1
output = json

Uso

Compilar o projeto

npm run build

Iniciar o servidor

npm start

Para desenvolvimento com reinicialização automática:

npm run dev

Integração com o Windsurf

Este servidor MCP foi projetado para funcionar com o Windsurf, permitindo que o Cascade interaja com o AWS CodePipeline por meio de solicitações em linguagem natural.

Etapas de configuração

Certifique-se de que o servidor esteja em execução:

npm start

Adicione a configuração do servidor ao arquivo de configuração MCP do Windsurf em ~/.codeium/windsurf/mcp_config.json:

{
   "mcpServers": {
    "codepipeline": {
      "command": "npx",
      "args": [
        "-y",
        "path/to/mcp-codepipeline-server/dist/index.js"
      ],
      "env": {
        "AWS_REGION": "us-east-1",
        "AWS_PROFILE": "your-aws-profile"
      }
    }
  }
}

Crie o diretório se ele não existir:

mkdir -p ~/.codeium/windsurf
touch ~/.codeium/windsurf/mcp_config.json

Reinicie o Windsurf para carregar a nova configuração do servidor MCP

Usando com o Cascade

Após a configuração, você pode interagir com o AWS CodePipeline usando linguagem natural no Windsurf. Por exemplo:

"Liste todos os meus pipelines do CodePipeline"
"Mostre-me o estado atual do meu pipeline 'production-deploy'"
"Acione o pipeline 'test-build'"
"Obtenha métricas para o meu pipeline 'data-processing'"
"Crie um webhook para o meu pipeline 'frontend-deploy'"

O Cascade traduzirá essas solicitações nas chamadas de ferramenta MCP apropriadas.

Ferramentas MCP

Gerenciamento principal de pipelines

Nome da ferramenta	Descrição	Parâmetros
`list_pipelines`	Listar todos os pipelines do CodePipeline	Nenhum
`get_pipeline_state`	Obter o estado de um pipeline específico	`pipelineName`: Nome do pipeline
`list_pipeline_executions`	Listar execuções de um pipeline específico	`pipelineName`: Nome do pipeline
`trigger_pipeline`	Acionar uma execução de pipeline	`pipelineName`: Nome do pipeline
`stop_pipeline_execution`	Parar uma execução de pipeline	`pipelineName`: Nome do pipeline `executionId`: ID da execução `reason`: Motivo opcional para parar

Detalhes e métricas do pipeline

Nome da ferramenta	Descrição	Parâmetros
`get_pipeline_details`	Obter a definição completa de um pipeline	`pipelineName`: Nome do pipeline
`get_pipeline_execution_logs`	Obter logs de uma execução de pipeline	`pipelineName`: Nome do pipeline `executionId`: ID da execução
`get_pipeline_metrics`	Obter métricas de desempenho de um pipeline	`pipelineName`: Nome do pipeline `period`: Período de métrica opcional em segundos `startTime`: Hora de início opcional para métricas `endTime`: Hora de término opcional para métricas

Ações e integrações do pipeline

Nome da ferramenta	Descrição	Parâmetros
`approve_action`	Aprovar ou rejeitar uma ação de aprovação manual	`pipelineName`: Nome do pipeline `stageName`: Nome do estágio `actionName`: Nome da ação `token`: Token de aprovação `approved`: Booleano indicando aprovação ou rejeição `comments`: Comentários opcionais
`retry_stage`	Repetir um estágio com falha	`pipelineName`: Nome do pipeline `stageName`: Nome do estágio `pipelineExecutionId`: ID da execução
`tag_pipeline_resource`	Adicionar ou atualizar tags para um recurso de pipeline	`pipelineName`: Nome do pipeline `tags`: Matriz de pares chave-valor para marcação
`create_pipeline_webhook`	Criar um webhook para um pipeline	`pipelineName`: Nome do pipeline `webhookName`: Nome do webhook `targetAction`: Ação de destino para o webhook `authentication`: Tipo de autenticação `authenticationConfiguration`: Configuração de autenticação opcional `filters`: Filtros de evento opcionais

Solução de problemas

Problemas comuns

Erro de conexão recusada:
- Certifique-se de que o servidor esteja em execução na porta especificada
- Verifique se a porta está bloqueada por um firewall
Erros de credenciais AWS:
- Para perfis/SSO: execute aws sso login --profile YOUR_PROFILE se necessário e depois defina AWS_PROFILE
- Para chaves estáticas: verifique AWS_ACCESS_KEY_ID e AWS_SECRET_ACCESS_KEY em .env ou no MCP env
- Garanta que o principal tenha permissões para CodePipeline (e CloudWatch para métricas)
- Verifique os logs de inicialização do servidor para AWS credentials: default provider chain vs static keys
Windsurf não detectando o servidor MCP:
- Verifique o formato do arquivo mcp_config.json
- Certifique-se de que a URL do servidor esteja correta
- Reinicie o Windsurf após fazer alterações

Logs

O servidor registra informações no console. Verifique esses logs para solução de problemas:

# Run with more verbose logging
DEBUG=* npm start

Exemplos

Criando um webhook para integração com GitHub

{
  "pipelineName": "my-pipeline",
  "webhookName": "github-webhook",
  "targetAction": "Source",
  "authentication": "GITHUB_HMAC",
  "authenticationConfiguration": {
    "SecretToken": "my-secret-token"
  },
  "filters": [
    {
      "jsonPath": "$.ref",
      "matchEquals": "refs/heads/main"
    }
  ]
}

Obtendo métricas do pipeline

{
  "pipelineName": "my-pipeline",
  "period": 86400,
  "startTime": "2025-03-10T00:00:00Z",
  "endTime": "2025-03-17T23:59:59Z"
}

Licença

ISC