# Fluxos de trabalho de integração (/pt/docs/verdent-for-vscode/advanced-features/integrations)

> Padrões práticos para integrar o Verdent com ferramentas e serviços externos



### O que você vai aprender [#o-que-você-vai-aprender]

Fluxos de trabalho práticos de integração que combinam subagentes personalizados, regras e servidores MCP para cenários reais de desenvolvimento.

***

## Métodos de integração [#métodos-de-integração]

| Método                        | Ideal para                                       | Configuração                  |
| ----------------------------- | ------------------------------------------------ | ----------------------------- |
| **Subagentes personalizados** | Tarefas especializadas com IA                    | `~/.verdent/subagents/*.md`   |
| **Regras (AGENTS.md)**        | Padrões e comportamento da equipe                | Raiz do projeto `AGENTS.md`   |
| **Servidores MCP**            | Ferramentas externas compatíveis com o protocolo | `.mcp.json` (raiz do projeto) |

**Filosofia:** Combine métodos para criar fluxos de trabalho abrangentes adaptados às suas necessidades.

***

## Padrões comuns de integração [#padrões-comuns-de-integração]

### Fluxo de trabalho de desenvolvimento de banco de dados [#fluxo-de-trabalho-de-desenvolvimento-de-banco-de-dados]

**Stack:** Subagente Migration Reviewer + Padrões do AGENTS.md + Servidor MCP PostgreSQL

**Subagente:**

```markdown
---
name: migration-reviewer
description: Reviews database migrations for safety
---
Checks: Destructive operations, reversibility, indexing, blocking operations
```

**AGENTS.md:**

```markdown
## Database Standards
- All migrations reviewed by @migration-reviewer
- Test on staging before production
- Include rollback procedures
```

**MCP:** Servidor PostgreSQL para execução de queries, inspeção de schema e validação de migrações

**Fluxo de trabalho:** Escrever migração → @migration-reviewer valida → MCP testa em staging → documentação do PR

***

### Desenvolvimento de API com segurança [#desenvolvimento-de-api-com-segurança]

**Stack:** Security Auditor + Regras do AGENTS.md + Ferramenta personalizada de testes API

**Componentes:**

* **Subagente:** `@api-security-auditor` - Validação de entrada, injeção de SQL, autenticação, limitação de taxa
* **Regras:** Todos os endpoints exigem revisão de segurança, limitação de taxa em APIs públicas
* **Ferramentas externas:** Testes automatizados de endpoints e varreduras de segurança por meio de integração personalizada

**Resultado:** Revisão de segurança automática antes da aprovação do PR.

<Note>
  Ferramentas de testes de API e de varredura de segurança podem ser integradas por meio de implementações personalizadas de servidores MCP ou outros métodos de integração, dependendo do seu ferramental.
</Note>

***

### Acessibilidade de frontend [#acessibilidade-de-frontend]

**Stack:** Accessibility Auditor + Regras WCAG + Integração com Lighthouse

**Fluxo de trabalho:**

```
Create component → @a11y-auditor reviews → Lighthouse tests accessibility → Rules enforce >90 score
```

<Note>
  O Lighthouse e outras ferramentas de acessibilidade podem ser integrados por meio de servidores MCP personalizados ou da integração com pipeline de CI/CD, dependendo do seu fluxo de trabalho.
</Note>

***

## Exemplos de configuração de MCP [#exemplos-de-configuração-de-mcp]

### Entendendo o MCP [#entendendo-o-mcp]

O &#x2A;*Model Context Protocol (MCP)** é um protocolo aberto que padroniza como os aplicativos fornecem contexto aos LLMs. Os servidores MCP são executáveis que implementam o protocolo. Eles não são conexões de banco de dados nem endpoints de API, mas programas que rodam e se comunicam via JSON-RPC 2.0.

**Conceitos principais:**

* **Servidores MCP**: Executáveis (pacotes Node.js, scripts Python, etc.) que implementam o protocolo MCP
* **Configuração**: Informa ao Verdent como iniciar o servidor (`command` + `args`)
* **Comunicação**: Os servidores cuidam da própria lógica de negócio (queries, chamadas de API, etc.)

### Configuração básica [#configuração-básica]

**Localização:** `.mcp.json` na raiz do projeto

<CodeGroup>
  ```json PostgreSQL Server
  {
    "mcpServers": {
      "postgres": {
        "command": "npx",
        "args": [
          "-y",
          "@modelcontextprotocol/server-postgres",
          "postgresql://localhost:5432/myapp_dev"
        ]
      }
    }
  }
  ```

  ```json GitHub Server
  {
    "mcpServers": {
      "github": {
        "command": "npx",
        "args": [
          "-y",
          "@modelcontextprotocol/server-github"
        ],
        "env": {
          "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
        }
      }
    }
  }
  ```

  ```json Multiple Servers
  {
    "mcpServers": {
      "postgres": {
        "command": "npx",
        "args": [
          "-y",
          "@modelcontextprotocol/server-postgres",
          "postgresql://localhost:5432/myapp_dev"
        ]
      },
      "github": {
        "command": "npx",
        "args": [
          "-y",
          "@modelcontextprotocol/server-github"
        ],
        "env": {
          "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
        }
      }
    }
  }
  ```
</CodeGroup>

**Explicação:**

* `mcpServers` - Chave de nível superior obrigatória para a configuração do MCP
* `command` - Executável a ser rodado (normalmente `npx` para pacotes Node.js)
* `args` - Argumentos passados ao comando (nome do pacote, strings de conexão, etc.)
* `env` - Variáveis de ambiente para autenticação/configuração

### Múltiplos ambientes [#múltiplos-ambientes]

```json
{
  "mcpServers": {
    "postgres-dev": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "${DEV_DATABASE_URL}"
      ]
    },
    "postgres-staging": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "${STAGING_DATABASE_URL}"
      ]
    },
    "postgres-prod": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "${PROD_DATABASE_URL}"
      ]
    }
  }
}
```

**Boa prática:** Use variáveis de ambiente para strings de conexão a fim de manter as credenciais seguras. Os servidores MCP tratam o comportamento somente leitura internamente, com base em sua implementação. Consulte a documentação específica do servidor para opções de controle de acesso.

<Tip>
  **Saiba mais sobre MCP:**

  * [Especificação do Model Context Protocol](https://modelcontextprotocol.io/specification)
  * [Registro de servidores MCP](https://mcp.so/servers) - Explore os servidores MCP disponíveis
  * [Servidores MCP oficiais](https://github.com/modelcontextprotocol) - PostgreSQL, GitHub, Filesystem e mais
</Tip>

***

## Integração com o espaço de trabalho [#integração-com-o-espaço-de-trabalho]

### Configuração específica do projeto [#configuração-específica-do-projeto]

**Configuração:**

1. Armazene na raiz do projeto: `.mcp.json`
2. Faça commit no controle de versão para compartilhamento com a equipe
3. Os membros da equipe usam automaticamente os servidores MCP do projeto

**Exemplo de microsserviços:**

```json
{
  "mcpServers": {
    "users-db": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://localhost:5432/users"
      ]
    },
    "orders-db": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://localhost:5433/orders"
      ]
    }
  }
}
```

<Note>
  Para serviços adicionais como Kafka, você precisaria de uma implementação de servidor MCP compatível. O registro oficial de servidores MCP em [mcp.so/servers](https://mcp.so/servers) lista os servidores da comunidade disponíveis.
</Note>

***

## Colaboração em equipe [#colaboração-em-equipe]

### Padrões compartilhados do AGENTS.md [#padrões-compartilhados-do-agentsmd]

Faça commit no controle de versão para consistência em toda a equipe:

```markdown
# AGENTS.md

## Code Review Process
- Run @code-reviewer before PR
- Address all security warnings
- Minimum 80% test coverage

## Integration Requirements
- @migration-reviewer for database changes
- @api-security-auditor for new endpoints
- @a11y-auditor for UI components

## MCP Servers
- Use postgres-staging MCP server for queries
- Never use postgres-prod MCP server for exploratory queries
```

**Benefícios:** Comportamento consistente, padrões aplicados, portões de qualidade automáticos.

***

## Coordenação multiagente [#coordenação-multiagente]

### Fluxo de trabalho de funcionalidade complexa [#fluxo-de-trabalho-de-funcionalidade-complexa]

**Exemplo:** Novo endpoint de pagamento

```
1. Developer request → 2. Main agent generates code →
3. @api-security-auditor reviews security →
4. @migration-reviewer validates schema →
5. MCP tests on staging →
6. Main agent generates tests and PR
```

**Resultado:** Endpoint totalmente revisado com as melhores práticas de segurança e banco de dados aplicadas.

***

## Boas práticas de integração [#boas-práticas-de-integração]

### Adoção progressiva [#adoção-progressiva]

**Fase 1:** Regras básicas

```markdown
## Code Standards
- Use TypeScript strict mode
- Run tests before commit
```

**Fase 2:** Adicione um subagente especializado

```markdown
## Code Review
- Run @security-reviewer before PR
```

**Fase 3:** Integre o MCP

```markdown
## Database Access
- Use MCP postgres-staging for queries
```

### Combinações estratégicas [#combinações-estratégicas]

| Combinação          | Finalidade                                          | Exemplo                                          |
| ------------------- | --------------------------------------------------- | ------------------------------------------------ |
| Regras + Subagentes | Regras definem *quando*, subagentes *analisam*      | AGENTS.md: "Revisar com @security-reviewer"      |
| Regras + MCP        | Regras especificam *quais* servidores, MCP *acessa* | AGENTS.md: "Usar apenas db-staging"              |
| Subagentes + MCP    | O subagente usa o MCP para *dados externos*         | O auditor de segurança consulta endpoints de API |

### Boas práticas de documentação para a equipe [#boas-práticas-de-documentação-para-a-equipe]

Ao documentar integrações para a sua equipe, inclua:

* **Subagentes personalizados**: Liste o nome, a finalidade e quando invocar cada subagente
* **Regras do AGENTS.md**: Documente as regras com a justificativa explicando o "porquê" de cada padrão
* **Servidores MCP**: Descreva a finalidade de cada servidor, o nível de acesso (somente leitura/escrita) e quando usá-lo
* **Fluxos de trabalho de integração**: Forneça exemplos de fluxos de trabalho mostrando como os componentes funcionam juntos
* **Solução de problemas**: Documente problemas comuns específicos da sua configuração e suas soluções

<Tip>
  Faça commit da documentação de integração junto com os seus arquivos `.mcp.json` e `AGENTS.md` para que novos membros da equipe entendam rapidamente a sua configuração.
</Tip>

***

## Solução de problemas [#solução-de-problemas]

<Tabs>
  <Tab title="Problemas com subagentes">
    **Problema:** O subagente não é invocado quando esperado

    **Verifique:**

    **Localização**: O arquivo existe em `~/.verdent/subagents/[name].md`

    **Frontmatter YAML**: Sintaxe válida com os campos obrigatórios `name` e `description`

    **Política de invocação**: Corresponde ao uso (o modo estrito exige @-menção explícita)

    **Descrição**: A `description` do agente descreve com precisão quando o subagente deve ser usado

    **Reiniciar**: Tente reiniciar o Verdent para recarregar as definições de subagentes

    ***

    **Causas comuns:**

    * Erro de digitação no nome do arquivo do subagente ou na @-menção
    * Sintaxe YAML inválida no frontmatter
    * A `description` do subagente não corresponde ao contexto da tarefa
  </Tab>

  <Tab title="Problemas com AGENTS.md">
    **Problema:** As regras do AGENTS.md não estão sendo aplicadas

    **Verifique:**

    **Localização**: O arquivo está no diretório raiz do projeto

    **Sintaxe**: Markdown válido sem erros de parsing

    **Estilo de diretiva**: Use comandos específicos ("Sempre use..." em vez de "Tente...")

    **Sessão**: Inicie uma nova conversa para testar a aplicação das regras do zero

    **Conflitos**: Verifique se as regras do usuário substituem involuntariamente as regras do projeto

    ***

    **Causas comuns:**

    * AGENTS.md no diretório errado (deve ser a raiz do projeto)
    * Instruções vagas que a IA interpreta de forma diferente
    * Regras aplicadas, mas com resultados inesperados (refine a redação)
  </Tab>

  <Tab title="Problemas com servidores MCP">
    **Problema:** O servidor MCP falha ao iniciar ou conectar

    **Verifique:**

    **Sintaxe**: O `.mcp.json` contém JSON válido (use `jq` para validar)

    **Estrutura**: A chave obrigatória `mcpServers` está presente no nível superior

    **Configuração do servidor**: Cada servidor tem `command` e `args` especificados corretamente

    **Pacote**: O pacote do servidor MCP está acessível (`npx` baixa pacotes automaticamente; a flag `-y` ignora o prompt de confirmação)

    **Ambiente**: As variáveis no objeto `env` estão definidas corretamente no seu shell

    **Permissões**: O executável do servidor tem as permissões de execução adequadas

    ***

    **Causas comuns:**

    * Erro de digitação no JSON (vírgula faltando, colchete não fechado)
    * Nome de pacote errado no array args
    * Variáveis de ambiente ausentes ou incorretas
    * Rede/firewall bloqueando a instalação do pacote via npx

    ***

    **Passos de depuração:**

    1. Valide o JSON: `cat .mcp.json | jq .`
    2. Teste o comando manualmente: `npx -y @modelcontextprotocol/server-postgres "postgresql://..."`
    3. Verifique o ambiente: `echo $GITHUB_TOKEN`
    4. Revise os logs do Verdent em busca de mensagens de erro específicas
  </Tab>
</Tabs>

***

## Veja também [#veja-também]

<CardGroup cols="2">
  <Card title="Guia de extensibilidade" icon="puzzle-piece" href="/docs/verdent-for-vscode/advanced-features/extensibility">
    Visão geral completa dos métodos de extensão
  </Card>

  <Card title="Integração com MCP" icon="plug" href="/docs/verdent-for-vscode/advanced-features/mcp">
    Detalhes do Model Context Protocol
  </Card>
</CardGroup>