Espomcp

🚀 EspoCRM MCP 服务器

这是一个全面的模型上下文协议（MCP）服务器，用于与 EspoCRM 进行无缝集成。该服务器使 AI 助手能够通过标准化接口与你的 EspoCRM 实例进行交互，为联系人、账户、商机、会议、用户、任务、潜在客户等提供完整的 CRUD 操作，以及高级系统管理功能。

🤖 新增：AI 聊天机器人集成 - 现在包含一个完整的聊天机器人界面，可直接嵌入到你的 EspoCRM 中，通过自然语言访问所有 47 个 MCP 工具！

🚀 快速开始

前提条件

• Node.js 18+
• npm 或 yarn
• 具有 API 访问权限的 EspoCRM 实例
• 有效的 API 凭证

安装

1. 克隆仓库

git clone https://github.com/zaphod-black/EspoMCP.git
cd EspoMCP

2. 安装依赖

npm install

3. 配置环境

cp .env.example .env
# 使用你的 EspoCRM 凭证编辑 .env 文件

4. 构建项目

npm run build

5. 测试连接

npm run test:config

✨ 主要特性

核心功能

• 完整的 CRUD 操作 - 创建、读取、更新和删除实体
• 多实体支持 - 联系人、账户、商机、会议、用户、任务和潜在客户
• 高级搜索和过滤 - 支持日期范围、分页和复杂过滤器的灵活搜索
• 任务管理 - 具有父关系和用户分配的完整任务生命周期管理
• 潜在客户管理 - 从创建到转化的完整潜在客户管道管理
• 会议管理 - 与日历全面集成，支持参会人员管理
• 用户管理 - 全面的用户搜索和查找功能
• 实时验证 - 基于 Zod 的所有操作模式验证
• 全面日志记录 - 由 Winston 驱动的多级日志记录

认证与安全

• 多种认证方法 - 支持 API 密钥和 HMAC 认证
• 安全配置 - 基于环境的配置管理
• 速率限制 - 内置速率限制以保护 API
• 错误处理 - 强大的错误处理和详细日志记录

日历集成

• 会议操作 - 创建、搜索、更新和管理会议
• 参会人员管理 - 将联系人与用户关联到会议
• 日期/时间过滤 - 高级日期范围搜索功能
• 与 Google 日历同步兼容 - 专为日历同步工作流设计

AI 聊天机器人集成 🤖

• 浮动聊天窗口 - 美观且不干扰的聊天气泡界面
• 自然语言处理 - 使用纯英语聊天来执行 CRM 操作
• 实时通信 - 由 WebSocket 驱动的即时响应
• 访问 47 个 MCP 工具 - 通过聊天实现完整的 CRM 功能
• 嵌入 EspoCRM - 直接集成到你的 EspoCRM 界面中
• 移动响应式 - 在所有设备上无缝运行

开发者体验

• TypeScript 支持 - 全面支持 TypeScript 并采用严格类型检查
• Docker 支持 - 支持容器化部署
• 全面测试 - 多个测试脚本和验证工具
• 符合 MCP 2024/2025 规范 - 支持最新的 MCP 规范

📦 安装指南

克隆仓库

git clone https://github.com/zaphod-black/EspoMCP.git
cd EspoMCP

安装依赖

npm install

配置环境

cp .env.example .env
# 使用你的 EspoCRM 凭证编辑 .env 文件

构建项目

npm run build

测试连接

npm run test:config

💻 使用示例

任务管理

// 创建一个分配给用户且具有父关系的任务
await client.callTool('create_task', {
  name: '跟进潜在客户讨论',
  assignedUserId: 'user123',
  parentType: 'Lead',
  parentId: 'lead456',
  priority: '高',
  status: '未开始',
  dateEnd: '2025-08-15',
  description: '联系潜在客户了解定价问题'
});

// 按分配用户和状态搜索任务
await client.callTool('search_tasks', {
  assignedUserId: 'user123',
  status: '已开始',
  priority: '高',
  dueDateFrom: '2025-08-01',
  dueDateTo: '2025-08-31'
});

// 将任务分配给其他用户
await client.callTool('assign_task', {
  taskId: 'task789',
  assignedUserId: 'user456'
});

潜在客户管理

// 创建一个新的潜在客户
await client.callTool('create_lead', {
  firstName: '约翰',
  lastName: '史密斯',
  emailAddress: 'john.smith@example.com',
  accountName: '史密斯工业',
  source: '网站',
  status: '新',
  assignedUserId: 'user123',
  description: '对企业解决方案感兴趣'
});

// 按状态和来源搜索潜在客户
await client.callTool('search_leads', {
  status: '处理中',
  source: '网站',
  assignedUserName: '销售代表',
  createdFrom: '2025-08-01',
  limit: 20
});

// 将潜在客户转化为联系人和账户
await client.callTool('convert_lead', {
  leadId: 'lead123',
  createContact: true,
  createAccount: true,
  createOpportunity: true,
  opportunityName: '史密斯工业 - 企业交易',
  opportunityAmount: 50000
});

团队与角色管理

// 将用户添加到团队并指定职位
await client.callTool('add_user_to_team', {
  userId: 'user123',
  teamId: '销售团队',
  position: '销售经理'
});

// 获取团队的所有成员
await client.callTool('get_team_members', {
  teamId: '销售团队',
  limit: 50
});

// 为用户分配角色以进行权限管理
await client.callTool('assign_role_to_user', {
  userId: 'user123',
  roleId: '经理角色'
});

// 根据条件搜索团队
await client.callTool('search_teams', {
  name: '销售',
  description: '收入'
});

// 获取用户的有效权限
await client.callTool('get_user_permissions', {
  userId: 'user123'
});

通用实体操作

// 创建任何实体类型（包括自定义实体）
await client.callTool('create_entity', {
  entityType: '自定义产品',
  data: {
    name: '高级小部件',
    price: 199.99,
    category: '电子产品',
    inStock: true
  }
});

// 使用灵活的过滤器搜索任何实体
await client.callTool('search_entity', {
  entityType: '自定义订单',
  filters: {
    status: '待处理',
    totalAmount: 1000,
    customerType: '企业'
  },
  select: ['id', '订单编号', '客户名称', '总金额'],
  orderBy: 'createdAt',
  order: 'desc'
});

// 更新任何实体记录
await client.callTool('update_entity', {
  entityType: '自定义产品',
  entityId: 'prod123',
  data: {
    price: 179.99,
    inStock: false,
    lastModified: '2025-07-20T10:30:00Z'
  }
});

// 删除任何实体记录
await client.callTool('delete_entity', {
  entityType: '自定义产品',
  entityId: 'prod123'
});

// 获取特定实体并选择字段
await client.callTool('get_entity', {
  entityType: '自定义订单',
  entityId: 'order456',
  select: ['订单编号', '客户名称', '商品', '总金额']
});

关系管理

// 将实体关联在一起（例如，将联系人关联到账户）
await client.callTool('link_entities', {
  entityType: 'Contact',
  entityId: 'contact123',
  relatedEntityType: 'Account',
  relatedEntityId: 'account456',
  relationshipName: 'accounts'
});

// 获取实体的所有关系
await client.callTool('get_entity_relationships', {
  entityType: 'Contact',
  entityId: 'contact123',
  relationshipName: 'opportunities'
});

// 移除实体之间的关系
await client.callTool('unlink_entities', {
  entityType: 'Contact',
  entityId: 'contact123',
  relatedEntityType: 'Account',
  relatedEntityId: 'account456',
  relationshipName: 'accounts'
});

沟通工具

// 创建一个通话记录
await client.callTool('create_call', {
  name: '跟进与约翰·史密斯的通话',
  status: '已完成',
  direction: '呼出',
  duration: 1800, // 30 分钟，以秒为单位
  parentType: 'Contact',
  parentId: 'contact123',
  description: '讨论了定价选项和下一步计划'
});

// 根据条件搜索通话记录
await client.callTool('search_calls', {
  status: '已完成',
  direction: '呼出',
  dateFrom: '2025-07-01',
  dateTo: '2025-07-31',
  limit: 20
});

// 创建一个支持案例
await client.callTool('create_case', {
  name: '登录问题',
  status: '新',
  priority: '高',
  type: '技术',
  accountId: 'account123',
  description: '客户无法登录门户'
});

// 为任何实体添加备注
await client.callTool('add_note', {
  parentType: 'Lead',
  parentId: 'lead123',
  post: '客户对企业功能表示感兴趣。下周安排演示。',
  data: {
    isInternal: false
  }
});

// 根据父实体搜索备注
await client.callTool('search_notes', {
  parentType: 'Lead',
  parentId: 'lead123',
  createdFrom: '2025-07-01',
  limit: 10
});

AI 聊天机器人使用

嵌入式聊天机器人理解自然语言，可以执行任何 CRM 操作：

// 用户可以输入的自然语言示例：
"创建一个名为莎拉·约翰逊的联系人，邮箱为 sarah@techcorp.com"
"查找软件行业的所有账户"
"显示超过 50,000 美元的商机"
"创建一个跟进潜在客户约翰·史密斯的任务"
"安排明天下午 2 点的会议"
"系统健康状态如何？"
"将联系人 ID 123 关联到账户 TechCorp"
"在案例 #456 中添加备注：'客户对解决方案满意'"

会议管理

// 创建一个带有参会人员的会议
await client.callTool('create_meeting', {
  name: '项目启动会议',
  dateStart: '2025-08-01T10:00:00',
  dateEnd: '2025-08-01T11:00:00',
  location: 'A 会议室',
  description: '初始项目规划会议',
  status: '计划中',
  contactsIds: ['contact123', 'contact456'],
  usersIds: ['user789']
});

// 按日期范围搜索会议
await client.callTool('search_meetings', {
  dateFrom: '2025-08-01',
  dateTo: '2025-08-31',
  status: '计划中',
  limit: 20
});

用户管理

// 通过电子邮件查找用户
await client.callTool('get_user_by_email', {
  emailAddress: 'john.doe@company.com'
});

// 搜索活跃用户
await client.callTool('search_users', {
  isActive: true,
  type: '普通用户',
  limit: 50
});

带日期过滤的高级联系人搜索

// 搜索上周创建的联系人
await client.callTool('search_contacts', {
  searchTerm: '经理',
  createdFrom: '2025-07-13',
  createdTo: '2025-07-20',
  limit: 10
});

日历集成工作流

// 完整的日历同步工作流
const meetings = await client.callTool('search_meetings', {
  dateFrom: '2025-08-01',
  dateTo: '2025-08-31'
});

const user = await client.callTool('get_user_by_email', {
  emailAddress: 'calendar@company.com'
});

const newMeeting = await client.callTool('create_meeting', {
  name: '从 Google 日历同步的会议',
  dateStart: '2025-08-15T14:00:00',
  dateEnd: '2025-08-15T15:00:00',
  googleEventId: 'google_event_123'
});

📚 详细文档

可用工具

MCP 服务器为 EspoCRM 集成提供了 47 个全面的工具：

联系人管理

• create_contact - 创建支持所有字段的新联系人
• search_contacts - 使用日期范围过滤搜索和筛选联系人
• get_contact - 通过 ID 检索特定联系人

账户管理

• create_account - 创建新的公司/组织账户
• search_accounts - 使用日期范围过滤搜索和筛选账户

商机管理

• create_opportunity - 创建新的销售商机
• search_opportunities - 使用包括金额范围在内的高级过滤器搜索商机

会议管理

• create_meeting - 创建支持参会人员管理和日历集成的会议
• search_meetings - 使用日期范围、状态和地点过滤器搜索会议
• get_meeting - 检索包括参会人员在内的详细会议信息
• update_meeting - 更新现有会议，支持所有会议字段

用户管理

• search_users - 按用户名、电子邮件、姓名、类型和状态搜索用户
• get_user_by_email - 基于电子邮件直接查找用户，用于日历同步操作

任务管理

• create_task - 创建支持父实体（潜在客户、账户、联系人、商机）的任务
• search_tasks - 按分配用户、状态、优先级、父实体和截止日期搜索任务
• get_task - 检索包括关系在内的详细任务信息
• update_task - 更新任务属性，包括状态、优先级和截止日期
• assign_task - 将任务分配或重新分配给特定用户

潜在客户管理

• create_lead - 创建支持所有字段并进行验证的新潜在客户
• search_leads - 按状态、来源、分配用户和日期范围搜索潜在客户
• update_lead - 更新潜在客户属性和状态
• convert_lead - 将潜在客户转化为联系人、账户和/或商机
• assign_lead - 将潜在客户分配或重新分配给特定用户

团队与角色管理

• add_user_to_team - 将用户添加到团队，并可选择指定职位
• remove_user_from_team - 从团队中移除用户
• assign_role_to_user - 为用户分配角色以进行权限管理
• get_user_teams - 获取用户所属的所有团队
• get_team_members - 获取特定团队的所有成员
• search_teams - 按名称和描述搜索团队
• get_user_permissions - 根据角色获取用户的有效权限

通用实体操作

• create_entity - 为任何实体类型（包括自定义实体）创建记录
• search_entity - 使用灵活的过滤器和字段选择搜索任何实体类型
• update_entity - 通过 ID 更新任何实体记录，支持灵活的数据
• delete_entity - 通过 ID 删除任何实体记录
• get_entity - 获取特定实体记录，并可选择字段

关系管理

• link_entities - 在任意两个实体记录之间创建关系
• unlink_entities - 移除实体记录之间的关系
• get_entity_relationships - 获取实体的所有相关记录，并包含关系详细信息

沟通工具

• create_call - 创建支持状态、方向和持续时间跟踪的通话记录
• search_calls - 按状态、方向、联系人及日期范围搜索通话记录
• create_case - 创建支持优先级、类型和账户关联的支持案例
• search_cases - 按状态、优先级、类型和分配情况搜索案例
• add_note - 为任何实体记录添加备注，用于文档记录和跟进
• search_notes - 按父实体、作者和日期范围搜索备注
• create_document - 创建支持文件附件和元数据的文档记录

系统工具

• health_check - 验证服务器和 EspoCRM 在所有实体上的连接性

增强搜索功能

所有搜索工具现在支持高级过滤选项：

日期范围过滤

• createdFrom / createdTo - 按创建日期范围过滤
• modifiedFrom / modifiedTo - 按修改日期范围过滤
• dateFrom / dateTo - 按日期范围过滤会议

会议特定过滤器

• status - 按会议状态（计划中、已举行、未举行）过滤
• location - 按会议地点过滤
• assignedUserName - 按分配用户过滤

用户特定过滤器

• userName - 按用户名搜索
• emailAddress - 按电子邮件地址搜索
• firstName / lastName - 按姓名组件搜索
• isActive - 按活动状态过滤
• type - 按用户类型（管理员、普通用户、门户用户、API 用户）过滤

🔧 技术细节

测试

自动化测试

项目包含全面的测试工具：

# 测试配置和连接性
npm run test:config

# 测试 MCP 客户端功能
npm run test:client

# 运行单元测试
npm test

手动测试脚本

连接测试

node test-connection.js

测试基本连接性、API 端点和认证。

增强工具测试

node test-enhanced-tools.js

全面测试所有增强功能，包括会议和用户管理。

随机联系人生成

node create-random-contact.js

创建一个随机测试联系人以验证 CRUD 操作。

开发

项目结构

EspoMCP/
├── src/                     # 源代码
│   ├── config/             # 配置管理
│   ├── espocrm/           # EspoCRM API 客户端和类型
│   │   ├── client.ts      # 带有认证的 HTTP 客户端
│   │   └── types.ts       # 所有实体的 TypeScript 接口
│   ├── tools/             # MCP 工具实现
│   ├── utils/             # 实用函数和格式化
│   │   ├── errors.ts      # 错误处理工具
│   │   ├── formatting.ts  # 实体格式化函数
│   │   ├── logger.ts      # Winston 日志配置
│   │   └── validation.ts  # Zod 模式验证
│   └── index.ts           # 主服务器入口点
├── tests/                  # 测试文件
├── build/                  # 编译后的 JavaScript
├── logs/                   # 应用程序日志
└── docs/                   # 文档

关键组件

• MCP 服务器 (src/index.ts)：主服务器实现，支持环境加载、优雅关闭处理和 MCP 协议合规性。
• EspoCRM 客户端 (src/espocrm/client.ts)：带有认证、错误处理、日志记录和完整 CRUD 操作的 HTTP 客户端。
• 实体类型 (src/espocrm/types.ts)：联系人、账户、商机、会议、用户及相关实体的完整 TypeScript 接口。
• 工具注册表 (src/tools/index.ts)：所有 MCP 工具的中央注册表，具有适当的类型安全、验证和错误处理。
• 格式化工具 (src/utils/formatting.ts)：所有实体类型的专业格式化函数，确保输出格式一致。

开发工作流

1. 对 src/ 中的源文件进行更改
2. 使用 npm run build 构建项目
3. 使用 npm run test:config 测试更改
4. 使用 npm run test:client 测试增强功能
5. 使用 npm run lint 检查代码

Docker 部署

使用 Docker 构建和运行

# 构建 Docker 镜像
npm run docker:build

# 使用环境文件运行
npm run docker:run

Docker Compose

version: '3.8'
services:
  espocrm-mcp:
    build: .
    environment:
      - ESPOCRM_URL=${ESPOCRM_URL}
      - ESPOCRM_API_KEY=${ESPOCRM_API_KEY}
      - ESPOCRM_AUTH_METHOD=apikey
      - MCP_TRANSPORT=stdio
      - RATE_LIMIT=100
      - LOG_LEVEL=info
    volumes:
      - ./logs:/app/logs
    restart: unless-stopped

日历同步集成

此 MCP 服务器专为与日历同步系统无缝协作而设计：

与 Google 日历同步兼容

• 会议实体包含 googleEventId 字段，用于同步跟踪
• 通过电子邮件查找用户，用于参会人员管理
• 日期范围过滤，实现高效同步操作
• 通过 contactsIds 和 usersIds 关联参会人员

同步预防功能

• 全面的实体跟踪，防止重复创建
• 支持外部系统标识符
• 强大的同步操作错误处理

工作流集成

// 典型的日历同步工作流
const existingMeetings = await client.callTool('search_meetings', {
  dateFrom: syncStartDate,
  dateTo: syncEndDate
});

const user = await client.callTool('get_user_by_email', {
  emailAddress: assignedUserEmail
});

// 从外部日历创建会议
for (const externalEvent of externalEvents) {
  await client.callTool('create_meeting', {
    name: externalEvent.title,
    dateStart: externalEvent.start,
    dateEnd: externalEvent.end,
    googleEventId: externalEvent.id,
    description: externalEvent.description
  });
}

故障排除

常见问题

连接失败

# 测试基本连接性
node test-connection.js

# 检查环境变量
npm run test:config

# 测试特定端点
curl -H "X-Api-Key: YOUR_API_KEY" http://your-espocrm.com/api/v1/App/user

认证问题

• 验证 API 密钥是否正确且有效
• 检查 EspoCRM 中的用户权限
• 确保用户已启用 API 访问
• 验证正确的 API 端点格式

会议创建问题

• 确保提供了必需字段（名称、开始日期、结束日期）
• 验证日期格式是否为 ISO 8601（YYYY-MM-DDTHH:mm:ss）
• 检查用户是否有创建会议的权限
• 在关联前验证联系人与用户 ID 是否存在

用户搜索问题

• 验证用户是否有权限访问用户实体
• 检查系统中是否存在用户
• 确保电子邮件地址格式正确

调试模式

启用调试日志：

LOG_LEVEL=debug

查看详细日志：

tail -f logs/espocrm-mcp.log

连接诊断

测试特定 API 端点：

# 测试用户端点
curl -H "X-Api-Key: YOUR_KEY" http://your-espocrm.com/api/v1/App/user

# 测试会议搜索
curl -H "X-Api-Key: YOUR_KEY" "http://your-espocrm.com/api/v1/Meeting?maxSize=1"

# 测试用户搜索  
curl -H "X-Api-Key: YOUR_KEY" "http://your-espocrm.com/api/v1/User?maxSize=1"

API 参考

工具模式

所有工具使用 Zod 模式进行验证。关键模式包括：

联系人模式

{
  firstName: string,
  lastName: string,
  emailAddress?: string,
  phoneNumber?: string,
  title?: string,
  department?: string,
  accountId?: string,
  description?: string
}

会议模式

{
  name: string,
  dateStart: string,        // ISO 8601 格式
  dateEnd: string,          // ISO 8601 格式
  location?: string,
  description?: string,
  status?: 'Planned' | 'Held' | 'Not Held',
  parentType?: string,
  parentId?: string,
  contactsIds?: string[],   // 联系人 ID 数组
  usersIds?: string[],      // 用户 ID 数组
  googleEventId?: string    // 用于日历同步
}

用户模式

{
  userName: string,
  firstName?: string,
  lastName?: string,
  emailAddress?: string,
  phoneNumber?: string,
  isActive?: boolean,
  type?: 'admin' | 'regular' | 'portal' | 'api'
}

任务模式

{
  name: string,
  assignedUserId?: string,
  parentType?: 'Lead' | 'Account' | 'Contact' | 'Opportunity',
  parentId?: string,
  status?: 'Not Started' | 'Started' | 'Completed' | 'Canceled' | 'Deferred',
  priority?: 'Low' | 'Normal' | 'High' | 'Urgent',
  dateEnd?: string,         // 截止日期，YYYY-MM-DD 格式
  description?: string
}

潜在客户模式

{
  firstName: string,
  lastName: string,
  emailAddress?: string,
  phoneNumber?: string,
  accountName?: string,     // 公司名称
  website?: string,
  status?: 'New' | 'Assigned' | 'In Process' | 'Converted' | 'Recycled' | 'Dead',
  source: 'Call' | 'Email' | 'Existing Customer' | 'Partner' | 'Public Relations' | 'Web Site' | 'Campaign' | 'Other',
  industry?: string,
  assignedUserId?: string,
  description?: string
}

团队模式

{
  name: string,
  description?: string,
  positionList?: string[],  // 团队中的可用职位
}

通用实体模式

{
  entityType: string,       // 实体类型名称（例如，'Contact'，'CustomProduct'）
  data: {                   // 灵活的键值对
    [key: string]: any
  },
  // 搜索/获取操作可选
  filters?: {
    [field: string]: any
  },
  select?: string[],        // 要检索的字段
  orderBy?: string,
  order?: 'asc' | 'desc'
}

通话模式

{
  name: string,
  status?: 'Planned' | 'Held' | 'Not Held',
  direction?: 'Inbound' | 'Outbound',
  duration?: number,        // 持续时间，以秒为单位
  parentType?: string,      // 相关实体类型
  parentId?: string,        // 相关实体 ID
  assignedUserId?: string,
  description?: string
}

案例模式

{
  name: string,
  status?: 'New' | 'Assigned' | 'Pending' | 'Closed' | 'Rejected' | 'Duplicate',
  priority?: 'Low' | 'Normal' | 'High' | 'Urgent',
  type?: string,            // 案例类型
  accountId?: string,       // 相关账户
  contactId?: string,       // 相关联系人
  assignedUserId?: string,
  description?: string
}

备注模式

{
  parentType: string,       // 备注所关联的实体类型
  parentId: string,         // 备注所关联的实体 ID
  post: string,             // 备注内容
  data?: {                  // 额外的备注数据
    isInternal?: boolean,   // 内部备注标志
    [key: string]: any
  }
}

关系模式

{
  entityType: string,       // 源实体类型
  entityId: string,         // 源实体 ID
  relatedEntityType: string, // 目标实体类型
  relatedEntityId: string,  // 目标实体 ID
  relationshipName: string  // 关系字段名称
}

团队管理操作

// 将用户添加到团队
{
  userId: string,
  teamId: string,
  position?: string         // 团队内的可选职位
}

// 角色分配
{
  userId: string,
  roleId: string
}

搜索参数

{
  searchTerm?: string,
  limit?: number,           // 默认值：20，最大值：200
  offset?: number,          // 默认值：0
  createdFrom?: string,     // YYYY-MM-DD 格式
  createdTo?: string,       // YYYY-MM-DD 格式
  modifiedFrom?: string,    // YYYY-MM-DD 格式
  modifiedTo?: string,      // YYYY-MM-DD 格式
  // 特定实体过滤器...
}

响应格式

标准列表响应

{
  "total": 150,
  "list": [
    {
      "id": "entity123",
      "name": "实体名称",
      "createdAt": "2025-07-20T10:30:00Z",
      "modifiedAt": "2025-07-20T15:45:00Z"
    }
  ]
}

会议响应

{
  "id": "meeting123",
  "name": "项目会议",
  "status": "计划中",
  "dateStart": "2025-08-01T10:00:00Z",
  "dateEnd": "2025-08-01T11:00:00Z",
  "location": "A 会议室",
  "assignedUserName": "约翰·多伊",
  "contacts": ["contact1", "contact2"],
  "googleEventId": "google_event_123"
}

性能考虑

分页

• 默认限制：20 条结果
• 最大限制：200 条结果
• 使用偏移量对大型数据集进行分页

速率限制

• 默认值：每分钟 100 个请求
• 可通过 RATE_LIMIT 环境变量进行配置
• 实现指数退避以处理速率限制

缓存

• 无内置缓存（建议在应用程序级别实现）
• 不缓存 EspoCRM API 响应，以确保数据新鲜度

批量操作

• 仅支持单个实体操作
• 对于批量操作，在应用程序级别遍历数组
• 处理大型数据集时考虑速率限制

安全最佳实践

API 密钥管理

• 仅将 API 密钥存储在环境变量中
• 定期轮换 API 密钥
• 使用具有最小所需权限的专用 API 用户
• 监控 API 使用日志

网络安全

• 对所有 EspoCRM 连接使用 HTTPS
• 对于敏感数据，考虑使用 VPN 或专用网络
• 如果你的 EspoCRM 实例支持，实现 IP 白名单

数据验证

• 使用 Zod 模式验证所有输入
• 应用清理以防止注入攻击
• 错误消息不暴露敏感系统信息

📄 许可证

本项目采用 MIT 许可证 - 有关详细信息，请参阅 LICENSE 文件。

支持

• 问题反馈：GitHub 问题
• 文档：查看 docs/ 目录以获取更多文档
• EspoCRM API：官方 EspoCRM API 文档
• MCP 规范：模型上下文协议文档

变更日志

版本 2.0.0 - AI 聊天机器人集成 🤖

• 完整的聊天机器人界面：可嵌入 EspoCRM 的浮动聊天气泡
• 自然语言处理：使用纯英语聊天来执行 CRM 操作
• WebSocket 通信：实时双向通信
• 访问 47 个 MCP 工具：通过对话界面实现完整的 CRM 功能
• 安全与速率限制：具备输入验证的生产级安全
• Docker 部署：与 MCP 服务器一起进行容器化的聊天机器人服务器部署
• 移动响应式：在所有设备上都有美观的界面
• EspoCRM 集成：与现有 EspoCRM 实例进行简单的三行集成
• AI 驱动：可选的 OpenAI 集成，实现高级自然语言理解
• 生产测试：全面的测试套件和演示界面

版本 1.5.0 - 第三阶段：完整的通信与关系管理

• 关系管理：3 个新工具，用于链接/取消链接实体和管理关系
• 通信工具：7 个新工具，用于通话、案例、备注和文档管理
• 实体关系操作：链接/取消链接任何实体，获取关系详细信息
• 通话管理：创建和搜索支持持续时间和方向跟踪的通话记录
• 案例管理：创建和搜索支持优先级和类型分类的支持案例
• 备注系统：为任何实体添加备注，支持内部/外部可见性控制
• 文档管理：创建支持文件附件的文档记录
• 高级格式化：为通话、案例和备注添加专门的格式化
• 工具数量：从 39 个扩展到 47 个全面工具（新增 8 个工具）

版本 1.4.0 - 第二阶段：完整的企业解决方案

• 团队与角色管理：7 个新工具，用于完整的用户/团队/角色管理
• 通用实体操作：5 个新工具，用于操作任何 EspoCRM 实体（包括自定义实体）
• 团队管理：添加/移除团队中的用户，分配职位，获取团队成员
• 角色分配：为用户分配角色并获取有效权限
• 通用实体支持：创建、读取、更新、删除和搜索任何实体类型
• 自定义实体支持：全面支持自定义 EspoCRM 实体和字段
• 增强的类型安全：添加了团队、角色和通用实体的 TypeScript 接口
• 工具数量：从 27 个扩展到 39 个全面工具（新增 12 个工具）

版本 1.3.0 - 第一阶段扩展

• 任务管理：5 个新工具，实现完整的任务生命周期管理（创建、搜索、获取、更新、分配）
• 潜在客户管理：5 个新工具，实现完整的潜在客户管道管理（创建、搜索、更新、转化、分配）
• 父关系：任务可以关联到潜在客户、账户、联系人或商机
• 潜在客户转化：一次操作将潜在客户转化为联系人、账户和商机
• 高级任务功能：优先级级别、截止日期、状态跟踪和用户分配
• 扩展搜索：任务和潜在客户搜索支持全面的过滤选项
• 类型安全：为所有新实体增强了 TypeScript 接口
• 工具数量：从 17 个扩展到 27 个全面工具

版本 1.2.0

• 增强的会议管理：实现会议的完整 CRUD 操作
• 用户管理：用户搜索和查找功能
• 高级日期过滤：所有搜索操作支持日期范围
• 日历同步兼容性：支持与 Google 日历集成
• 改进的错误处理：更好的错误消息和调试功能
• 连接修复：解决 API 端点兼容性问题

版本 1.1.0

• 扩展的实体支持：添加了全面的类型定义
• 增强的搜索：高级过滤功能
• 性能改进：优化 API 客户端和错误处理

版本 1.0.0

• 初始版本，全面支持 MCP 2024/2025
• 联系人、账户、商机的完整 CRUD 操作
• Docker 支持和全面测试
• 多种认证方法
• 生产级日志记录和错误处理

---

为现代 AI 应用提供企业级 EspoCRM 集成