npm package: @marcelocorrea/mcp-clint
Description: MCP server for Clint API integration
Author: Marcelo Correa
Latest version: 1.0.0

# MCP Clint - Servidor de Protocolo de Contexto de Modelo

[![npm version](https://img.shields.io/npm/v/@marcelocorrea/mcp-clint.svg)](https://www.npmjs.com/package/@marcelocorrea/mcp-clint)
[![npm downloads](https://img.shields.io/npm/dm/@marcelocorrea/mcp-clint.svg)](https://www.npmjs.com/package/@marcelocorrea/mcp-clint)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js Version](https://img.shields.io/node/v/@marcelocorrea/mcp-clint.svg)](https://nodejs.org)

O MCP Clint é um servidor do Protocolo de Contexto de Modelo (MCP) que fornece integração com a plataforma Clint CRM. Ele atua como uma ponte entre modelos de IA e a API Clint, permitindo que assistentes de IA realizem operações em recursos Clint como contatos, negócios, organizações, tags, grupos, usuários, origens e itens de status perdidos.

## Índice

1. [Visão Geral](#visão-geral)
2. [Recursos Disponíveis](#recursos-disponíveis)
3. [Configuração no Claude Code](#configuração-no-claude-code)
4. [Instalação e Configuração](#instalação-e-configuração)
5. [Variáveis de Ambiente](#variáveis-de-ambiente)
6. [Exemplos de Uso](#exemplos-de-uso)

## Visão Geral

O servidor foi desenvolvido em TypeScript e utiliza o SDK oficial do MCP para implementar um serviço que se comunica com a API Clint via requisições HTTP. Ele segue uma arquitetura baseada em ferramentas onde diferentes operações são expostas como ferramentas chamáveis que modelos de IA podem usar.

## Recursos Disponíveis

O servidor expõe as seguintes ferramentas para que modelos de IA possam interagir:

### 1. Ferramenta de Contatos
- **Operações**: list, get, create, update, delete, add_tags, remove_tag
- **Parâmetros**: Suporta várias opções de filtro (limite, deslocamento, nome, e-mail, etc.) e detalhes de contato

### 2. Ferramenta de Negócios
- **Operações**: list, get, create, update, delete
- **Parâmetros**: Dados específicos de negócios e opções de filtragem

### 3. Ferramenta de Organizações
- **Operações**: get, update
- **Parâmetros**: ID da organização e campos de atualização

### 4. Ferramenta de Tags
- **Operações**: list, get, create, delete
- **Parâmetros**: Detalhes das tags e opções de filtragem

### 5. Ferramenta de Grupos
- **Operações**: list, get
- **Parâmetros**: Opções de filtragem de grupos

### 6. Ferramenta de Usuários
- **Operações**: list, get
- **Parâmetros**: Opções de filtragem de usuários

### 7. Ferramenta de Origens
- **Operações**: list, get
- **Parâmetros**: Opções de filtragem de origens

### 8. Ferramenta de Status Perdidos
- **Operações**: list, get
- **Parâmetros**: Opções de filtragem de status perdidos

### 9. Ferramenta de Conta
- **Operações**: list_fields
- **Parâmetros**: Opções de listagem de campos da conta

## Configuração no Claude Code

O Claude Code suporta a integração com servidores MCP para estender as capacidades dos assistentes de IA. Para configurar o MCP Clint com o Claude, siga estes passos:

### 1. Instalação via NPM

Você pode instalar o pacote do MCP Clint globalmente:

```bash
npm install -g @marcelocorrea/mcp-clint
```

Depois de instalado, você pode executar o servidor MCP:

```bash
CLINT_API_TOKEN=seu_token_aqui mcp-clint
```

### 2. Execução Direta do Arquivo na Máquina

Se preferir executar o servidor a partir do código fonte:

1. Clone o repositório:
```bash
git clone https://github.com/seu-usuario/mcp-clint.git
cd mcp-clint
```

2. Instale as dependências:
```bash
npm install
```

3. Execute o servidor em modo de desenvolvimento:
```bash
CLINT_API_TOKEN=seu_token_aqui npm run dev
```

### Passos para Configuração no Claude:

1. **Instale o Claude Code** em seu ambiente de desenvolvimento (VS Code, JetBrains, etc.)

2. **Configure o Servidor MCP**:
   - No Claude Code, vá até as configurações de MCP
   - Adicione um novo servidor MCP
   - Se você instalou via NPM, use o comando: `mcp-clint`
   - Se estiver executando localmente, use o caminho para executar: `npm run dev` no diretório do projeto

3. **Defina as variáveis de ambiente**:
   - Certifique-se de que a variável `CLINT_API_TOKEN` esteja definida com seu token de API Clint

4. **Teste a conexão**:
   - Após configurar, o Claude Code deve ser capaz de se comunicar com o servidor MCP Clint
   - Você poderá usar os recursos Clint diretamente no assistente de IA

## Instalação e Configuração

### Pré-requisitos
- Node.js >= 18
- Um token de API Clint válido

### Instalação
```bash
npm install
```

### Compilação
```bash
npm run build
```
Isso compila o código TypeScript para JavaScript no diretório `dist`.

### Execução em Desenvolvimento
```bash
CLINT_API_TOKEN=seu_token_aqui npm run dev
```

### Execução em Produção
```bash
npm start
```
Isso executa o servidor JavaScript compilado.

## Variáveis de Ambiente

- `CLINT_API_TOKEN`: Obrigatório. Seu token de autenticação da API Clint.

## Publicação e Distribuição

Este pacote está publicado no NPM como `@marcelocorrea/mcp-clint`. Para mais informações sobre publicação e desenvolvimento, consulte a documentação técnica no arquivo `QWEN.md` ou `CLAUDE.md`.

### Instalação

```bash
# Instalação global
npm install -g @marcelocorrea/mcp-clint

# Instalação local em um projeto
npm install @marcelocorrea/mcp-clint
```

### Links Úteis

- [Pacote no NPM](https://www.npmjs.com/package/@marcelocorrea/mcp-clint)
- [Repositório GitHub](https://github.com/maximweb/mcp-clint)
- [Reportar Issues](https://github.com/maximweb/mcp-clint/issues)

## Exemplos de Uso

### Listar contatos
```json
{
  "name": "contacts",
  "arguments": {
    "operation": "list",
    "limit": 10,
    "offset": 0
  }
}
```

### Criar um novo contato
```json
{
  "name": "contacts",
  "arguments": {
    "operation": "create",
    "first_name": "João",
    "last_name": "Silva",
    "email": "joao.silva@exemplo.com",
    "phone": "+55 11 99999-9999"
  }
}
```

### Obter detalhes de um negócio específico
```json
{
  "name": "deals",
  "arguments": {
    "operation": "get",
    "id": "ID_DO_NEGÓCIO"
  }
}
```

### Adicionar tags a um contato
```json
{
  "name": "contacts",
  "arguments": {
    "operation": "add_tags",
    "id": "ID_DO_CONTATO",
    "tag_ids": ["ID_DA_TAG1", "ID_DA_TAG2"]
  }
}
```

---

Para mais detalhes sobre os parâmetros e operações disponíveis, consulte a documentação completa no arquivo `docs/clint-api-catalogo-v1.md`.