> ## Documentation Index
> Fetch the complete documentation index at: https://zeropath.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Referência de Ferramentas MCP

> Referência completa de todas as ferramentas disponíveis através do Servidor MCP da ZeroPath

O servidor MCP expõe ferramentas que mapeiam para a API REST V2 da ZeroPath. As ferramentas são carregadas do manifesto MCP da ZeroPath na inicialização, então seu assistente de IA sempre tem acesso às capacidades atuais.

<CardGroup cols={2}>
  <Card title="Issues" icon="shield-exclamation">
    12 ferramentas — listar, triar, investigar, atualizar status, severidade e notas, regenerar patches
  </Card>

  <Card title="Scans" icon="magnifying-glass">
    3 ferramentas — listar histórico de scans, obter detalhes de um scan, reescanear PRs
  </Card>

  <Card title="Repositórios" icon="code-branch">
    1 ferramenta — listar repositórios com filtragem
  </Card>

  <Card title="Inspeção de Código" icon="file-code">
    3 ferramentas — buscar, ler e listar arquivos em repositórios conectados
  </Card>

  <Card title="Regras" icon="gavel">
    5 ferramentas — CRUD completo para regras de segurança personalizadas
  </Card>
</CardGroup>

<h2 id="organization-scoping">
  Escopo de Organização
</h2>

Toda ferramenta aceita `organizationId`. O servidor MCP lida com isso automaticamente:

* Se `ZEROPATH_ORG_ID` estiver definido, o servidor **o injeta em cada requisição** — você nunca precisa passá-lo manualmente.
* Se `ZEROPATH_ORG_ID` **não** estiver definido, você deve passar `organizationId` explicitamente. A maioria das ferramentas o exige no nível da API; algumas (como `issues.list`) conseguem resolver o contexto da organização a partir da sua sessão de autenticação.

<Tip>
  Defina `ZEROPATH_ORG_ID` durante a [instalação](/pt/mcp/installation) para evitar passar `organizationId` em cada chamada.
</Tip>

***

<h2 id="issue-tools">
  Ferramentas de Issues
</h2>

<h3 id="issues-list">
  issues.list
</h3>

Liste e filtre issues de segurança. Usa **paginação baseada em offset** via `offset` e `limit`.

| Parameter                   | Type      | Required | Descrição                                                                                                                                                                                                                   |
| --------------------------- | --------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `offset`                    | integer   | No       | Índice inicial (padrão: 0)                                                                                                                                                                                                  |
| `limit`                     | integer   | No       | Resultados por página (padrão: 25, máx: 100)                                                                                                                                                                                |
| `statuses`                  | string\[] | No       | Filtrar por status: `PENDING_REVIEW`, `REVIEWING`, `PATCHING`, `RESOLVED`, `BACKLOG`, `INFORMATIONAL`, `NON_EXPLOITABLE`, `FALSE_POSITIVE`, `ACCEPTED_RISK`                                                                 |
| `scoreLevels`               | string\[] | No       | Filtrar por nível de severidade: `CRITICAL`, `HIGH`, `MEDIUM`, `LOW`, `INFO`                                                                                                                                                |
| `scoreRange`                | object    | No       | Filtrar por faixa numérica de score: `{ min: number, max: number }` (0–100)                                                                                                                                                 |
| `searchQuery`               | string    | No       | Busca em texto livre nos títulos e descrições das issues                                                                                                                                                                    |
| `scanId`                    | string    | No       | Filtrar para issues de um scan específico                                                                                                                                                                                   |
| `languages`                 | string\[] | No       | Filtrar por linguagem de programação                                                                                                                                                                                        |
| `vulnerabilityClasses`      | string\[] | No       | Filtrar por classe de vulnerabilidade (ex.: `SQL Injection`)                                                                                                                                                                |
| `vulnerabilityClassFilters` | object\[] | No       | Filtro estruturado: cada objeto tem `operator` (`equals`, `contains` ou `startsWith`) e `value` (string). Use para correspondência parcial ou por prefixo de classe; `vulnerabilityClasses` é uma lista simples de strings. |
| `codeScanTypes`             | string\[] | No       | Filtrar por tipo de scan                                                                                                                                                                                                    |
| `detectionTypes`            | string\[] | No       | Filtrar por categoria de detecção                                                                                                                                                                                           |
| `repositoryBranches`        | object\[] | No       | Filtrar para repositórios e branches específicos                                                                                                                                                                            |
| `projectId`                 | string    | No       | Filtrar para um projeto específico                                                                                                                                                                                          |
| `sortBy`                    | string    | No       | Campo de ordenação: `createdAt`, `score`, `title`, `repository`, `class`, `file`, `patch`                                                                                                                                   |
| `sortOrder`                 | string    | No       | `asc` ou `desc`                                                                                                                                                                                                             |
| `organizationId`            | string    | No       | Injetado de `ZEROPATH_ORG_ID` quando configurado                                                                                                                                                                            |

<CodeGroup>
  ```json Request theme={null}
  {
    "offset": 0,
    "limit": 25,
    "statuses": ["PENDING_REVIEW"],
    "scoreLevels": ["CRITICAL", "HIGH"],
    "sortBy": "score",
    "sortOrder": "desc"
  }
  ```

  ```json Response theme={null}
  {
    "issues": [
      {
        "id": "issue_abc123",
        "title": "SQL Injection in user lookup",
        "score": 9.2,
        "status": "PENDING_REVIEW",
        "repository": { "id": "repo_123", "name": "backend-api" },
        "vulnerabilityClass": "SQL Injection",
        "createdAt": "2025-10-16T12:34:56Z"
      }
    ],
    "counts": {
      "total": 42,
      "byStatus": { "PENDING_REVIEW": 12, "REVIEWING": 8 }
    },
    "effectiveFilters": { "statuses": ["PENDING_REVIEW"] }
  }
  ```
</CodeGroup>

<h3 id="issues-archive">
  issues.archive
</h3>

Arquive issues para removê-las das visualizações ativas.

| Parameter        | Type      | Required | Descrição                                                                      |
| ---------------- | --------- | -------- | ------------------------------------------------------------------------------ |
| `issueIds`       | string\[] | Yes      | IDs das issues a arquivar                                                      |
| `reason`         | string    | No       | Motivo do arquivamento                                                         |
| `organizationId` | string    | Yes      | Injetado de `ZEROPATH_ORG_ID`; passe explicitamente se não estiver configurado |

<CodeGroup>
  ```json Request theme={null}
  {
    "issueIds": ["issue_123", "issue_456"],
    "reason": "Confirmed duplicate"
  }
  ```

  ```json Response theme={null}
  {
    "ok": true
  }
  ```
</CodeGroup>

<h3 id="issues-unarchive">
  issues.unarchive
</h3>

Restaure issues arquivadas de volta às visualizações ativas.

| Parameter        | Type      | Required | Descrição                                                                      |
| ---------------- | --------- | -------- | ------------------------------------------------------------------------------ |
| `issueIds`       | string\[] | Yes      | IDs das issues a desarquivar                                                   |
| `organizationId` | string    | Yes      | Injetado de `ZEROPATH_ORG_ID`; passe explicitamente se não estiver configurado |

<CodeGroup>
  ```json Request theme={null}
  {
    "issueIds": ["issue_123"]
  }
  ```

  ```json Response theme={null}
  {
    "ok": true
  }
  ```
</CodeGroup>

<h3 id="issues-markfalsepositive">
  issues.markFalsePositive
</h3>

Marque issues como falsos positivos. Remove-as da revisão ativa.

| Parameter        | Type      | Required | Descrição                                                                      |
| ---------------- | --------- | -------- | ------------------------------------------------------------------------------ |
| `issueIds`       | string\[] | Yes      | IDs das issues a marcar                                                        |
| `reason`         | string    | No       | Motivo da determinação                                                         |
| `organizationId` | string    | Yes      | Injetado de `ZEROPATH_ORG_ID`; passe explicitamente se não estiver configurado |

<CodeGroup>
  ```json Request theme={null}
  {
    "issueIds": ["issue_789"],
    "reason": "Input is sanitized by middleware"
  }
  ```

  ```json Response theme={null}
  {
    "ok": true
  }
  ```
</CodeGroup>

<h3 id="issues-marktruepositive">
  issues.markTruePositive
</h3>

Confirme issues como verdadeiros positivos.

| Parameter        | Type      | Required | Descrição                                                                      |
| ---------------- | --------- | -------- | ------------------------------------------------------------------------------ |
| `issueIds`       | string\[] | Yes      | IDs das issues a confirmar                                                     |
| `reason`         | string    | No       | Motivo da confirmação                                                          |
| `organizationId` | string    | Yes      | Injetado de `ZEROPATH_ORG_ID`; passe explicitamente se não estiver configurado |

<CodeGroup>
  ```json Request theme={null}
  {
    "issueIds": ["issue_101", "issue_102"]
  }
  ```

  ```json Response theme={null}
  {
    "ok": true
  }
  ```
</CodeGroup>

<h3 id="issues-updatestatus">
  issues.updateStatus
</h3>

Atualize o status de fluxo de trabalho de uma ou mais issues.

| Parameter        | Type      | Required | Descrição                                                                           |
| ---------------- | --------- | -------- | ----------------------------------------------------------------------------------- |
| `issueIds`       | string\[] | Yes      | IDs das issues a atualizar                                                          |
| `issueStatus`    | string    | Yes      | `PENDING_REVIEW`, `REVIEWING`, `PATCHING`, `RESOLVED`, `BACKLOG` ou `INFORMATIONAL` |
| `reason`         | string    | No       | Motivo da mudança de status                                                         |
| `organizationId` | string    | Yes      | Injetado de `ZEROPATH_ORG_ID`; passe explicitamente se não estiver configurado      |

<Warning>
  O nome do campo é `issueStatus`, não `status`. Usar o nome de campo errado causará um erro de validação.
</Warning>

<CodeGroup>
  ```json Request theme={null}
  {
    "issueIds": ["issue_123"],
    "issueStatus": "RESOLVED",
    "reason": "Fixed in PR #456"
  }
  ```

  ```json Response theme={null}
  {
    "ok": true,
    "updatedCount": 1
  }
  ```
</CodeGroup>

<h3 id="issues-updateseverity">
  issues.updateSeverity
</h3>

Atualize o score de severidade de uma **única** issue.

| Parameter        | Type   | Required | Descrição                                                                      |
| ---------------- | ------ | -------- | ------------------------------------------------------------------------------ |
| `issueId`        | string | Yes      | ID de uma única issue (não um array)                                           |
| `severity`       | number | Yes      | Score de 0 a 10 (suporta uma casa decimal)                                     |
| `reason`         | string | No       | Motivo da mudança de severidade                                                |
| `organizationId` | string | Yes      | Injetado de `ZEROPATH_ORG_ID`; passe explicitamente se não estiver configurado |

<Warning>
  Esta ferramenta recebe um único `issueId` (string), não `issueIds` (array). O campo `severity` é um **número entre 0 e 10**, não um enum de string.
</Warning>

<CodeGroup>
  ```json Request theme={null}
  {
    "issueId": "issue_123",
    "severity": 8.5,
    "reason": "Upgraded after confirming public exposure"
  }
  ```

  ```json Response theme={null}
  {
    "ok": true
  }
  ```
</CodeGroup>

<h3 id="mcp-issues-request-investigation">
  issues.requestInvestigation
</h3>

Solicite uma investigação sob demanda de um achado usando modelos de IA maiores para uma validação de maior confiança.

<Note>
  **REST vs MCP:** A API HTTP pública expõe um único procedimento, `POST /api/v2/issues/requestInvestigation`, com um array `issueIds` (um ou mais IDs). Essa rota usa o mesmo caminho de backend que a ferramenta MCP **issues.requestBulkInvestigation**. Esta ferramenta MCP **issues.requestInvestigation** chama a mutação tRPC de **issue única** — não existe um endpoint REST `POST …/{id}/investigate` correspondente.
</Note>

| Parameter        | Type   | Required | Descrição                                                                                                                                                                                                     |
| ---------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `issueId`        | string | Yes      | ID da issue a investigar                                                                                                                                                                                      |
| `context`        | string | No       | Contexto adicional para orientar a investigação (máx. 20.000 caracteres). Você pode incluir detalhes como a forma de uso do código afetado, contexto de implantação ou preocupações específicas em que focar. |
| `organizationId` | string | No       | Injetado de `ZEROPATH_ORG_ID` quando configurado                                                                                                                                                              |

<CodeGroup>
  ```json Request theme={null}
  {
    "issueId": "issue_123",
    "context": "This endpoint is exposed to unauthenticated users and handles file uploads. Please check whether the path traversal is reachable from the public route."
  }
  ```

  ```json Response theme={null}
  {
    "investigationId": "inv_abc123",
    "status": "created"
  }
  ```
</CodeGroup>

Se já houver uma investigação em andamento para a issue, a resposta retorna a investigação existente com `"status": "already_pending"` em vez de criar uma duplicata.

<h3 id="mcp-issues-request-bulk-investigation">
  issues.requestBulkInvestigation
</h3>

Solicite investigações para várias issues de uma vez.

<Note>
  **Mapeamento REST:** `POST /api/v2/issues/requestInvestigation` com `{ issueIds, context?, organizationId? }`. Esta é a superfície HTTP para investigações em lote; **não** é o mesmo nome de ferramenta MCP que **issues.requestInvestigation** ([ferramenta tRPC de issue única](#mcp-issues-request-investigation) acima).
</Note>

| Parameter        | Type      | Required | Descrição                                                                                                                                                                                                            |
| ---------------- | --------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `issueIds`       | string\[] | Yes      | IDs das issues a investigar                                                                                                                                                                                          |
| `context`        | string    | No       | Contexto adicional para orientar todas as investigações deste lote (máx. 20.000 caracteres). Você pode incluir detalhes como contexto de implantação ou preocupações específicas que se apliquem ao grupo de issues. |
| `organizationId` | string    | No       | Injetado de `ZEROPATH_ORG_ID` quando configurado                                                                                                                                                                     |

<CodeGroup>
  ```json Request theme={null}
  {
    "issueIds": ["issue_123", "issue_456", "issue_789"],
    "context": "These issues were found in our payment processing service which is PCI-scoped. Please prioritize exploitability assessment."
  }
  ```

  ```json Response theme={null}
  {
    "created": 2,
    "skipped": 1,
    "unauthorized": 0
  }
  ```
</CodeGroup>

Issues que já têm uma investigação pendente ou em andamento são ignoradas. Issues que não pertencem à sua organização são contabilizadas como não autorizadas.

<h3 id="issues-getinvestigationstatus">
  issues.getInvestigationStatus
</h3>

Obtenha o resultado de investigação mais recente de uma issue.

| Parameter        | Type   | Required | Descrição                                        |
| ---------------- | ------ | -------- | ------------------------------------------------ |
| `issueId`        | string | Yes      | ID da issue                                      |
| `organizationId` | string | No       | Injetado de `ZEROPATH_ORG_ID` quando configurado |

<CodeGroup>
  ```json Request theme={null}
  {
    "issueId": "issue_123"
  }
  ```

  ```json Response theme={null}
  {
    "id": "inv_abc123",
    "status": "COMPLETED",
    "startedAt": "2026-03-15T10:00:00Z",
    "completedAt": "2026-03-15T10:02:30Z",
    "resultValidated": "CONFIRMED",
    "resultSecurityAssessment": "The SQL injection is exploitable via the search parameter...",
    "error": null,
    "createdAt": "2026-03-15T09:59:00Z"
  }
  ```
</CodeGroup>

Retorna `null` se nenhuma investigação tiver sido solicitada para a issue. O campo `status` pode ser `PENDING`, `PROCESSING`, `COMPLETED` ou `FAILED`.

<h3 id="issues-regeneratepatch">
  issues.regeneratePatch
</h3>

Solicite a geração de um novo patch para uma issue. Use isto quando o patch gerado automaticamente estiver desatualizado, não se aplicar de forma limpa, ou quando você quiser uma nova tentativa depois que o código afetado mudou.

| Parameter        | Type    | Required | Descrição                                                                                |
| ---------------- | ------- | -------- | ---------------------------------------------------------------------------------------- |
| `issueId`        | string  | Yes      | ID da issue para a qual regenerar um patch                                               |
| `force`          | boolean | No       | Quando `true`, sobrepõe o veredito de não corrigível e força uma nova tentativa de patch |
| `organizationId` | string  | No       | Injetado de `ZEROPATH_ORG_ID` quando configurado                                         |

<CodeGroup>
  ```json Request theme={null}
  {
    "issueId": "issue_123"
  }
  ```

  ```json Response theme={null}
  {
    "ok": true
  }
  ```
</CodeGroup>

<h3 id="issues-updatenotes">
  issues.updateNotes
</h3>

Atualize as notas internas de uma issue. Notas são anotações de texto livre visíveis para sua equipe na página de detalhes da issue e são úteis para registrar contexto de triagem, descobertas de investigação ou planos de remediação.

| Parameter        | Type   | Required | Descrição                                                                                                                                         |
| ---------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `issueId`        | string | Yes      | ID da issue a atualizar                                                                                                                           |
| `notes`          | string | Yes      | Conteúdo das notas (substitui quaisquer notas existentes; máx. 5.000 caracteres; passe uma string vazia ou apenas com espaços para limpar a nota) |
| `organizationId` | string | No       | Injetado de `ZEROPATH_ORG_ID` quando configurado                                                                                                  |

<CodeGroup>
  ```json Request theme={null}
  {
    "issueId": "issue_123",
    "notes": "Confirmed reachable via the public /upload endpoint. Assigned to the platform team for remediation in the Q3 sprint."
  }
  ```

  ```json Response theme={null}
  {
    "ok": true
  }
  ```
</CodeGroup>

***

<h2 id="scan-tools">
  Ferramentas de Scan
</h2>

<h3 id="scans-list">
  scans.list
</h3>

Liste scans com **paginação baseada em cursor**. Passe o `nextCursor` de uma resposta anterior para avançar na paginação.

| Parameter        | Type      | Required | Descrição                                                                    |
| ---------------- | --------- | -------- | ---------------------------------------------------------------------------- |
| `cursor`         | object    | No       | Cursor da resposta anterior: `{ createdAt: string, id: string }`             |
| `limit`          | number    | No       | Resultados por página (padrão: 20, máx: 100)                                 |
| `repositoryIds`  | string\[] | No       | Filtrar para repositórios específicos                                        |
| `scanTypes`      | string\[] | No       | `FullScan`, `PrScan` (padrão: ambos)                                         |
| `searchQuery`    | string    | No       | Buscar pelo nome do scan                                                     |
| `projectId`      | string    | No       | Filtrar por ID de projeto                                                    |
| `scoreRange`     | object    | No       | Filtrar por score de vulnerabilidade: `{ min: number, max: number }` (0–100) |
| `showEphemeral`  | boolean   | No       | Incluir scans efêmeros/de CLI (padrão: false)                                |
| `getCounts`      | boolean   | No       | Incluir contagens de vulnerabilidades (padrão: true)                         |
| `organizationId` | string    | No       | Injetado de `ZEROPATH_ORG_ID` quando configurado                             |

<CodeGroup>
  ```json Request (first page) theme={null}
  {
    "limit": 10,
    "repositoryIds": ["repo_123"],
    "scanTypes": ["FullScan"]
  }
  ```

  ```json Request (next page) theme={null}
  {
    "cursor": {
      "createdAt": "2025-10-15T08:00:00Z",
      "id": "scan_xyz"
    },
    "limit": 10
  }
  ```

  ```json Response theme={null}
  {
    "scans": [
      {
        "scanId": "scan_abc123",
        "repositoryId": "repo_123",
        "repositoryName": "backend-api",
        "status": "Finished",
        "codeScanType": "FullScan",
        "createdAt": "2025-10-16T12:00:00Z",
        "scanFinishedAt": "2025-10-16T12:08:00Z",
        "issueCounts": {
          "PENDING_REVIEW": 3,
          "RESOLVED": 12,
          "newOpen": 2
        }
      }
    ],
    "nextCursor": { "createdAt": "2025-10-15T08:00:00Z", "id": "scan_xyz" },
    "hasMore": true,
    "isFirstPage": true
  }
  ```
</CodeGroup>

<h3 id="scans-get">
  scans.get
</h3>

Obtenha os detalhes de um scan específico.

| Parameter        | Type   | Required | Descrição                                        |
| ---------------- | ------ | -------- | ------------------------------------------------ |
| `scanId`         | string | Yes      | ID do scan                                       |
| `organizationId` | string | No       | Injetado de `ZEROPATH_ORG_ID` quando configurado |

<CodeGroup>
  ```json Request theme={null}
  {
    "scanId": "scan_abc123"
  }
  ```

  ```json Response theme={null}
  {
    "scanId": "scan_abc123",
    "repositoryId": "repo_123",
    "repositoryName": "backend-api",
    "status": "Finished",
    "codeScanType": "FullScan",
    "scanTargetBranch": "main",
    "finished": true,
    "createdAt": "2025-10-16T12:00:00Z",
    "scanFinishedAt": "2025-10-16T12:08:00Z",
    "issueCounts": {
      "PENDING_REVIEW": 3,
      "REVIEWING": 1,
      "RESOLVED": 12,
      "newOpen": 2,
      "open": 5
    },
    "scanType": "code"
  }
  ```
</CodeGroup>

<h3 id="scans-rescanpr">
  scans.rescanPR
</h3>

Dispare um novo scan de um pull request ou merge request. Passe o ID de um scan de PR anterior e a plataforma buscará o pull request novamente e criará novo(s) scan(s). Suporta PRs do GitHub e MRs do GitLab.

| Parameter        | Type    | Required | Descrição                                                                                                 |
| ---------------- | ------- | -------- | --------------------------------------------------------------------------------------------------------- |
| `scanId`         | string  | Yes      | ID de um scan de PR anterior a reescanear                                                                 |
| `force`          | boolean | No       | Quando true, ignora a detecção de duplicatas e reescaneia mesmo que já exista um scan para o commit atual |
| `organizationId` | string  | No       | Injetado de `ZEROPATH_ORG_ID` quando configurado                                                          |

<CodeGroup>
  ```json Request theme={null}
  {
    "scanId": "scan_abc123",
    "force": false
  }
  ```

  ```json Response theme={null}
  {
    "outcome": "scans_created",
    "message": "Created 1 new scan(s)",
    "scanCount": 1
  }
  ```
</CodeGroup>

O campo `outcome` indica o que aconteceu:

| Outcome               | Significado                                                             |
| --------------------- | ----------------------------------------------------------------------- |
| `scans_created`       | Novo(s) scan(s) criado(s) com sucesso                                   |
| `skipped_duplicate`   | Já existe um scan para o commit atual (use `force: true` para sobrepor) |
| `skipped_not_enabled` | O escaneamento de PRs não está habilitado para este repositório         |
| `skipped_no_targets`  | Nenhum alvo de scan válido foi encontrado para o pull request           |
| `closed`              | O pull request está fechado                                             |
| `error`               | Ocorreu um erro durante o novo scan                                     |

***

<h2 id="repository-tools">
  Ferramentas de Repositório
</h2>

<h3 id="repositories-list">
  repositories.list
</h3>

Liste repositórios com **paginação baseada em cursor** (cursor em string).

| Parameter        | Type    | Required | Descrição                                                               |
| ---------------- | ------- | -------- | ----------------------------------------------------------------------- |
| `cursor`         | string  | No       | Cursor do `nextCursor` da resposta anterior                             |
| `limit`          | integer | No       | Resultados por página (padrão: 20, máx: 100)                            |
| `sortBy`         | string  | No       | `name` ou `issues` (padrão: `name`)                                     |
| `sortDirection`  | string  | No       | `asc` ou `desc` (padrão: `asc`)                                         |
| `getCounts`      | boolean | No       | Incluir contagens de issues (padrão: true, pode impactar a performance) |
| `organizationId` | string  | No       | Injetado de `ZEROPATH_ORG_ID` quando configurado                        |

<CodeGroup>
  ```json Request theme={null}
  {
    "limit": 50,
    "sortBy": "issues",
    "sortDirection": "desc",
    "getCounts": true
  }
  ```

  ```json Response theme={null}
  {
    "items": [
      {
        "id": "repo_123",
        "projectId": "proj_456",
        "name": "backend-api",
        "defaultScanTargetBranch": "main",
        "tags": [{ "id": "tag_1", "name": "production", "priority": 1 }],
        "issueCounts": {
          "newOpen": 5,
          "open": 12,
          "patched": 30,
          "archived": 2,
          "falsePositive": 3,
          "patchable": 4,
          "closed": 8,
          "silenced": 1
        },
        "vcs": {
          "vcsType": "github",
          "url": "https://github.com/acme/backend-api",
          "linkActive": true
        }
      }
    ],
    "nextCursor": "eyJuYW1lIjoiYmFja2VuZC1hcGkifQ",
    "hasMore": true,
    "totalCount": 87
  }
  ```
</CodeGroup>

***

<h2 id="code-inspection-tools">
  Ferramentas de Inspeção de Código
</h2>

Estas ferramentas permitem navegar e buscar código-fonte diretamente em repositórios GitHub e GitLab conectados, sem precisar cloná-los.

<h3 id="code-search">
  code.search
</h3>

Busque código dentro de um repositório.

| Parameter        | Type    | Required | Descrição                                                                               |
| ---------------- | ------- | -------- | --------------------------------------------------------------------------------------- |
| `repositoryId`   | string  | Yes      | ID do repositório onde buscar                                                           |
| `query`          | string  | Yes      | Consulta de busca (1–512 caracteres)                                                    |
| `ref`            | string  | No       | Ref do Git (branch/tag/commit). Somente GitLab — o GitHub sempre busca na branch padrão |
| `pathPrefix`     | string  | No       | Restringir os resultados a uma subárvore de diretório                                   |
| `limit`          | integer | No       | Máximo de resultados (padrão: 10, máx: 50)                                              |
| `organizationId` | string  | No       | Injetado de `ZEROPATH_ORG_ID` quando configurado                                        |

<CodeGroup>
  ```json Request theme={null}
  {
    "repositoryId": "repo_123",
    "query": "password",
    "pathPrefix": "src/auth",
    "limit": 5
  }
  ```

  ```json Response theme={null}
  {
    "provider": "github",
    "repositoryId": "repo_123",
    "query": "password",
    "ref": null,
    "pathPrefix": "src/auth",
    "hasNextPage": true,
    "totalMatches": 12,
    "items": [
      {
        "path": "src/auth/login.ts",
        "line": 42,
        "preview": "const hashedPassword = await bcrypt.hash(password, 10);",
        "url": "https://github.com/acme/backend/blob/main/src/auth/login.ts#L42"
      }
    ]
  }
  ```
</CodeGroup>

<h3 id="code-read">
  code.read
</h3>

Leia o conteúdo de um arquivo em um repositório.

| Parameter        | Type    | Required | Descrição                                        |
| ---------------- | ------- | -------- | ------------------------------------------------ |
| `repositoryId`   | string  | Yes      | ID do repositório                                |
| `path`           | string  | Yes      | Caminho do arquivo dentro do repositório         |
| `ref`            | string  | No       | Ref do Git (branch/tag/commit)                   |
| `startLine`      | integer | No       | Primeira linha a retornar (baseada em 1)         |
| `endLine`        | integer | No       | Última linha a retornar (deve ser >= startLine)  |
| `organizationId` | string  | No       | Injetado de `ZEROPATH_ORG_ID` quando configurado |

<CodeGroup>
  ```json Request theme={null}
  {
    "repositoryId": "repo_123",
    "path": "src/auth/login.ts",
    "startLine": 40,
    "endLine": 50
  }
  ```

  ```json Response theme={null}
  {
    "provider": "github",
    "repositoryId": "repo_123",
    "path": "src/auth/login.ts",
    "ref": "main",
    "startLine": 40,
    "endLine": 50,
    "totalLines": 120,
    "content": "...",
    "byteLength": 450,
    "truncatedByLineRange": true,
    "truncatedByByteLimit": false,
    "url": "https://github.com/acme/backend/blob/main/src/auth/login.ts"
  }
  ```
</CodeGroup>

As respostas são limitadas a 1.000 linhas e 200 KB. As flags `truncatedByLineRange` e `truncatedByByteLimit` indicam se a resposta foi truncada.

<h3 id="code-listfiles">
  code.listFiles
</h3>

Liste arquivos e diretórios dentro de um caminho do repositório.

| Parameter        | Type    | Required | Descrição                                          |
| ---------------- | ------- | -------- | -------------------------------------------------- |
| `repositoryId`   | string  | Yes      | ID do repositório                                  |
| `path`           | string  | No       | Caminho do diretório (padrão: raiz do repositório) |
| `ref`            | string  | No       | Ref do Git (branch/tag/commit)                     |
| `cursor`         | string  | No       | Cursor de paginação (somente GitLab)               |
| `limit`          | integer | No       | Máximo de resultados (padrão: 100, máx: 200)       |
| `organizationId` | string  | No       | Injetado de `ZEROPATH_ORG_ID` quando configurado   |

<CodeGroup>
  ```json Request theme={null}
  {
    "repositoryId": "repo_123",
    "path": "src/auth"
  }
  ```

  ```json Response theme={null}
  {
    "provider": "github",
    "repositoryId": "repo_123",
    "ref": "main",
    "path": "src/auth",
    "hasMore": false,
    "nextCursor": null,
    "items": [
      { "path": "src/auth/login.ts", "name": "login.ts", "type": "file", "size": 2048 },
      { "path": "src/auth/middleware", "name": "middleware", "type": "dir", "size": null }
    ]
  }
  ```
</CodeGroup>

<Note>
  A inspeção de código atualmente é suportada para repositórios **GitHub** e **GitLab**. Bitbucket, Git genérico e repositórios enviados por upload ainda não são suportados.
</Note>

***

<h2 id="rule-tools">
  Ferramentas de Regras
</h2>

<h3 id="rules-list">
  rules.list
</h3>

Liste regras de segurança personalizadas. Usa **paginação baseada em offset**.

| Parameter        | Type    | Required | Descrição                                        |
| ---------------- | ------- | -------- | ------------------------------------------------ |
| `offset`         | integer | No       | Índice inicial (padrão: 0)                       |
| `limit`          | integer | No       | Resultados por página (padrão: 20, máx: 100)     |
| `repositoryId`   | string  | No       | Filtrar regras por repositório                   |
| `organizationId` | string  | No       | Injetado de `ZEROPATH_ORG_ID` quando configurado |

<CodeGroup>
  ```json Request theme={null}
  {
    "offset": 0,
    "limit": 25
  }
  ```

  ```json Response theme={null}
  {
    "rules": [
      {
        "id": "rule_xyz789",
        "name": "Detect unsafe eval",
        "rule": "Detect any use of eval() on user input",
        "globPattern": "**/*.js",
        "sourceTypes": ["FILE_HANDLER"],
        "repositoryIds": ["repo_123"],
        "tags": [{ "id": "tag_1", "name": "critical-rules" }],
        "createdAt": "2025-09-01T00:00:00Z",
        "updatedAt": "2025-10-10T12:00:00Z"
      }
    ],
    "totalCount": 8,
    "hasMore": false,
    "nextOffset": null
  }
  ```
</CodeGroup>

<h3 id="rules-get">
  rules.get
</h3>

Obtenha os detalhes de uma regra específica, incluindo os nomes dos repositórios associados.

| Parameter        | Type   | Required | Descrição                                        |
| ---------------- | ------ | -------- | ------------------------------------------------ |
| `ruleId`         | string | Yes      | ID da regra                                      |
| `organizationId` | string | No       | Injetado de `ZEROPATH_ORG_ID` quando configurado |

<CodeGroup>
  ```json Request theme={null}
  {
    "ruleId": "rule_xyz789"
  }
  ```

  ```json Response theme={null}
  {
    "id": "rule_xyz789",
    "name": "Detect unsafe eval",
    "rule": "Detect any use of eval() on user input",
    "globPattern": "**/*.js",
    "sourceTypes": ["FILE_HANDLER"],
    "repositories": [
      { "id": "repo_123", "name": "backend-api" }
    ],
    "tags": [{ "id": "tag_1", "name": "critical-rules" }],
    "createdAt": "2025-09-01T00:00:00Z",
    "updatedAt": "2025-10-10T12:00:00Z"
  }
  ```
</CodeGroup>

<h3 id="rules-create">
  rules.create
</h3>

Crie uma regra de segurança personalizada.

| Parameter        | Type      | Required | Descrição                                                                                                               |
| ---------------- | --------- | -------- | ----------------------------------------------------------------------------------------------------------------------- |
| `name`           | string    | Yes      | Nome da regra                                                                                                           |
| `rule`           | string    | Yes      | Definição da regra em linguagem natural                                                                                 |
| `globPattern`    | string    | No       | Padrão de arquivos (padrão: `**/*`)                                                                                     |
| `sourceTypes`    | string\[] | No       | `HTTP_HANDLER`, `FILE_HANDLER`, `STDIN_HANDLER`, `BROWSER_DATA`, `WEBSOCKET`, `SOCKET`, `CLI_ARGUMENT`, `MOBILE_INPUTS` |
| `repositoryIds`  | string\[] | No       | Limitar a repositórios específicos                                                                                      |
| `tagIds`         | string\[] | No       | IDs de tags a associar à regra                                                                                          |
| `organizationId` | string    | No       | Injetado de `ZEROPATH_ORG_ID` quando configurado                                                                        |

<CodeGroup>
  ```json Request theme={null}
  {
    "name": "Detect unsafe eval",
    "rule": "Detect any use of eval() on user input",
    "globPattern": "**/*.{js,ts}",
    "sourceTypes": ["HTTP_HANDLER", "FILE_HANDLER"],
    "repositoryIds": ["repo_123"],
    "tagIds": ["tag_1"]
  }
  ```

  ```json Response theme={null}
  {
    "id": "rule_xyz789",
    "name": "Detect unsafe eval",
    "rule": "Detect any use of eval() on user input",
    "globPattern": "**/*.{js,ts}",
    "sourceTypes": ["HTTP_HANDLER", "FILE_HANDLER"],
    "repositoryIds": ["repo_123"],
    "tags": [{ "id": "tag_1", "name": "critical-rules" }],
    "createdAt": "2025-10-16T14:00:00Z",
    "updatedAt": "2025-10-16T14:00:00Z"
  }
  ```
</CodeGroup>

<h3 id="rules-update">
  rules.update
</h3>

Atualize uma regra existente. Apenas os campos que você incluir serão modificados.

| Parameter        | Type      | Required | Descrição                                        |
| ---------------- | --------- | -------- | ------------------------------------------------ |
| `ruleId`         | string    | Yes      | ID da regra a atualizar                          |
| `name`           | string    | No       | Nome atualizado                                  |
| `rule`           | string    | No       | Definição atualizada                             |
| `globPattern`    | string    | No       | Padrão de arquivos atualizado                    |
| `sourceTypes`    | string\[] | No       | Tipos de fonte atualizados                       |
| `repositoryIds`  | string\[] | No       | Escopo de repositórios atualizado                |
| `tagIds`         | string\[] | No       | Associações de tags atualizadas                  |
| `organizationId` | string    | No       | Injetado de `ZEROPATH_ORG_ID` quando configurado |

<CodeGroup>
  ```json Request theme={null}
  {
    "ruleId": "rule_xyz789",
    "name": "Detect unsafe eval (updated)",
    "globPattern": "**/*.{js,ts,jsx,tsx}"
  }
  ```

  ```json Response theme={null}
  {
    "id": "rule_xyz789",
    "name": "Detect unsafe eval (updated)",
    "rule": "Detect any use of eval() on user input",
    "globPattern": "**/*.{js,ts,jsx,tsx}",
    "sourceTypes": ["HTTP_HANDLER", "FILE_HANDLER"],
    "repositoryIds": ["repo_123"],
    "tags": [{ "id": "tag_1", "name": "critical-rules" }],
    "createdAt": "2025-10-16T14:00:00Z",
    "updatedAt": "2025-10-16T15:30:00Z"
  }
  ```
</CodeGroup>

<h3 id="rules-delete">
  rules.delete
</h3>

Exclua uma regra personalizada.

| Parameter        | Type   | Required | Descrição                                        |
| ---------------- | ------ | -------- | ------------------------------------------------ |
| `ruleId`         | string | Yes      | ID da regra a excluir                            |
| `organizationId` | string | No       | Injetado de `ZEROPATH_ORG_ID` quando configurado |

<CodeGroup>
  ```json Request theme={null}
  {
    "ruleId": "rule_xyz789"
  }
  ```

  ```json Response theme={null}
  {
    "success": true
  }
  ```
</CodeGroup>

***

<h2 id="common-workflows">
  Fluxos de Trabalho Comuns
</h2>

<AccordionGroup>
  <Accordion title="Triar novas issues">
    1. **Liste as issues pendentes** — chame `issues.list` com `statuses: ["PENDING_REVIEW"]` ordenado por `score` decrescente.
    2. **Revise cada issue** — peça ao seu assistente de IA para resumir a vulnerabilidade e o código afetado.
    3. **Classifique** — use `issues.markTruePositive` ou `issues.markFalsePositive` com um motivo.
    4. **Atualize o status** — mova as issues confirmadas para `REVIEWING` ou `PATCHING` com `issues.updateStatus`.
    5. **Ajuste a severidade** — se o score atribuído automaticamente não corresponder à sua avaliação, use `issues.updateSeverity` com um valor de 0 a 10.
  </Accordion>

  <Accordion title="Criar regras personalizadas">
    1. **Liste as regras existentes** — chame `rules.list` para ver o que já está configurado.
    2. **Crie uma regra** — use `rules.create` com uma descrição em linguagem natural. O scanner da ZeroPath fará a correspondência desse padrão em scans futuros.
    3. **Defina o escopo** — use `repositoryIds` para limitar a regra a repositórios específicos, `globPattern` para limitar a tipos de arquivo específicos e `sourceTypes` para direcionar pontos de entrada específicos.
    4. **Adicione tags** — use `tagIds` para associar a regra a tags para fins de organização.
    5. **Itere** — atualize com `rules.update` conforme você refina o padrão.
  </Accordion>

  <Accordion title="Investigar resultados de scans">
    1. **Liste os scans recentes** — chame `scans.list` para ver o histórico de scans. Filtre com `scanTypes: ["FullScan"]` para scans agendados ou `["PrScan"]` para scans de PR.
    2. **Obtenha os detalhes do scan** — use `scans.get` com um `scanId` específico para ver status, branch e contagens de issues.
    3. **Aprofunde-se nos achados** — chame `issues.list` com um filtro de `scanId` para ver apenas as issues daquele scan.
  </Accordion>
</AccordionGroup>

***

<h2 id="error-handling">
  Tratamento de Erros
</h2>

Chamadas de ferramenta que falham retornam erros estruturados:

<AccordionGroup>
  <Accordion title="BAD_REQUEST — Entrada inválida">
    Retornado quando a validação da entrada falha. Verifique o array `data.issues` para detalhes por campo.

    ```json theme={null}
    {
      "error": {
        "code": "BAD_REQUEST",
        "message": "Input validation failed",
        "data": {
          "issues": [
            { "path": "issueIds", "message": "Required" }
          ]
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="UNAUTHORIZED — Autenticação inválida ou ausente">
    Verifique se `ZEROPATH_TOKEN_ID` e `ZEROPATH_TOKEN_SECRET` estão corretos e se a chave de API está ativa.
  </Accordion>

  <Accordion title="FORBIDDEN — Permissões insuficientes">
    A chave de API não tem as permissões necessárias para esta operação. Verifique o papel da sua chave em [ZeroPath Settings](https://zeropath.com/app/settings/api).
  </Accordion>

  <Accordion title="NOT_FOUND — O recurso não existe">
    O ID especificado (issue, scan, regra ou repositório) não foi encontrado. Verifique se o ID está correto e pertence à sua organização.
  </Accordion>
</AccordionGroup>

***

<h2 id="tips">
  Dicas
</h2>

* **Pagine** — sempre pagine conjuntos grandes de resultados. Use `offset`/`limit` para issues e regras, `cursor`/`limit` para scans e repositórios.
* **Filtre cedo** — use filtros de status, severidade e repositório para reduzir o tamanho da resposta.
* **Atualize em lote** — passe múltiplos IDs em uma única chamada ao arquivar, marcar ou atualizar status.
* **Inclua motivos** — adicione um `reason` ao arquivar, marcar falsos/verdadeiros positivos ou mudar status, para fins de trilha de auditoria.
* **Defina o contexto da organização** — configure `ZEROPATH_ORG_ID` durante a [instalação](/pt/mcp/installation) para que o servidor injete `organizationId` automaticamente em cada requisição.