Azure DevOps MCP Server

Um servidor MCP para Azure DevOps, permitindo que assistentes de IA interajam com as APIs do Azure DevOps.

Documentação

Servidor MCP do Azure DevOps

Uma implementação de servidor Model Context Protocol (MCP) para Azure DevOps, permitindo que assistentes de IA interajam com as APIs do Azure DevOps por meio de um protocolo padronizado.

Procurando o servidor oficial? A Microsoft mantém um MCP do Azure DevOps com suporte ao produto em microsoft/azure-devops-mcp. Se você usa o Azure DevOps Services (nuvem), comece por lá.

Este servidor da comunidade continua sendo uma boa opção quando você precisa de suporte ao Azure DevOps Server (on-premises) — especialmente versões mais antigas que podem não funcionar com o MCP da Microsoft — ou de recursos ainda não disponíveis no servidor oficial. Consulte a Discussão #237 para mais contexto. Consulte ROADMAP.md para saber onde este servidor se diferencia e o que está planejado.

Visão Geral

Este servidor implementa o Model Context Protocol (MCP) para Azure DevOps, permitindo que assistentes de IA como o Claude interajam com os recursos do Azure DevOps de forma segura. O servidor atua como uma ponte entre modelos de IA e as APIs do Azure DevOps, fornecendo uma maneira padronizada de:

Acessar e gerenciar projetos, itens de trabalho, repositórios e muito mais
Criar e atualizar itens de trabalho, branches e pull requests
Executar fluxos de trabalho comuns de DevOps por meio de linguagem natural
Acessar o conteúdo do repositório por meio de URIs de recursos padronizados
Autenticar e interagir com segurança com os recursos do Azure DevOps

Estrutura do Servidor

O servidor é estruturado em torno do Model Context Protocol (MCP) para comunicação com assistentes de IA. Ele fornece ferramentas para interagir com os recursos do Azure DevOps, incluindo:

Projetos
Itens de Trabalho
Repositórios
Pull Requests
Branches
Pipelines

Componentes Principais

AzureDevOpsServer: Classe principal do servidor que inicializa o servidor MCP e registra as ferramentas
Módulos de Recursos: Organizados por área de recurso (itens de trabalho, projetos, repositórios, etc.)
Manipuladores de Solicitações: Cada módulo de recurso fornece funções de identificação e tratamento de solicitações
Manipuladores de Ferramentas: Funções modulares para cada operação do Azure DevOps
Configuração: Configuração baseada em variáveis de ambiente para URL da organização, PAT, etc.

O servidor usa uma arquitetura baseada em recursos, onde cada área de recurso (como itens de trabalho, projetos, repositórios) é encapsulada em seu próprio módulo. Isso torna o código mais fácil de manter e de estender com novos recursos.

Primeiros Passos

Pré-requisitos

Node.js (v16+)
npm ou yarn
Conta do Azure DevOps com acesso apropriado
Credenciais de autenticação (consulte o Guia de Autenticação para detalhes):
- Personal Access Token (PAT), ou
- Credenciais do Azure Identity, ou
- Login do Azure CLI

Executando via npm (npx)

Se você quiser apenas executar o pacote do servidor publicado, não é necessário clonar ou compilar este repositório:

npx -y @tiberriver256/mcp-server-azure-devops

Executando localmente (a partir do código-fonte)

A partir de um checkout deste repositório:

npm ci
cp .env.example .env   # then edit values
npm run build
npm start              # runs: node dist/index.js

Para desenvolvimento iterativo (recarga automática):

npm run dev            # runs src/index.ts via ts-node-dev

Uso com Claude Desktop/Cursor AI

Para integrar com o Claude Desktop ou Cursor AI, adicione uma das seguintes configurações ao seu arquivo de configuração.

Autenticação com Azure Identity

Certifique-se de estar logado no Azure CLI com az login e adicione o seguinte:

{
  "mcpServers": {
    "azureDevOps": {
      "command": "npx",
      "args": ["-y", "@tiberriver256/mcp-server-azure-devops"],
      "env": {
        "AZURE_DEVOPS_ORG_URL": "https://dev.azure.com/your-organization",
        "AZURE_DEVOPS_AUTH_METHOD": "azure-identity",
        "AZURE_DEVOPS_DEFAULT_PROJECT": "your-project-name"
      }
    }
  }
}

Autenticação com Personal Access Token (PAT)

{
  "mcpServers": {
    "azureDevOps": {
      "command": "npx",
      "args": ["-y", "@tiberriver256/mcp-server-azure-devops"],
      "env": {
        "AZURE_DEVOPS_ORG_URL": "https://dev.azure.com/your-organization",
        "AZURE_DEVOPS_AUTH_METHOD": "pat",
        "AZURE_DEVOPS_PAT": "<YOUR_PAT>",
        "AZURE_DEVOPS_DEFAULT_PROJECT": "your-project-name"
      }
    }
  }
}

O Azure DevOps Server (on-premises) exige autenticação via PAT. Exemplo:

{
  "mcpServers": {
    "azureDevOps": {
      "command": "npx",
      "args": ["-y", "@tiberriver256/mcp-server-azure-devops"],
      "env": {
        "AZURE_DEVOPS_ORG_URL": "https://server:8080/tfs/DefaultCollection",
        "AZURE_DEVOPS_AUTH_METHOD": "pat",
        "AZURE_DEVOPS_PAT": "<YOUR_PAT>",
        "AZURE_DEVOPS_DEFAULT_PROJECT": "your-project-name"
      }
    }
  }
}

Para instruções detalhadas de configuração e mais opções de autenticação, consulte o Guia de Autenticação.

Métodos de Autenticação

Este servidor suporta vários métodos de autenticação para conectar-se às APIs do Azure DevOps. Para instruções detalhadas de configuração, exemplos de configuração e dicas de solução de problemas, consulte o Guia de Autenticação.

Métodos de Autenticação Suportados

Personal Access Token (PAT) - Autenticação simples baseada em token
Azure Identity (DefaultAzureCredential) - Autenticação flexível usando o SDK do Azure Identity
Azure CLI - Autenticação usando seu login do Azure CLI

Arquivos de configuração de exemplo para cada método de autenticação estão disponíveis no diretório de exemplos.

O Azure DevOps Server (on-premises) suporta apenas autenticação via PAT. Azure Identity e Azure CLI são suportados para o Azure DevOps Services.

Variáveis de Ambiente

Para uma lista completa das variáveis de ambiente e suas descrições, consulte o Guia de Autenticação.

As principais variáveis de ambiente incluem:

Variável	Descrição	Obrigatória	Padrão
`AZURE_DEVOPS_AUTH_METHOD`	Método de autenticação (`pat`, `azure-identity` ou `azure-cli`) - sem diferenciar maiúsculas de minúsculas	Não	`azure-identity`
`AZURE_DEVOPS_ORG_URL`	URL completa da sua organização ou coleção do Azure DevOps Server (ex.: `https://server:8080/tfs/DefaultCollection`)	Sim	-
`AZURE_DEVOPS_PAT`	Personal Access Token (para autenticação via PAT)	Somente com autenticação via PAT	-
`AZURE_DEVOPS_DEFAULT_PROJECT`	Projeto padrão se nenhum for especificado	Não	-
`AZURE_DEVOPS_API_VERSION`	Versão da API REST para as ferramentas que chamam a API REST diretamente (valores por versão)	Não	`7.1`
`AZURE_TENANT_ID`	ID do locatário do Azure AD (para service principals)	Somente com service principals	-
`AZURE_CLIENT_ID`	ID do aplicativo do Azure AD (para service principals)	Somente com service principals	-
`AZURE_CLIENT_SECRET`	Segredo do cliente do Azure AD (para service principals)	Somente com service principals	-
`LOG_LEVEL`	Nível de log (debug, info, warn, error)	Não	info

Solução de Problemas de Autenticação

Para informações detalhadas de solução de problemas para cada método de autenticação, consulte o Guia de Autenticação.

Os problemas comuns incluem:

Credenciais inválidas ou expiradas
Permissões insuficientes
Problemas de conectividade de rede
Erros de configuração

Detalhes de Implementação da Autenticação

Para detalhes técnicos sobre como a autenticação é implementada no servidor MCP do Azure DevOps, consulte o Guia de Autenticação e o código-fonte no diretório src/auth.

Ferramentas Disponíveis

O servidor MCP do Azure DevOps fornece uma variedade de ferramentas para interagir com os recursos do Azure DevOps. Para documentação detalhada sobre cada ferramenta, consulte a documentação correspondente.

Ferramentas de Usuário

get_me: Obter detalhes do usuário autenticado (id, displayName, email) (somente Azure DevOps Services)

Ferramentas de Organização

list_organizations: Listar todas as organizações acessíveis (somente Azure DevOps Services)

Ferramentas de Projeto

list_projects: Listar todos os projetos em uma organização
get_project: Obter detalhes de um projeto específico
get_project_details: Obter detalhes abrangentes de um projeto, incluindo processo, tipos de item de trabalho e equipes

Ferramentas de Repositório

list_repositories: Listar todos os repositórios em um projeto
get_repository: Obter detalhes de um repositório específico
get_repository_details: Obter informações detalhadas sobre um repositório, incluindo estatísticas e refs
get_file_content: Obter conteúdo de um arquivo ou diretório de um repositório
get_repository_tree: Listar a árvore de arquivos de um repositório a partir de qualquer caminho e profundidade
create_branch: Criar um novo branch a partir de um existente
create_commit: Enviar múltiplas alterações de arquivos para um branch usando diffs unificados ou instruções de busca/substituição

Ferramentas de Item de Trabalho

get_work_item: Recuperar um item de trabalho por ID
create_work_item: Criar um novo item de trabalho
update_work_item: Atualizar um item de trabalho existente
list_work_items: Listar itens de trabalho em um projeto
manage_work_item_link: Adicionar, remover ou atualizar links entre itens de trabalho

Ferramentas de Pesquisa

search_code: Pesquisar código em repositórios de um projeto
search_wiki: Pesquisar conteúdo em páginas de wiki de um projeto
search_work_items: Pesquisar itens de trabalho em projetos do Azure DevOps

Ferramentas de Pipelines

list_pipelines: Listar pipelines em um projeto
get_pipeline: Obter detalhes de um pipeline específico
list_pipeline_runs: Listar execuções recentes de um pipeline com filtros opcionais
get_pipeline_run: Obter informações detalhadas de execução e resumos de artefatos
download_pipeline_artifact: Baixar um único arquivo de artefato como texto
pipeline_timeline: Recuperar a linha do tempo de estágios e jobs de uma execução
get_pipeline_log: Recuperar conteúdo de log bruto ou formatado em JSON
trigger_pipeline: Disparar uma execução de pipeline com parâmetros personalizáveis

Ferramentas de Wiki

get_wikis: Listar todas as wikis em um projeto
get_wiki_page: Obter conteúdo de uma página de wiki específica como texto simples

Ferramentas de Pull Request

create_pull_request - Criar um novo pull request
get_pull_request - Obter um pull request por ID
list_pull_requests - Listar pull requests em um repositório
add_pull_request_comment - Adicionar um comentário a um pull request
get_pull_request_comments - Obter comentários de um pull request
update_pull_request - Atualizar um pull request existente (título, descrição, status, estado de rascunho, revisores, itens de trabalho)
get_pull_request_changes - Listar alterações em um pull request e status de avaliação de políticas
get_pull_request_checks - Resumir verificações de status, avaliações de políticas e seus pipelines relacionados

Para documentação abrangente sobre todas as ferramentas, consulte a Documentação de Ferramentas.

Contribuindo

Contribuições são bem-vindas! Consulte CONTRIBUTING.md para as diretrizes de contribuição.

Histórico de Estrelas

Licença

MIT