JinDaGe - espomcp MCP Details

article

README

🚀 EspoCRM MCP 服务器

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

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

🚀 快速开始

前提条件

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

安装

克隆仓库

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

✨ 主要特性

核心功能

完整的 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)：所有实体类型的专业格式化函数，确保输出格式一致。

开发工作流

对 src/ 中的源文件进行更改
使用 npm run build 构建项目
使用 npm run test:config 测试更改
使用 npm run test:client 测试增强功能
使用 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 集成