MCP Cvcrm

🚀 CV CRM MCP服务器

MCP（模型上下文协议）服务器，用于与 CRM 简历 API 集成，使 AI 助理能够自然高效地管理 CRM 操作。

📋 索引

• 索夫雷
• 功能
• 先决条件
• 安装
• 配置
• 使用
• 文档
• 开发
• 故障排除

🎯 索夫雷

该项目实施了一个MCP服务器，将CRM简历API暴露给AI助手（如Cursor），允许：

• ✅ 管理 服务
• ✅ 注册和搜索 客户
• ✅ 创建和管理 预订
• ✅ 咨询 委员
• ✅ 访问 一般 记录 （项目、工作流程等）

✨ 功能

可用的MCP工具

服务

• cvcrm_criar_atendimento - 注册新服务
• cvcrm_listar_atendimentos - 带过滤器的会议列表

客户

• cvcrm_cadastrar_cliente - 客户注册（PF或PJ）
• cvcrm_buscar_clientes - 通过姓名，CPF，CNPJ或电子邮件搜索客户

预订

• cvcrm_criar_reserva - 创建新的驱动器备份
• cvcrm_listar_reservas - 带过滤器的预订列表
• cvcrm_informar_venda - 商标预订为已售

新月（ AI 代理）⭐ 新

• luna_identificar_cliente - 通过CPF识别客户
• luna_consultar_parcelas -查询付款地块
• luna_gerar_segunda_via_boleto -GERA第二票
• luna_criar_chamado_assistencia 打开帮助呼叫
• luna_consultar_chamados - 帮助呼叫列表
• luna_listar_empreendimentos_disponiveis - 企业列表

版本： docs/06-LUNA-NOVA-TOOLS.md

🌐 通过HTTP API访问（n8n，Make，Zapier）

所有Luna工具也可通过REST API获得！

# Exemplo
POST http://localhost:3000/api/luna/identificar-cliente
Content-Type: application/json

{
  "cpf": "12345678900"
}

可用的端点 ：

• POST /api/luna/identificar-cliente
• POST /api/luna/consultar-parcelas
• POST /api/luna/gerar-boleto
• POST /api/luna/criar-chamado
• POST /api/luna/consultar-chamados
• POST /api/luna/listar-empreendimentos

版本： N8N_集成指南.md e docs/07-HTTP-API.md文件

可用的 MCP 资源

• cvcrm://auth/status 身份验证和令牌状态
• cvcrm://empreendimentos 活跃企业列表
• cvcrm://config - 服务器配置

📦 先决条件

• Node.js >= 18.0.0
• npm >= 9.0.0
• 瑞迪斯 （当地或Upstash）
• CRM 简历 （域名、用户、CPF）

🚀 安装

1. 克隆仓库

git clone 
cd cvcrm-mcp-server

2. 安装依赖关系

npm install

3.配置器Redis

选项A：Docker（推荐）

docker run -d --name cvcrm-redis -p 6379:6379 redis:alpine

选项B：本地网络

# Windows (com chocolatey)
choco install redis-64

# Mac (com homebrew)
brew install redis

# Linux
sudo apt-get install redis-server

# Iniciar
redis-server

选项C：Upstash（云）

1. 创建账户 upush.com
2. 创建 Redis 数据库
3. 复制连接 URL

4. 设置环境变量

# Copiar arquivo de exemplo
cp .env.example .env

编辑 .env 您的凭据：

# CV CRM
CVCRM_DOMINIO=minhaempresa
CVCRM_USUARIO=usuario@email.com
CVCRM_CPF=12345678900
CVCRM_VERIFICATION_CODE=123456  # Opcional

# Redis
REDIS_URL=redis://localhost:6379

⚠️ 重要提示： 哦 CVCRM_VERIFICATION_CODE 这是可选的，但自动化是必要的。查看 认证 了解更多详情。

5. 构建项目

npm run build

⚙️ 配置

在光标上配置 MCP

添加到光标 MCP 配置文件 ：

窗户： %APPDATA%\Cursor\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json

Mac/Linux： ~/.cursor/mcp.json

{
  "mcpServers": {
    "cvcrm": {
      "command": "node",
      "args": [
        "C:/caminho/completo/para/cvcrm-mcp-server/dist/index.js"
      ],
      "env": {
        "CVCRM_DOMINIO": "minhaempresa",
        "CVCRM_USUARIO": "usuario@email.com",
        "CVCRM_CPF": "12345678900",
        "CVCRM_VERIFICATION_CODE": "123456",
        "REDIS_URL": "redis://localhost:6379",
        "LOG_LEVEL": "info"
      }
    }
  }
}

\_其他组织者

• 使用绝对路径 dist/index.js
• 在 Windows 中使用普通条 / 或逃避倒杆 \\
• 配置后重新启动光标

🎮 使用

无光标

设置后，您可以直接在 Cursor 聊天中使用这些工具：

例如：

User: Crie um atendimento para o cliente ID 123 sobre vazamento no banheiro

AI: [executa cvcrm_criar_atendimento]
✅ Atendimento criado com sucesso!
Protocolo: ATD-2024-001
...

User: Liste todas as reservas do empreendimento 5

AI: [executa cvcrm_listar_reservas com empreendimentoId: 5]
📋 Reservas Encontradas (15 total)
...

User: Cadastre um cliente pessoa física com nome João Silva, CPF 12345678900 e email joao@email.com

AI: [executa cvcrm_cadastrar_cliente]
✅ Cliente cadastrado com sucesso!
...

手动运行（ 开发）

# Modo desenvolvimento (watch)
npm run dev

# Modo produção
npm start

# Apenas MCP Server
npm run start:mcp

📚 文档

完整的文档在文件夹中 docs/:

• 00-项目概述.md - 项目概述
• 01-建筑.md 详细的建筑
• 02-认证.md - 身份验证系统
• 03-API-基准点.md -API CV CRM的终点
• 04-MCP-TOOLS.md 工具规格
• 05-部署.md -部署e故障排除

🔐 认证

简历CRM使用两步验证：

自动流（推荐给开发人员）

配置 CVCRM_VERIFICATION_CODE 不 .env 使用固定代码：

CVCRM_VERIFICATION_CODE=123456

Fluxo手册

1. 服务器请求验证码
2. 代码被发送到配置的电子邮件
3. 您需要获取代码并提供给系统

版本 docs/02-认证.md 了解更多详情。

🛠️ 开发

项目结构

cvcrm-mcp-server/
├── docs/                    # Documentação técnica
├── src/
│   ├── app/                # Next.js (opcional)
│   ├── lib/
│   │   ├── cvcrm/         # Cliente API CV CRM
│   │   ├── mcp/           # MCP Server
│   │   ├── redis/         # Cache Redis
│   │   └── utils/         # Utilitários
│   ├── types/             # TypeScript types
│   ├── config/            # Configurações
│   └── mcp/               # Entry point MCP
├── dist/                   # Build output
└── package.json

可用脚本

# Desenvolvimento
npm run dev              # Next.js dev server
npm run start:mcp        # MCP server standalone

# Build
npm run build            # Build completo
npm run build:mcp        # Build apenas MCP

# Qualidade
npm run lint             # ESLint
npm run type-check       # TypeScript check
npm test                 # Testes

# Produção
npm start                # Next.js server
npm run start:mcp        # MCP server

添加新工具

1. 创建文件于 src/lib/mcp/tools/
2. Definir模式（Zod）、工具定义和处理程序
3. 导出到 src/lib/mcp/tools/index.ts
4. 注册商em src/lib/mcp/server.ts

版本 docs/04-MCP-TOOLS.md 举个例子。

🐛 故障排除

错误： 无效的令牌

原因： 代币已过期或验证码错误

解决方案 ：

1. 检查 CVCRM_VERIFICATION_CODE
2. 清除缓存 ： redis-cli FLUSHDB
3. 重新验证

错误：“Redis连接被拒绝”

原因： Redis 未运行

解决方案 ：

# Verificar
docker ps | grep redis

# Iniciar
docker start cvcrm-redis
# ou
redis-server

错误：“找不到MCP服务器”

原因： 路径不正确 mcp.json

解决方案 ：

1. 检查绝对路径 dist/index.js
2. 检查是否 npm run build 已执行
3. 重新启动光标

日志不显示

# Ver logs
tail -f logs/cvcrm-mcp.log

# Ver erros
tail -f logs/error.log

还有问题吗？

咨询 docs/05-DEPLOYMENT.md 完整的名单。

📊 日志和监控

日志保存到 ：

• logs/cvcrm-mcp.log -罗格拉尔
• logs/error.log - 只有错误

通过设置日志级别 LOG_LEVEL （调试、信息、警告、错误）。

🔒 安全

• 永远不会 提交 .env
• 使用TTL存储在Redis中的令牌
• 通过环境变量验证
• 使用 Zod 校验输入

🤝 贡献

1. 分叉工程
2. 创建分支（git checkout -b feature/MinhaFeature)
3. 提交您的更改（git commit -m 'feat: Adiciona MinhaFeature')
4. 推动一个分支(git push origin feature/MinhaFeature)
5. Abra um Pull请求

📄 许可证

这个项目是私人和私有的。

🆘 支持

• 文档 ： 吃意大利面 docs/
• 问题： 在仓库中打开一个问题
• 电子邮件： \[seu-email@exemplo.com \]

______________________________________________________________________

开发于❤️ 使用 Next.js、TypeScript 和 Redis

版本 ： 1.0.0 | 数据： 2025-11-01