MCP Nova

客户管理和支付计划MCP服务器和聊天机器人

该项目提供两个主要组成部分：

1. MCP服务器：用于客户管理、地址查找和支付计划检索的模型上下文协议服务器
2. 人工智能聊天机器人：OpenAI GPT-4o-mini聊天机器人，通过REST API与MCP服务器集成

特性

MCP服务器

• ✅ 符合MCP的服务器实现（stdio传输）
• ✅ 承载令牌身份验证
• ✅ 三个集成工具：

- createCustomer -客户注册并验证 - getAddressByZipcode -巴西CEP地址查找 - list_payment_plans -付款计划检索（信用卡、PIX、银行单据）

• ✅ 必填字段验证
• ✅ 全面的错误处理
• ✅ 开发日志
• ✅ TypeScript实现

人工智能聊天机器人

• ✅ OpenAI GPT-4o-mini集成
• ✅ 通过环境变量配置音调/风格
• ✅ REST API终结点(/api/chat)
• ✅ 基于对话的MCP工具自动调用
• ✅ 对话历史管理
• ✅ 基于Express的HTTP服务器

先决条件

• Node.js 18+
• 纱线包装经理

安装

1. 安装依赖项：

yarn install

1. 配置环境变量：

复制示例文件并使用您的值进行编辑：

cp .env.example .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

备注: AGENT_TONE 或 AGENT_STYLE 控制聊天机器人的个性。

用法

运行MCP服务器（独立）

开发模式：

yarn dev

或者在手表模式下：

yarn watch

生产模式：

# Build
yarn build

# Run
yarn start

运行AI聊天机器人服务器

开发模式：

yarn chatbot:dev

生产模式：

# Build
yarn chatbot:build

# Run
yarn chatbot:start

聊天机器人服务器将在端口3000（或您配置的 CHATBOT_PORT).

聊天机器人API端点

POST/api/聊天

向聊天机器人发送消息：

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

答复：

{
  "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/聊天/重置

重置对话历史记录：

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

GET/健康

健康检查：

curl http://localhost:3000/health

MCP工具

工具1：创建客户

所需参数

• name （string）：客户全名
• email （string）：客户电子邮件地址（已验证）
• phone （string）：客户电话号码

可选参数

• retention （boolean）：保留标志
• identification （string）：客户ID文件（如CPF）
• zipcode （字符串）：邮政编码
• state （string）：州/省
• street （string）：街道名称
• number （string）：街道号
• neighborhood （string）：邻里
• city （string）：城市
• list_ids （number）：用于分类的列表ID
• create_deal （boolean）：是否创建交易
• tags （string）：客户标签
• url （string）：URL引用
• utm_term （string）：UTM术语参数
• utm_medium （string）：UTM介质参数
• utm_source （string）：UTM源参数
• utm_campaign （string）：UTM活动参数
• company_id （string）：公司ID
• utm_content （string）：UTM内容参数

示例请求

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

成功响应示例

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

错误响应示例

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

工具2:getAddressByZipcode

通过CEP（邮政编码）查找巴西地址。

所需参数

• zipcode （字符串）：巴西CEP，格式为XXXXX-XXXX或XXXXXXXX（8位数字）

示例请求

{
  "zipcode": "01310-100"
}

成功响应示例

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

工具3:列表_付款_计划

检索结账优惠的可用付款计划。从环境变量中读取配置(CHECKOUT_ID 和 PRODUCT_ID).

所需参数

无-该工具使用环境变量中的配置。

配置（环境变量）

• CHECKOUT_ID （string）：结账页面标识符
• PRODUCT_ID （string）：逗号分隔的产品ID（例如，“36,42”）

示例响应

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

备注

• API调用一次 product_id 字符串（逗号分隔）
• 后端处理多个产品ID并返回组合付款条件
• Fine、Fine_tax和late_interest字段会自动忽略
• 付款摘要以葡萄牙语（巴西）生成

错误响应示例

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

使用MCP客户端进行配置

要将此服务器与MCP兼容的客户端（如Claude Desktop）一起使用，请将以下内容添加到MCP设置配置中：

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

聊天机器人是如何工作的

1. 用户向发送消息 /api/chat
2. 聊天机器人将消息添加到对话历史记录中
3. OpenAI GPT-4o-mini使用配置的系统提示处理消息
4. 如果LLM确定需要动作（例如。， createCustomer, getAddressByZipcode, list_payment_plans)，它以JSON响应
5. 聊天机器人提取动作并通过stdio调用MCP服务器
6. MCP服务器执行相应的工具：

- 通过外部API进行客户注册 - 通过ViaCEP查找地址 - 通过外部API检索付款计划

1. 结果将返回给LLM，以葡萄牙语发送友好的后续消息
2. 最终回复已发送回用户

聊天机器人对话示例

客户注册：

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

聊天机器人： Perfeito! Cadastrei o João Silva com sucesso. O ID do cliente é 67890.

地址查找：

用户： Qual endereço do CEP 01310-100?

聊天机器人：\`CEP 01310-100对应于：

• 保利斯塔大道
• 社区： Bella Vista
• 圣保罗-SP\`

付款计划：

用户： Quais são as formas de pagamento?

Chatbot:\`我们有以下选项：

• 信用卡：高达R$ 91.33的12倍
• Pix to Vista:1.096,00雷亚尔
• 现场门票： R$ 1096.00\`

多圈带地址：

用户： Quero cadastrar um cliente

Chatbot：当然！我需要：

• 全名
• 电子邮件
• 电话

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

聊天机器人： *（查看CEP）* Encontrei o endereço: Avenida Rio Branco, Centro, Rio de Janeiro - RJ. Vou cadastrar a Maria Santos com essas informações.

*（创建客户）*

聊天机器人： Pronto! Maria Santos cadastrada com sucesso. ID: 11223

项目结构

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端点

发布 https://{{host}}/api/v1/customers

标题：

• Authorization: Bearer {{TOKEN}}
• Content-Type: application/json

开发日志

当 NODE_ENV=development，服务器记录：

• 请求URL和有效载荷
• 响应状态和数据
• API错误及详细信息

错误处理

服务器处理：

• 必填字段缺失或无效
• 来自外部API的HTTP错误
• 网络连接问题
• 承载令牌无效
• 请求格式错误

安全

• 环境变量用于敏感数据（API主机和令牌）
• .env 文件被忽略
• 承载令牌从未被记录或公开
• 电子邮件验证阻止了基本的注入尝试

许可证

麻省理工学院