# Customer Management & Payment Plans MCP Server & Chatbot

This project provides two main components:
1. **MCP Server**: A Model Context Protocol server for customer management, address lookup, and payment plan retrieval
2. **AI Chatbot**: An OpenAI GPT-4o-mini powered chatbot that integrates with the MCP server via REST API

## Features

### MCP Server
- ✅ MCP-compliant server implementation (stdio transport)
- ✅ Bearer token authentication
- ✅ Three integrated tools:
  - `createCustomer` - Customer registration with validation
  - `getAddressByZipcode` - Brazilian CEP address lookup
  - `list_payment_plans` - Payment plan retrieval (credit card, PIX, bank slip)
- ✅ Required field validation
- ✅ Comprehensive error handling
- ✅ Development logging
- ✅ TypeScript implementation

### AI Chatbot
- ✅ OpenAI GPT-4o-mini integration
- ✅ Configurable tone/style via environment variables
- ✅ REST API endpoint (`/api/chat`)
- ✅ Automatic MCP tool invocation based on conversation
- ✅ Conversation history management
- ✅ Express-based HTTP server

## Prerequisites

- Node.js 18+ 
- Yarn package manager

## Installation

1. Install dependencies:

```bash
yarn install
```

2. Configure environment variables:

Copy the example file and edit with your values:

```bash
cp .env.example .env
```

Edit `.env`:

```env
# MCP Server Configuration
CUSTOMER_API_HOST=https://your-api-host.com
CUSTOMER_API_TOKEN=your_bearer_token_here
NODE_ENV=development

# Payment Plans Configuration
CHECKOUT_ID=your_checkout_id_here
PRODUCT_ID=36,42

# Chatbot Configuration
OPENAI_API_KEY=sk-your-openai-api-key-here
OPENAI_MODEL=gpt-5-nano
AGENT_TONE=Professional, helpful, and efficient
# Alternative: AGENT_STYLE=Encouraging, visionary, witty

# Chatbot Server Port (optional, defaults to 3000)
CHATBOT_PORT=3000
```

**Note**: `AGENT_TONE` or `AGENT_STYLE` controls the chatbot's personality.

## Usage

### Running the MCP Server (standalone)

**Development Mode:**

```bash
yarn dev
```

Or with watch mode:

```bash
yarn watch
```

**Production Mode:**

```bash
# Build
yarn build

# Run
yarn start
```

### Running the AI Chatbot Server

**Development Mode:**

```bash
yarn chatbot:dev
```

**Production Mode:**

```bash
# Build
yarn chatbot:build

# Run
yarn chatbot:start
```

The chatbot server will start on port 3000 (or your configured `CHATBOT_PORT`).

## Chatbot API Endpoints

### POST /api/chat

Send a message to the chatbot:

```bash
curl -X POST http://localhost:3000/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Register a customer: John Doe, john@example.com, +1234567890",
    "context": {}
  }'
```

**Response:**

```json
{
  "reply": "Great! I've successfully registered John Doe as a customer. The customer ID is 12345.",
  "actions": [
    {
      "tool": "createCustomer",
      "input": {
        "name": "John Doe",
        "email": "john@example.com",
        "phone": "+1234567890"
      },
      "result": {
        "status": "success",
        "customerId": 12345,
        "data": {...}
      }
    }
  ]
}
```

### POST /api/chat/reset

Reset the conversation history:

```bash
curl -X POST http://localhost:3000/api/chat/reset
```

### GET /health

Health check:

```bash
curl http://localhost:3000/health
```

## MCP Tools

### Tool 1: createCustomer

### Required Parameters

- `name` (string): Customer full name
- `email` (string): Customer email address (validated)
- `phone` (string): Customer phone number

### Optional Parameters

- `retention` (boolean): Retention flag
- `identification` (string): Customer ID document (e.g., CPF)
- `zipcode` (string): ZIP/Postal code
- `state` (string): State/Province
- `street` (string): Street name
- `number` (string): Street number
- `neighborhood` (string): Neighborhood
- `city` (string): City
- `list_ids` (number): List ID for categorization
- `create_deal` (boolean): Whether to create a deal
- `tags` (string): Tags for the customer
- `url` (string): URL reference
- `utm_term` (string): UTM term parameter
- `utm_medium` (string): UTM medium parameter
- `utm_source` (string): UTM source parameter
- `utm_campaign` (string): UTM campaign parameter
- `company_id` (string): Company ID
- `utm_content` (string): UTM content parameter

### Example Request

```json
{
  "name": "Tony Stark",
  "email": "newone@avengers.com",
  "phone": "(12) 99756-0001",
  "city": "São Paulo",
  "retention": true,
  "identification": "251.482.720-58",
  "tags": "coyo-jan"
}
```

### Example Success Response

```json
{
  "status": "success",
  "customerId": 12345,
  "data": {
    "id": 12345,
    "name": "Tony Stark",
    "email": "newone@avengers.com",
    ...
  }
}
```

### Example Error Response

```json
{
  "status": "error",
  "error": "Validation failed",
  "errors": [
    "email is required",
    "phone is required"
  ]
}
```

### Tool 2: getAddressByZipcode

Lookup Brazilian addresses by CEP (zipcode).

#### Required Parameters

- `zipcode` (string): Brazilian CEP in format XXXXX-XXX or XXXXXXXX (8 digits)

#### Example Request

```json
{
  "zipcode": "01310-100"
}
```

#### Example Success Response

```json
{
  "cep": "01310-100",
  "logradouro": "Avenida Paulista",
  "bairro": "Bela Vista",
  "localidade": "São Paulo",
  "uf": "SP"
}
```

### Tool 3: list_payment_plans

Retrieve available payment plans for checkout offers. Configuration is read from environment variables (`CHECKOUT_ID` and `PRODUCT_ID`).

#### Required Parameters

None - the tool uses configuration from environment variables.

#### Configuration (Environment Variables)

- `CHECKOUT_ID` (string): Checkout page identifier
- `PRODUCT_ID` (string): Comma-separated product IDs (e.g., "36,42")

#### Example Response

```json
{
  "checkout_id": "checkout_abc123",
  "product_id": "36,42",
  "plans": {
    "credit_card": [
      { "installments": 1, "value": 1096.00 },
      { "installments": 2, "value": 548.00 },
      { "installments": 3, "value": 365.33 },
      { "installments": 6, "value": 182.67 },
      { "installments": 12, "value": 91.33 }
    ],
    "pix": [
      { "value": 1096.00 }
    ],
    "bank_slip": [
      { "value": 1096.00 }
    ]
  },
  "payment_summary": "Temos pagamentos em até 12x de R$ 91,33 no cartão de crédito, ou à vista no PIX por R$ 1.096,00 ou boleto por R$ 1.096,00."
}
```

#### Notes

- The API is called once with the full `product_id` string (comma-separated)
- Backend processes multiple product IDs and returns combined payment conditions
- Fine, fine_tax, and late_interest fields are automatically ignored
- Payment summary is generated in Portuguese (Brazil)

#### Example Error Response

```json
{
  "error": "Request failed with status code 401",
  "statusCode": 401
}
```

## Configuring with MCP Clients

To use this server with an MCP-compatible client (like Claude Desktop), add the following to your MCP settings configuration:

```json
{
  "mcpServers": {
    "customer-registration": {
      "command": "node",
      "args": ["/absolute/path/to/mcpNova/build/index.js"],
      "env": {
        "CUSTOMER_API_HOST": "https://your-api-host.com",
        "CUSTOMER_API_TOKEN": "your_bearer_token_here",
        "NODE_ENV": "production",
        "CHECKOUT_ID": "your_checkout_id",
        "PRODUCT_ID": "36,42"
      }
    }
  }
}
```

## How the Chatbot Works

1. User sends a message to `/api/chat`
2. Chatbot adds message to conversation history
3. OpenAI GPT-4o-mini processes the message with configured system prompt
4. If LLM determines an action is needed (e.g., `createCustomer`, `getAddressByZipcode`, `list_payment_plans`), it responds with JSON
5. Chatbot extracts the action and calls MCP server via stdio
6. MCP server executes the appropriate tool:
   - Customer registration via external API
   - Address lookup via ViaCEP
   - Payment plans retrieval via external API
7. Result is returned to LLM for a friendly follow-up message in Portuguese
8. Final response sent back to user

## Example Chatbot Conversations

**Customer Registration:**

User: `Preciso cadastrar um cliente: João Silva, joao@email.com, (11) 98765-4321`

Chatbot: `Perfeito! Cadastrei o João Silva com sucesso. O ID do cliente é 67890.`

**Address Lookup:**

User: `Qual endereço do CEP 01310-100?`

Chatbot: `O CEP 01310-100 corresponde a:
- Avenida Paulista
- Bairro: Bela Vista
- São Paulo - SP`

**Payment Plans:**

User: `Quais são as formas de pagamento?`

Chatbot: `Temos as seguintes opções:
- Cartão de crédito: até 12x de R$ 91,33
- PIX à vista: R$ 1.096,00
- Boleto à vista: R$ 1.096,00`

**Multi-turn with Address:**

User: `Quero cadastrar um cliente`

Chatbot: `Claro! Preciso de:
- Nome completo
- E-mail
- Telefone`

User: `Nome: Maria Santos, Email: maria@email.com, Telefone: (21) 99999-8888, CEP: 20040-020`

Chatbot: *(looks up CEP)* `Encontrei o endereço: Avenida Rio Branco, Centro, Rio de Janeiro - RJ. Vou cadastrar a Maria Santos com essas informações.`

*(creates customer)*

Chatbot: `Pronto! Maria Santos cadastrada com sucesso. ID: 11223`

## Project Structure

```
mcpNova/
├── src/
│   ├── index.ts                  # MCP Server (stdio)
│   ├── chatbotServer.ts          # Express REST API server
│   └── services/
│       ├── customerService.ts    # Customer API integration
│       ├── viaCepService.ts      # Brazilian address lookup
│       ├── paymentPlansService.ts # Payment plans retrieval
│       ├── mcpClient.ts          # MCP client (stdio communication)
│       └── chatbotService.ts     # OpenAI integration & logic
├── build/                        # Compiled TypeScript
├── package.json
├── tsconfig.json
├── .env                          # Environment variables (gitignored)
├── .env.example                  # Environment template
└── README.md
```

## API Endpoint

**POST** `https://{{host}}/api/v1/customers`

**Headers:**
- `Authorization: Bearer {{TOKEN}}`
- `Content-Type: application/json`

## Development Logging

When `NODE_ENV=development`, the server logs:
- Request URLs and payloads
- Response status and data
- API errors with details

## Error Handling

The server handles:
- Missing or invalid required fields
- HTTP errors from the external API
- Network connectivity issues
- Invalid Bearer tokens
- Malformed requests

## Security

- Environment variables are used for sensitive data (API host and token)
- `.env` files are gitignored
- Bearer token is never logged or exposed
- Email validation prevents basic injection attempts

## License

MIT