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:

yarn install

2. Configure environment variables:

Copy the example file and edit with your values:

cp .env.example .env

Edit .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:

yarn dev

Or with watch mode:

yarn watch

Production Mode:

# Build
yarn build

# Run
yarn start

Running the AI Chatbot Server

Development Mode:

yarn chatbot:dev

Production Mode:

# 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:

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:

{
  "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:

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

GET /health

Health check:

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

{
  "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

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

Example Error Response

{
  "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

{
  "zipcode": "01310-100"
}

Example Success Response

{
  "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

{
  "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

{
  "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:

{
  "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