# mcp-gs1br

Model Context Protocol (MCP) server for the **GS1 Brasil — Verified by GS1** API.

Consulta dados autoritativos de produtos a partir do GTIN (EAN-8, UPC-A, EAN-13, ITF-14): marca, descrição, GPC, NCM, CEST, imagens, peso, dimensões, licenciado. Cobre a base **nacional** (Cadastro Nacional de Produtos – CNP) e a base **internacional** (GS1 Registry Platform).

## Pré-requisitos

1. Ser associado GS1 Brasil.
2. Aceitar o termo de uso em <https://verifiedbygs1.gs1br.org/>.
3. Solicitar liberação de acesso em <https://fs8.formsite.com/gsurvey/cfw75k23hq/index>.
4. Receber da GS1 Brasil seu `client_id` e `client_secret`.

Depois disso você usa o mesmo `username`/`password` do portal CNP / Verified by GS1 como credenciais OAuth.

## Instalação

```bash
cd mcp-gs1br
npm install
npm run build
```

## Configuração

Exporte as credenciais como variáveis de ambiente:

| Variável              | Obrigatória | Descrição                                    |
| --------------------- | ----------- | -------------------------------------------- |
| `GS1BR_CLIENT_ID`     | sim         | Client ID recebido da GS1 Brasil             |
| `GS1BR_CLIENT_SECRET` | sim         | Client Secret recebido da GS1 Brasil         |
| `GS1BR_USERNAME`      | sim         | E-mail do usuário CNP / Verified by GS1      |
| `GS1BR_PASSWORD`      | sim         | Senha do mesmo usuário                       |
| `GS1BR_ENV`           | não         | `production` (padrão) ou `homologacao`       |

### Registrar como MCP no Claude Code

`.claude/mcp.json` ou equivalente:

```json
{
  "mcpServers": {
    "gs1br": {
      "command": "node",
      "args": ["/caminho/absoluto/para/mcp-gs1br/dist/index.js"],
      "env": {
        "GS1BR_CLIENT_ID": "...",
        "GS1BR_CLIENT_SECRET": "...",
        "GS1BR_USERNAME": "seu@email",
        "GS1BR_PASSWORD": "...",
        "GS1BR_ENV": "production"
      }
    }
  }
}
```

### Claude Desktop

No `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "gs1br": {
      "command": "node",
      "args": ["/caminho/absoluto/para/mcp-gs1br/dist/index.js"],
      "env": { "GS1BR_CLIENT_ID": "...", "GS1BR_CLIENT_SECRET": "...", "GS1BR_USERNAME": "...", "GS1BR_PASSWORD": "..." }
    }
  }
}
```

## Tools expostas

### `gs1_validate_check_digit`

Valida localmente o dígito verificador (módulo 10) de um GTIN. Não consome a API. Útil para filtrar leituras ruins antes de gastar quota.

```json
{ "gtin": "7898357416086" }
```

### `gs1_verify_gtin`

Consulta um GTIN e retorna um **resumo normalizado**:

```json
{
  "gtin": "7898357416086",
  "found": true,
  "source": "national",
  "status": "Válido",
  "brand": "GS1 Brasil",
  "description": "GS1 Brasil Tênis de Corrida Style Azul com Branco Tamanho 37",
  "gpcCategoryCode": "10001070",
  "gpcCategoryName": "Calçados Esportivos - Uso Geral",
  "ncm": "0000.00.00",
  "cest": "28.059.00",
  "imageUrls": ["https://cnp30blob.blob.core.windows.net/cnp3files/..."],
  "grossWeight": { "value": 2.8, "unitCode": "KGM" },
  "netWeight":   { "value": 2.8, "unitCode": "KGM" },
  "netContent":  { "value": 1,   "unitCode": "EA"  },
  "dimensions": {
    "height": { "value": 40, "unitCode": "CMT" },
    "width":  { "value": 17, "unitCode": "CMT" },
    "depth":  { "value": 10, "unitCode": "CMT" }
  },
  "licensee": {
    "name": "GS1 BRASIL - ASSOCIACAO BRASILEIRA DE AUTOMACAO",
    "licenseType": "GCP",
    "managingOrganization": "GS1 Brasil"
  },
  "syncInformationCCG": true,
  "raw": { ... }
}
```

Campos podem vir vazios dependendo do perfil de consulta contratado (Verificação, Verificação + Nacional, Verificação + Internacional, Nacional + Internacional).

### `gs1_verify_gtin_raw`

Mesmo que acima, mas retorna o JSON cru da API GS1 (array com `dadosInternacionais`, `dadosNacionais`, `verificacao`).

### `gs1_enrich_many`

Enriquece um lote de até 25 GTINs sequencialmente. Filtra localmente dígitos verificadores inválidos para economizar requests.

```json
{ "gtins": ["7898357416086", "4006381333931", "..."] }
```

## Por baixo dos panos

- **OAuth 2.0 password grant** contra `POST {host}/oauth/access-token`, header `Authorization: Basic base64(client_id:client_secret)`, body JSON `{grant_type, username, password}`.
- **Token cache** em memória, TTL 3h (expires_in = 10800). Reautenticação automática em 401/403.
- **Consulta**: `GET {host}/provider/v2/verified?gtin={GTIN}` com headers `client_id` e `access_token`.
- **Hosts**:
  - `https://api.gs1br.org` (produção)
  - `https://api-hml.gs1br.org` (homologação)

## Erros comuns

| Código HTTP | Situação                                   |
| ----------- | ------------------------------------------ |
| 200         | Sucesso                                    |
| 400         | Requisição inválida                        |
| 403         | Usuário sem autorização para o recurso     |
| 404         | GTIN não encontrado                        |
| 500         | Erro interno GS1                           |

Códigos de negócio (`returnCode` / `returnCodeDescription`) retornados dentro do payload quando o GTIN é internacional — vide manual oficial R1.3.

## Referências

- Portal API GS1 Brasil: <https://portalapi.gs1br.org/>
- Manual R1.3 (PDF): [Manual de Uso da API Verified by GS1 R1.3](https://gs1portalstoragecdncms.blob.core.windows.net/strapi/strapi-assets/Manual_do_Usuario_API_Verified_by_GS_1_R1_31_1_a534922ec8.pdf)
- Manual CNP (PDF): [API de Cadastro e Consulta CNP v3](https://gs1portalstoragecdncms.blob.core.windows.net/strapi/strapi-assets/API_de_Cadastro_e_Consulta_CNP_v3_a58fa2d310.pdf)

## Licença

MIT.