# Customers MCP

Servidor [MCP (Model Context Protocol)](https://modelcontextprotocol.io) que expõe uma API REST de clientes (CRUD) como tools, resource e prompts, prontos para uso no GitHub Copilot Chat, Claude ou qualquer outro cliente MCP.

Construído com o suporte nativo a TypeScript do Node.js — sem etapa de build.

---

## O que ele expõe

| Tipo | Nome | Descrição |
|---|---|---|
| 🔧 Tool | `list_customers` | Lista todos os clientes |
| 🔧 Tool | `create_customer` | Cria um novo cliente (`name`, `phone`) |
| 🔧 Tool | `get_customer` | Busca um cliente por `_id`, `name` ou `phone` |
| 🔧 Tool | `update_customer` | Atualiza nome e/ou telefone de um cliente existente |
| 🔧 Tool | `delete_customer` | Remove um cliente pelo `_id` |
| 📄 Resource | `customer://api-info` | Descreve os endpoints da API REST que o servidor consome |
| 💬 Prompt | `find_customer_prompt` | Busca um cliente por qualquer combinação de `_id`, `name` ou `phone` |
| 💬 Prompt | `create_customer_prompt` | Cria um cliente a partir de dados soltos |
| 💬 Prompt | `get_customer_prompt` | Busca um cliente com um template pronto |
| 💬 Prompt | `update_customer_prompt` | Atualiza um cliente com um template pronto |
| 💬 Prompt | `delete_customer_prompt` | Remove um cliente com um template pronto |

---

## Pré-requisitos

- **Node.js v24+** (veja `engines` em `package.json`)
- Uma **API REST de clientes** rodando em `http://localhost:9999/v1`, com os endpoints `GET/POST /customers`, `GET/PUT/DELETE /customers/:id`

O servidor MCP não tem estado próprio — ele é uma camada MCP sobre essa API.

---

## Instalação

```bash
npm install
```

---

## Configuração no VS Code

Crie (ou edite) `.vscode/mcp.json` na raiz do workspace:

```json
{
  "servers": {
    "customers-mcp": {
      "command": "node",
      "args": ["--experimental-specifier-resolution=node", "--watch", "--inspect", "src/index.ts"]
    }
  }
}
```

Depois, recarregue o VS Code (`Cmd+Shift+P` → **Developer: Reload Window**).

### Usando no Copilot Chat

```
Liste todos os clientes
```

```
Crie um cliente chamado João Silva com telefone 11999998888
```

```
Busque o cliente com o nome João Silva
```

```
Mostre o resource customer://api-info
```

O agente escolhe a tool certa automaticamente. Os prompts (`/find_customer_prompt`, `/create_customer_prompt` etc.) ficam disponíveis como comandos prontos no cliente MCP.

---

## Explorando com o MCP Inspector

Abre uma UI web para testar tools, resources e prompts manualmente, sem precisar de um cliente completo:

```bash
npm run mcp:inspect
```

---

## Rodando os testes

```bash
npm test          # roda a suíte uma vez
npm run test:dev  # roda em watch mode, com debugger
```

Os testes sobem o servidor real via stdio (mesmo mecanismo do cliente MCP) e chamam as tools, o resource e o prompt de ponta a ponta contra a API REST configurada.

---

## Estrutura do projeto

```
src/
  index.ts                    # Entry point — conecta o server ao transporte stdio
  mcp/
    server.ts                 # Monta o McpServer e registra tools, resource e prompts
    tools/                    # Uma tool por arquivo (create, get, update, delete, list)
    resources/apiInfo.ts      # Resource customer://api-info
    prompts/                  # Um prompt por operação
  application/
    customerService.ts        # Regras de negócio (busca por query, etc.)
  infrastructure/
    customerHttpClient.ts     # Cliente HTTP para a API REST de clientes
  domain/
    customer.ts                # Schemas Zod e tipos compartilhados
  tests/
    tools/customers.test.ts
    resources/apiInfo.test.ts
    prompt/findCustomer.test.ts
    helper.ts                  # Sobe um client de teste conectado ao server real
```

---

## Scripts disponíveis

| Script | Descrição |
|---|---|
| `npm start` | Sobe o servidor (usado pelos clientes MCP) |
| `npm run dev` | Sobe com file-watch e o inspector do Node.js |
| `npm test` | Roda todos os testes |
| `npm run test:dev` | Roda os testes em watch mode |
| `npm run mcp:inspect` | Abre o MCP Inspector |

---

## Licença

ISC