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 集成