内容
# EspoCRM MCP 服务器
一个用于与 EspoCRM 无缝集成的综合模型上下文协议（MCP）服务器。该服务器使 AI 助手能够通过标准化接口与您的 EspoCRM 实例交互，为联系人、账户、机会、会议、用户、任务、潜在客户等提供完整的 CRUD 操作，并具备高级系统管理功能。
**新增：AI 聊天机器人集成** - 现包含一个完整的聊天机器人界面，可直接嵌入到您的 EspoCRM 中，提供对所有 47 个 MCP 工具的自然语言访问！
## 功能
### 核心功能
- **完整的 CRUD 操作** - 创建、读取、更新和删除实体
- **多实体支持** - 联系人、账户、机会、会议、用户、任务和潜在客户
- **高级搜索和筛选** - 灵活的搜索，支持日期范围、分页和复杂筛选
- **任务管理** - 完整的任务生命周期，支持父级关系和用户分配
- **潜在客户管理** - 完整的潜在客户流程，从创建到转换
- **会议管理** - 完整的会议日历集成，支持与会者管理
- **用户管理** - 全面的用户搜索和查找功能
- **实时验证** - 基于 Zod 的架构验证，适用于所有操作
- **全面的日志记录** - Winston 驱动的日志记录，支持多个日志级别
### 身份验证和安全
- **多种身份验证方法** - 支持 API 密钥和 HMAC 身份验证
- **安全配置** - 基于环境的配置管理
- **速率限制** - 内置的 API 保护速率限制
- **错误处理** - 强大的错误处理，支持详细日志记录
### 日历集成
- **会议操作** - 创建、搜索、更新和管理会议
- **与会者管理** - 将联系人和用户链接到会议
- **日期/时间筛选** - 高级日期范围搜索功能
- **谷歌日历同步兼容性** - 设计用于日历同步工作流
### AI 聊天机器人集成
- **浮动聊天窗口** - 美观、不侵入式的聊天气泡界面
- **自然语言处理** - 用普通英语聊天以执行 CRM 操作
- **实时通信** - WebSocket 驱动的即时响应
- **47 个 MCP 工具访问** - 通过聊天提供完整的 CRM 功能
- **EspoCRM 嵌入** - 直接集成到您的 EspoCRM 界面
- **移动响应** - 在所有设备上无缝运行
### 开发人员体验
- **TypeScript** - 完整的 TypeScript 支持，具备严格的类型检查
- **Docker 支持** - 容器化部署准备就绪
- **全面的测试** - 多个测试脚本和验证工具
- **MCP 2024/2025 合规** - 最新 MCP 规范支持
## 快速入门
### 先决条件
- Node.js 18+
- npm 或 yarn
- 具有 API 访问权限的 EspoCRM 实例
- 有效的 API 凭证
### 安装
1. **克隆仓库**
```bash
git clone https://github.com/zaphod-black/EspoMCP.git
cd EspoMCP
```
2. **安装依赖项**
```bash
npm install
```
3. **配置环境**
```bash
cp .env.example .env
# 编辑 .env 文件，填写您的 EspoCRM 凭证
```
4. **构建项目**
```bash
npm run build
```
5. **测试连接**
```bash
npm run test:config
```
## AI 聊天机器人快速入门
### 部署聊天机器人界面
1. **导航到聊天机器人目录**
```bash
cd chatbot-bridge
```
2. **安装依赖项**
```bash
npm install
```
3. **配置环境**
```bash
cp .env.example .env
# 编辑 .env 文件，填写您的 EspoCRM 设置
```
4. **启动聊天机器人服务器**
```bash
npm start
# 或使用 Docker：docker-compose up -d
```
5. **与 EspoCRM 集成**
将以下内容添加到您的 EspoCRM 页脚模板：
```html
<script>
window.ESPOCRM_CHAT_SERVER = 'http://your-server:3001';
</script>
<script src="http://your-server:3001/socket.io/socket.io.js"></script>
<script src="http://your-server:3001/api/widget.js"></script>
```
6. **试用演示**
访问 `http://localhost:3001/widget` 以查看聊天机器人在运行！
### 环境配置
创建 `.env` 文件并包含您的 EspoCRM 配置：
```env
# EspoCRM 配置
ESPOCRM_URL=https://your-espocrm-instance.com
ESPOCRM_API_KEY=your-api-key-here
ESPOCRM_AUTH_METHOD=apikey
# 可选：HMAC 身份验证
# ESPOCRM_SECRET_KEY=your-secret-key
# ESPOCRM_AUTH_METHOD=hmac
# 服务器配置（可选）
MCP_TRANSPORT=stdio
RATE_LIMIT=100
REQUEST_TIMEOUT=30000
LOG_LEVEL=info
```
### 必需配置
| 变量 | 描述 | 必需 | 默认值 |
|----------|-------------|----------|---------|
| `ESPOCRM_URL` | 您的 EspoCRM 实例 URL | 是 | - |
| `ESPOCRM_API_KEY` | 身份验证的 API 密钥 | 是 | - |
| `ESPOCRM_AUTH_METHOD` | 身份验证方法（`apikey` 或 `hmac`） | 是 | `apikey` |
| `ESPOCRM_SECRET_KEY` | HMAC 身份验证的密钥 | 否 | - |
| `MCP_TRANSPORT` | MCP 传输方法 | 否 | `stdio` |
| `RATE_LIMIT` | 每分钟请求数限制 | 否 | `100` |
| `REQUEST_TIMEOUT` | 请求超时（毫秒） | 否 | `30000` |
| `LOG_LEVEL` | 日志级别 | 否 | `info` |
## 可用工具
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 用户）
## 使用示例
### 任务管理
```javascript
// 创建一个分配给用户的任务，带有父级关系
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'
});
```
### 潜在客户管理
```javascript
// 创建一个新的潜在客户
await client.callTool('create_lead', {
firstName: 'John',
lastName: 'Smith',
emailAddress: 'john.smith@example.com',
accountName: 'Smith Industries',
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: 'Smith Industries - 企业交易',
opportunityAmount: 50000
});
```
### 团队和角色管理
```javascript
// 将用户添加到团队并分配职位
await client.callTool('add_user_to_team', {
userId: 'user123',
teamId: 'sales-team',
position: '销售经理'
});
// 获取团队的所有成员
await client.callTool('get_team_members', {
teamId: 'sales-team',
limit: 50
}
// 为权限管理将角色分配给用户
await client.callTool('assign_role_to_user', {
userId: 'user123',
roleId: 'manager-role'
}
// 按条件搜索团队
await client.callTool('search_teams', {
name: '销售',
description: '收入'
});
// 获取用户的有效权限
await client.callTool('get_user_permissions', {
userId: 'user123'
});
```
### 通用实体操作
```javascript
// 创建任何实体类型（包括自定义实体）
await client.callTool('create_entity', {
entityType: 'CustomProduct',
data: {
name: '高级小部件',
price: 199.99,
category: '电子产品',
inStock: true
}
}
// 搜索任何实体类型，支持灵活的筛选
await client.callTool('search_entity', {
entityType: 'CustomOrder',
filters: {
status: 'pending',
totalAmount: 1000,
customerType: 'enterprise'
},
select: ['id', 'orderNumber', 'customerName', 'totalAmount'],
orderBy: 'createdAt',
order: 'desc'
}
// 更新任何实体记录
await client.callTool('update_entity', {
entityType: 'CustomProduct',
entityId: 'prod123',
data: {
price: 179.99,
inStock: false,
lastModified: '2025-07-20T10:30:00Z'
}
}
// 删除任何实体记录
await client.callTool('delete_entity', {
entityType: 'CustomProduct',
entityId: 'prod123'
}
// 获取特定实体，支持字段选择
await client.callTool('get_entity', {
entityType: 'CustomOrder',
entityId: 'order456',
select: ['orderNumber', 'customerName', 'items', 'totalAmount']
});
```
### 关系管理
```javascript
// 将实体链接在一起（例如，将联系人链接到账户）
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'
});
```
### 通信工具
```javascript
// 创建通话记录
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: 'Technical',
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',
created',
name: 'Login Issues',
status: 'New',
priority: '高',
type: 'Technical',
accountId: 'account123',
description: '客户无法登录门户'
});
// 搜索聊天记录
await client.callTool('search_notes', {
parentType: 'Lead',
parentId: 'lead123',
createdFrom: '2025-07-01',
limit: 10
});
```
### AI 聊天机器人用法
嵌入式聊天机器人理解自然语言，可以执行任何 CRM 操作：
```javascript
// 用户可以输入的自然语言示例：
"创建一个名为 Sarah Johnson 的联系人，邮箱为 sarah@techcorp.com"
"查找软件行业的所有账户"
"显示大于 $50,000 的机会"
"创建一个跟进潜在客户 John Smith 的任务"
"明天 2 PM 安排一个会议"
"系统健康状态如何？"
"链接联系人 ID 123 到账户 TechCorp"
"在案例 #456 中添加注释 '客户对解决方案感到满意'"
```
### 会议管理
```javascript
// 创建具有与会者和日历集成的会议
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
});
```
### 用户管理
```javascript
// 按电子邮件查找用户
await client.callTool('get_user_by_email', {
emailAddress: 'john.doe@company.com'
});
// 搜索活跃用户
await client.callTool('search_users', {
isActive: true,
type: 'regular',
limit: 50
});
```
### 高级联系人搜索，支持日期筛选
```javascript
// 搜索过去一周创建的联系人
await client.callTool('search_contacts', {
searchTerm: 'manager',
createdFrom: '2025-07-13',
createdTo: '2025-07-20',
limit: 10
});
```
### 日历集成工作流
```javascript
// 完成日历同步的完整工作流
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: '与谷歌日历同步',
dateStart: '2025-08-15T14:00:00',
dateEnd: '2025-08-15T15:00:00',
googleEventId: 'google_event_123'
});
```
## 测试
### 自动化测试
该项目包含全面的测试工具：
```bash
# 测试配置和连接性
npm run test:config
# 测试 MCP 客户端功能
npm run test:client
# 运行单元测试
npm test
```
### 手动测试脚本
#### 连接测试
```bash
node test-connection.js
```
测试基本连接性、API 端点和身份验证。
#### 增强工具测试
```bash
node test-enhanced-tools.js
```
对所有增强功能进行全面测试，包括会议和用户。
#### 随机联系人生成
```bash
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`)
Contact、Account、Opportunity、Meeting、User 和相关实体的完整 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 构建和运行
```bash
# 构建 Docker 镜像
npm run docker:build
# 使用环境文件运行
npm run docker:run
```
### Docker Compose
```yaml
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 日历同步兼容性
- Meeting 实体包括 `googleEventId` 字段用于同步跟踪
- 通过电子邮件查找用户以进行与会者管理
- 日期范围过滤以实现高效的同步操作
- 通过 `contactsIds` 和 `usersIds` 进行与会者链接
### 同步预防功能
- 全面的实体跟踪以防止重复创建
- 支持外部系统标识符
- 强大的错误处理以进行同步操作
### 工作流集成
```javascript
// 典型日历同步工作流
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
});
}
```
## 故障排除
### 常见问题
#### 连接失败
```bash
# 测试基本连接性
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 在链接之前存在
#### 用户搜索问题
- 验证用户是否有权访问用户实体
- 检查系统是否存在用户
- 确保电子邮件地址正确格式化
### 调试模式
启用调试日志记录：
```env
LOG_LEVEL=debug
```
查看详细日志：
```bash
tail -f logs/espocrm-mcp.log
```
### 连接诊断
测试特定 API 端点：
```bash
# 测试用户端点
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 模式进行验证。关键模式包括：
#### 联系人模式
```typescript
{
firstName: string,
lastName: string,
emailAddress?: string,
phoneNumber?: string,
title?: string,
department?: string,
accountId?: string,
description?: string
}
```
#### 会议模式
```typescript
{
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 // 用于日历同步
}
```
#### 用户模式
```typescript
{
userName: string,
firstName?: string,
lastName?: string,
emailAddress?: string,
phoneNumber?: string,
isActive?: boolean,
type?: 'admin' | 'regular' | 'portal' | 'api'
}
```
#### 任务模式
```typescript
{
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
}
```
#### 线索模式
```typescript
{
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
}
```
#### 团队模式
```typescript
{
name: string,
description?: string,
positionList?: string[], // 团队中的可用职位
}
```
#### 通用实体模式
```typescript
{
entityType: string, // 实体类型名称（例如：'Contact'，'CustomProduct'）
data: { // 灵活的键值对
[key: string]: any
},
// 搜索/获取操作时可选
filters?: {
[field: string]: any
},
select?: string[], // 要检索的字段
orderBy?: string,
order?: 'asc' | 'desc'
}
```
#### 调用模式
```typescript
{
name: string,
status?: 'Planned' | 'Held' | 'Not Held',
direction?: 'Inbound' | 'Outbound',
duration?: number, // 秒为单位的持续时间
parentType?: string, // 相关实体类型
parentId?: string, // 相关实体 ID
assignedUserId?: string,
description?: string
}
```
#### 工单模式
```typescript
{
name: string,
status?: 'New' | 'Assigned' | 'Pending' | 'Closed' | 'Rejected' | 'Duplicate',
priority?: 'Low' | 'Normal' | 'High' | 'Urgent',
type?: string, // 工单类型
accountId?: string, // 相关账户
contactId?: string, // 相关联系人
assignedUserId?: string,
description?: string
}
```
#### 注释模式
```typescript
{
parentType: string, // 注释附加到的实体类型
parentId: string, // 注释附加到的实体 ID
post: string, // 注释内容
data?: { // 附加注释数据
isInternal?: boolean, // 内部注释标志
[key: string]: any
}
}
```
#### 关系模式
```typescript
{
entityType: string, // 源实体类型
entityId: string, // 源实体 ID
relatedEntityType: string, // 目标实体类型
relatedEntityId: string, // 目标实体 ID
relationshipName: string // 关系字段名称
}
```
#### 团队管理操作
```typescript
// 将用户添加到团队
{
userId: string,
teamId: string,
position?: string // 团队中的可选职位
}
// 角色分配
{
userId: string,
roleId: string
}
```
#### 搜索参数
```typescript
{
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 格式
// 实体特定过滤器...
}
```
### 响应格式
#### 标准列表响应
```json
{
"total": 150,
"list": [
{
"id": "entity123",
"name": "实体名称",
"createdAt": "2025-07-20T10:30:00Z",
"modifiedAt": "2025-07-20T15:45:00Z"
}
]
}
```
#### 会议响应
```json
{
"id": "meeting123",
"name": "项目会议",
"status": "Planned",
"dateStart": "2025-08-01T10:00:00Z",
"dateEnd": "2025-08-01T11:00:00Z",
"location": "会议室 A",
"assignedUserName": "John Doe",
"contacts": ["contact1", "contact2"],
"googleEventId": "google_event_123"
}
```
## 性能考虑
### 分页
- 默认限制：20 个结果
- 最大限制：200 个结果
- 使用 offset 进行大数据集分页
### 限流
- 默认：每分钟 100 次请求
- 可通过 RATE_LIMIT 环境变量配置
- 实现速率限制的指数退避
### 缓存
- 无内置缓存（建议在应用程序级别实现）
- EspoCRM API 响应不缓存以确保数据新鲜度
### 批量操作
- 仅支持单个实体操作
- 对于批量操作，请在应用程序级别遍历数组
- 处理大数据集时请考虑速率限制
## 安全最佳实践
### API 密钥管理
- 仅将 API 密钥存储在环境变量中
- 定期轮换 API 密钥
- 使用专用的 API 用户，并具有最低要求的权限
- 监控 API 使用日志
### 网络安全
- 为所有 EspoCRM 连接使用 HTTPS
- 考虑为敏感数据使用 VPN 或私有网络
- 如果您的 EspoCRM 实例支持，请实施 IP 白名单
### 数据验证
- 所有输入都使用 Zod 模式进行验证
- 应用净化以防止注入攻击
- 错误消息不会公开敏感的系统信息
## 贡献
1. 复刻仓库
2. 创建功能分支（`git checkout -b feature/enhanced-search`）
3. 提交更改（`git commit -m 'Add enhanced search capabilities'`）
4. 推送到分支（`git push origin feature/enhanced-search`）
5. 打开拉取请求
### 开发指南
- 遵循 TypeScript 最佳实践，并使用严格的类型定义
- 为新功能添加全面的测试
- 更新任何新功能的文档
- 确保所有测试通过后再提交
- 遵循现有的代码格式和结构
- 添加适当的错误处理和日志记录
### 测试要求
- 新功能单元测试
- 带有模拟 EspoCRM 响应的集成测试
- 使用真实 EspoCRM 实例的手动测试
- 新功能文档更新
## 许可证
该项目在 MIT 许可证下获得许可 - 有关详细信息，请参阅 [LICENSE](LICENSE) 文件。
## 支持
- **问题**: [GitHub Issues](https://github.com/zaphod-black/EspoMCP/issues)
- **文档**: 在 `docs/` 目录中查看附加文档
- **EspoCRM API**: [官方 EspoCRM API 文档](https://docs.espocrm.com/development/api/)
- **MCP 规范**: [Model Context Protocol 文档](https://spec.modelcontextprotocol.io/)
## 更新日志
### 版本 2.0.0 - AI 聊天机器人集成 🤖
- **完整的聊天机器人界面**: 嵌入 EspoCRM 的浮动聊天气泡
- **自然语言处理**: 用纯英语聊天以执行 CRM 操作
- **WebSocket 通信**: 与聊天机器人服务器的实时双向通信
- **47 个 MCP 工具访问**: 通过对话界面提供完整的 CRM 功能
- **安全和速率限制**: 生产就绪的安全功能，具有输入验证
- **Docker 部署**: 容器化聊天机器人服务器与 MCP 服务器一起部署
- **移动响应式界面**: 适用于所有设备的漂亮界面
- **EspoCRM 集成**: 与现有的 EspoCRM 实例的简单 3 行集成
- **AI 集成**: 可选的 OpenAI 集成以实现高级自然语言理解
- **生产测试**: 全面的测试套件和演示界面
### 版本 1.5.0 - 阶段 3 完整的通信和关系管理
- **关系管理**: 3 个用于链接/取消链接实体和管理关系的工具
- **通信工具**: 7 个用于调用、工单、注释和文档管理的工具
- **实体关系操作**: 链接/取消链接任何实体并获取关系详细信息
- **调用管理**: 创建和搜索调用记录，持续时间和方向跟踪
- **工单管理**: 创建和搜索支持工单，具有优先级和类型分类
- **注释系统**: 将注释添加到任何实体，具有内部/外部可见性控制
- **文档管理**: 创建文档记录，具有文件附件支持
- **高级格式化**: 为调用、工单和注释添加专用格式化
- **工具数量**: 从 39 扩展到 47 个全面的工具 (+8 个新工具)
### 版本 1.4.0 - 阶段 2 完整的企业解决方案
- **团队和角色管理**: 7 个用于完整的用户/团队/角色管理的工具
- **通用实体操作**: 5 个用于操作任何 EspoCRM 实体（包括自定义实体）的工具
- **团队管理**: 添加/删除用户到团队，分配职位，获取团队成员
- **角色分配**: 将角色分配给用户并获取有效权限
- **通用实体支持**: 创建、读取、更新、删除和搜索任何实体类型
- **自定义实体支持**: 对自定义 EspoCRM 实体和字段提供完整支持
- **增强类型安全性**: 为所有新实体添加 TypeScript 接口
- **工具数量**: 从 27 扩展到 39 个全面的工具 (+12 个新工具)
### 版本 1.3.0 - 阶段 1 扩展
- **任务管理**: 完整的任务生命周期，具有 5 个新工具（创建、搜索、获取、更新、分配）
- **线索管理**: 完整的线索管道，具有 5 个新工具（创建、搜索、更新、转换、分配）
- **父关系**: 任务可以链接到线索、账户、联系人或机会
- **线索转换**: 将线索转换为联系人、账户和机会在一个操作中
- **高级任务功能**: 优先级级别、截止日期、状态跟踪和用户分配
- **扩展搜索**: 任务和线索搜索，具有全面的过滤选项
- **类型安全性**: 为所有新实体增强 TypeScript 接口
- **工具数量**: 从 17 扩展到 27 个全面的工具
### 版本 1.2.0
- **增强会议管理**: 完整的会议 CRUD 操作
- **用户管理**: 用户的搜索和查找功能
- **高级日期过滤**: 所有搜索操作的日期范围支持
- **日历同步兼容性**: Google 日历集成支持
- **改进的错误处理**: 更好的错误消息和调试
- **连接修复**: 解决 API 端点兼容性问题
### 版本 1.0.0
- 初始发布，具有完整的 MCP 2024/2025 支持
- 完整的 CRUD 操作联系人、账户、机会
- Docker 支持和全面的测试
- 多种身份验证方法
- 生产就绪的日志处理和错误处理
---
**企业级 EspoCRM 集成，用于现代 AI 应用**
连接信息
猜你喜欢
暂无推荐服务器