@vvssistemas/mcp-azure-devops

Servidor MCP (Model Context Protocol) que conecta ao Azure DevOps Server / TFS on-premise e expõe operações de work items, projetos, Git, pull requests e pipelines para o Claude (Claude Desktop, Claude Code, etc.).

Pré-requisitos

• Node.js 20+
• Uma instância acessível do Azure DevOps Server / TFS
• Um Personal Access Token (PAT) com os escopos que você pretende usar (Work Items leitura/escrita, Code leitura & status, Build leitura & execução, Project & Team leitura)

Instalação

Como pacote publicado (recomendado)

Não é necessário clonar o repositório — o Claude Desktop / Claude Code sobe o servidor diretamente via npx. Veja a seção Adicionando ao Claude Desktop abaixo.

A partir do código-fonte (desenvolvimento)

npm install
npm run build

Configuração

Copie .env.example para .env e preencha os valores:

cp .env.example .env

Variáveis:

| Variável | Descrição | | --------------------- | ------------------------------------------------------------------------------------ | | TFS_BASE_URL | URL raiz do seu servidor TFS, ex.: https://azure.example.com:8081/tfs | | TFS_COLLECTION | Nome da collection, ex.: Desenvolvimento ou DefaultCollection | | TFS_PAT | Personal Access Token, usado como senha no HTTP Basic | | TFS_API_VERSION | Versão da REST API (padrão 5.1) | | TFS_DEFAULT_PROJECT | Opcional. Projeto usado como fallback pelas tools quando o chamador omite project. |

A base efetiva da REST fica ${TFS_BASE_URL}/${TFS_COLLECTION}/_apis.

Execução

# Compila uma vez e roda a partir de dist/
npm run build && npm start

# Modo watch para desenvolvimento
npm run dev

# Sobe o MCP Inspector contra o servidor compilado
npm run inspector

O servidor fala MCP via stdio, então deve ser iniciado por um host MCP (Claude Desktop, Claude Code, Inspector). O stdout é reservado para o protocolo — diagnósticos saem no stderr.

Adicionando ao Claude Desktop

Edite ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) ou o equivalente no seu sistema operacional.

Usando o pacote publicado no npm (recomendado)

{
  "mcpServers": {
    "azure-devops": {
      "command": "npx",
      "args": ["-y", "@vvssistemas/mcp-azure-devops"],
      "env": {
        "TFS_BASE_URL": "https://azure.example.com:8081/tfs",
        "TFS_COLLECTION": "Desenvolvimento",
        "TFS_PAT": "***",
        "TFS_API_VERSION": "5.1",
        "TFS_DEFAULT_PROJECT": "Projetos"
      }
    }
  }
}

npx -y baixa e cacheia o pacote automaticamente — sem precisar clonar nem buildar.

A partir de um build local

{
  "mcpServers": {
    "azure-devops": {
      "command": "node",
      "args": ["/caminho/absoluto/para/azure-devops-mcp/dist/index.js"],
      "env": {
        "TFS_BASE_URL": "https://azure.example.com:8081/tfs",
        "TFS_COLLECTION": "Desenvolvimento",
        "TFS_PAT": "***",
        "TFS_API_VERSION": "5.1",
        "TFS_DEFAULT_PROJECT": "Projetos"
      }
    }
  }
}

Reinicie o Claude Desktop depois de salvar.

Adicionando ao Claude Code

O Claude Code (CLI) usa o comando claude mcp add. Como este servidor fala MCP via stdio, ele entra como um comando local — não é uma URL HTTP.

Usando o pacote publicado no npm

Recomendado instalar o binário globalmente primeiro: o npx -y na primeira execução pode estourar o timeout de handshake do Claude Code enquanto baixa o pacote.

npm install -g @vvssistemas/mcp-azure-devops

claude mcp add azure-devops \
  -e TFS_BASE_URL=https://azure.vvssistemas.com.br:8081/tfs \
  -e TFS_COLLECTION=Desenvolvimento \
  -e TFS_PAT=<seu-PAT> \
  -e TFS_API_VERSION=5.1 \
  -e TFS_DEFAULT_PROJECT=Projetos \
  -- mcp-azure-devops

Para deixar o servidor disponível em todos os projetos (e não só no diretório atual), adicione --scope user antes do --.

Verificar:

claude mcp list                # deve mostrar "azure-devops  ✓ Connected"
claude mcp get azure-devops    # detalhes da configuração

Remover:

claude mcp remove azure-devops

Atualizar pra última versão depois de uma nova release:

npm install -g @vvssistemas/mcp-azure-devops@latest

Alternativa: usando npx direto

Funciona igual à configuração do Claude Desktop, sem instalação global, mas com a ressalva do timeout no primeiro start:

claude mcp add azure-devops \
  -e TFS_BASE_URL=https://azure.vvssistemas.com.br:8081/tfs \
  -e TFS_COLLECTION=Desenvolvimento \
  -e TFS_PAT=<seu-PAT> \
  -e TFS_API_VERSION=5.1 \
  -e TFS_DEFAULT_PROJECT=Projetos \
  -- npx -y @vvssistemas/mcp-azure-devops

Se aparecer ✗ Failed to connect na primeira tentativa, rode npx -y @vvssistemas/mcp-azure-devops manualmente uma vez (ele cacheia o pacote) e adicione de novo, ou troque pela alternativa global acima.

Tools disponíveis

Projetos & Work Items

| Tool | Descrição | | ------------------ | ------------------------------------------------------------------------------------ | | list_projects | Lista todos os team projects da collection. | | get_work_item | Busca um work item pelo id numérico. | | list_work_items | Roda uma consulta WIQL filtrada por projeto e opcionalmente por type/state/assignee. | | create_work_item | Cria um work item (Bug, Task, User Story, ...). | | update_work_item | Atualiza title, state e/ou assignee de um work item existente. |

Git

| Tool | Descrição | | ------------- | --------------------------------------------------------------- | | list_repos | Lista repositórios Git de um projeto. | | get_commits | Últimos commits de um repositório (filtro opcional por branch). |

Pull Requests

| Tool | Descrição | | ----------------------------- | -------------------------------------------------------------------------------------------------------- | | list_pull_requests | Lista PRs de um repositório, filtrados por status. | | get_pull_request | Detalhes completos de um PR (reviewers, votos, status, commits de merge). | | create_pull_request | Abre PR de sourceBranch para targetBranch (auto-prefixa refs/heads/). Escrita. | | update_pull_request | Edita title, description e/ou estado de draft. Escrita. | | complete_pull_request | Faz merge do PR com a estratégia escolhida (squash / noFastForward / rebase / rebaseMerge). Escrita. | | abandon_pull_request | Define status como abandoned. Escrita. | | get_pull_request_threads | Lista as threads de comentários (geral + comentários inline em arquivos). | | add_pull_request_comment | Reply em uma thread ou nova thread (geral ou inline em filePath + line). Escrita. | | set_pull_request_vote | Vota: approve / approveWithSuggestions / noVote / waitForAuthor / reject. Escrita. | | add_pull_request_reviewer | Adiciona um reviewer (voto = 0). Escrita. | | get_pull_request_iterations | Snapshots do PR ao longo do tempo. | | get_pull_request_changes | Arquivos alterados em uma iteração (padrão: a última). |

Builds / Pipelines

| Tool | Descrição | | ------------------------ | --------------------------------------------------------------------------------------------------------------- | | list_build_definitions | Lista definitions de pipeline; suporta filtro por name com wildcard (*Dev*). | | get_build_definition | Detalhes completos de uma definition: variáveis, repositório, triggers, queue. | | list_builds | Builds recentes filtrados por definitionIds / status / result / branch. Padrão: mais recentes primeiro. | | get_build | Um build/run específico com timing, requester, status e result. | | get_build_timeline | Árvore tarefa-a-tarefa (jobs → phases → tasks) com erros e warnings. Use para descobrir qual step falhou. | | get_build_logs | Lista referências de log de um build (cada uma tem um logId). | | get_build_log_lines | Conteúdo do log em texto puro; passe startLine/endLine para limitar a saída. | | queue_build | Dispara um build para uma definition. Escrita. |

O servidor também expõe o resource tfs://projects, que retorna a lista de projetos como JSON.

Estrutura do projeto

src/
├── index.ts                # Entrypoint stdio
├── server.ts               # Wiring do McpServer
├── tfs-client.ts           # Cliente REST tipado para o TFS
├── tools/
│   ├── _helpers.ts         # Helpers compartilhados (resposta/erro/resolução de project)
│   ├── projects.ts         # list_projects
│   ├── work-items.ts       # get/list/create/update_work_item
│   ├── git.ts              # list_repos, get_commits
│   ├── pull-requests.ts    # tools de pull request
│   └── builds.ts           # tools de builds / pipelines
└── types/
    └── tfs.ts              # Interfaces TypeScript das entidades do TFS

Contribuindo

Este é um projeto interno em português brasileiro. Mensagens de commit, descrições de PR, documentação (README, CHANGELOG) e comentários voltados ao usuário devem ser escritos em pt-BR. Identificadores de código (nomes de variáveis, funções, tipos) e descrições de tools que vão para o LLM permanecem em inglês — esses textos são lidos pelo modelo e por integrações externas.

Licença

MIT © VVS Sistemas