# MCP do Facelocal

Conecte seu assistente de IA à documentação do Facelocal. O servidor MCP
(Model Context Protocol) permite consultar os guias, pesquisar APIs e ler os
exemplos de integração em português ou inglês.

## Conexão

**URL do servidor**

```text
https://facelocal.dev/api/mcp
```

- Transporte: **Streamable HTTP**.
- Acesso público, somente leitura. Não exige chave nem login.
- Os documentos acompanham a versão do SDK disponibilizada no site.

## Cursor

Adicione esta configuração ao arquivo `.cursor/mcp.json` do seu projeto.
Se o arquivo já existir, acrescente `facelocal` ao objeto `mcpServers`, sem
substituir os outros servidores.

```json
{
  "mcpServers": {
    "facelocal": {
      "url": "https://facelocal.dev/api/mcp"
    }
  }
}
```

Ative o servidor nas configurações de MCP do Cursor e confirme a conexão.

## VS Code

Adicione esta configuração ao arquivo `.vscode/mcp.json` do seu projeto.
Se o arquivo já existir, acrescente `facelocal` ao objeto `servers`.

```json
{
  "servers": {
    "facelocal": {
      "type": "http",
      "url": "https://facelocal.dev/api/mcp"
    }
  }
}
```

Use o comando **MCP: List Servers**, selecione `facelocal` e inicie o servidor.
Confirme a confiança no servidor quando o editor solicitar.

## Ferramentas disponíveis

| Ferramenta | Uso |
| --- | --- |
| `get_sdk_info` | Consultar a versão do SDK e os guias disponíveis. |
| `search_documentation` | Buscar trechos e seções da documentação. |
| `read_documentation` | Ler um guia ou uma seção, com paginação. |

Todas as ferramentas aceitam `locale`: `pt-BR` ou `en`. O padrão é `pt-BR`.

Os guias usam os identificadores `visao-geral`, `integracao`, `resultado-json`,
`mcp` e `licencas`, nos dois idiomas.

As buscas retornam links e identificadores de seção. Passe o identificador em
`section` para ler apenas aquele trecho. Para continuar uma leitura paginada,
use o valor de `nextLine` como `startLine`.

## Exemplo de uso

No chat do seu editor:

> Use o MCP facelocal para consultar a integração de Prova de Vida e Face Match no meu app React Native.

Exemplo dos argumentos de busca:

```json
{
  "query": "runFaceLocalVerification",
  "locale": "pt-BR",
  "limit": 5
}
```

Exemplo dos argumentos de leitura:

```json
{
  "slug": "integracao",
  "locale": "pt-BR",
  "startLine": 1,
  "maxLines": 120
}
```

Os guias também estão disponíveis como recursos MCP, por exemplo:

```text
facelocal://docs/pt-BR/integracao
facelocal://docs/en/integracao
```

## Escopo e privacidade

O MCP consulta apenas a documentação pública. Não executa Prova de Vida ou
Face Match, não recebe imagens, não acessa a galeria e não processa dados
biométricos. Essas operações continuam no SDK integrado ao aplicativo.

O MCP não libera o código-fonte pago, não valida cupons, não realiza pagamentos
e não acessa arquivos do projeto do visitante.

## Solução de problemas

- Use um cliente compatível com **Streamable HTTP**. Este servidor não oferece
  o transporte SSE legado.
- A URL não é uma página web. Abrir o endereço no navegador retorna HTTP 405;
  configure-o no cliente MCP, que envia requisições POST.
- HTTP 429 indica excesso de requisições. Aguarde o tempo do cabeçalho
  `Retry-After` antes de tentar novamente.
- Se o editor não listar as ferramentas, reinicie a conexão e confira a URL.

Para integrar o SDK, consulte o [guia de integração](INTEGRACAO.md) e o
[contrato do resultado JSON](RESULTADO-JSON.md).