Espocrm MCP Auth0

具有Auth0身份验证的EspoCRM MCP服务器

用于EspoCRM的具有Auth0身份验证和授权的模型上下文协议（MCP）服务器。

Demo

概述

该项目提供了一个与EspoCRM集成的MCP服务器，允许AI助手和其他MCP客户端通过标准化的接口与EspoCCM数据进行交互。服务器包括：

• Auth0身份验证：使用Auth0进行基于令牌的安全身份验证
• 基于范围的授权：使用OAuth作用域的粗粒度访问控制
• FGA精细授权 （可选）：使用OpenFGA的实体级、基于关系的访问控制
• EspoCRM集成：EspoCRM的完整API客户端，同时支持API密钥和HMAC身份验证
• 综合MCP工具：用于管理联系人、帐户、潜在客户、机会、会议、任务、电话、案例、笔记、用户、团队和通用实体操作的全功能工具

特性

已实施的工具

该项目提供了10多个类别的MCP工具，用于全面的EspoCRM管理。 看 完整工具参考 下面是完整的列表，包括描述和范围要求。

身份验证和授权

所有工具（除 health_check)需要具有适当作用域的有效Auth0身份验证：

• espocrm:contacts:read / espocrm:contacts:write
• espocrm:accounts:read / espocrm:accounts:write
• espocrm:leads:read / espocrm:leads:write
• espocrm:opportunities:read / espocrm:opportunities:write
• espocrm:meetings:read / espocrm:meetings:write
• espocrm:tasks:read / espocrm:tasks:write
• espocrm:calls:read / espocrm:calls:write
• espocrm:cases:read / espocrm:cases:write
• espocrm:notes:read / espocrm:notes:write
• espocrm:users:read
• espocrm:teams:read / espocrm:teams:write
• espocrm:entities:read / espocrm:entities:write

细粒度授权（FGA）

启用FGA后，将对以下对象执行其他实体级权限检查 20+工具 跨多种实体类型：

• 联系：所有者（完整）、分配用户（读取/更新）、团队成员（读取）、经理（完整）
• 账户：所有者（完整）、分配的用户（读取/更新）、团队成员（读取）
• 铅：所有者（完整）、分配的用户（读取/更新）、团队成员（读取）
• 会议：所有者（完整），分配的用户（读取/更新）
• 任务：所有者（完整）、分配用户（读取/更新）、受让人（读取）
• 案例：所有者（完整），分配的用户（读取/更新）
• 机会：所有者（完整），分配的用户（读取/更新）
• 通用实体 (get_entity, update_entity, delete_entity, link_entities, unlink_entities)：运行时的动态实体类型检查

请参阅 完整工具参考 FGA列显示每个工具的详细信息。

FGA通过结合基于范围（粗粒度）和实体级（细粒度）的授权来提供深度防御安全。权限规则在中以声明方式定义 src/tools/fga_config.py 并通过装饰器或运行时检查自动应用。

关键优势

该体系结构为多用户和企业场景提供了优于传统的基于API密钥的方法的显著优势。

集中式身份管理

Auth0集成优势：

• 单点登录（SSO）：用户可以通过一次登录访问多个应用程序
• 社会化登录：支持谷歌、GitHub、微软和其他身份提供商
• 多因素身份验证（MFA）：内置支持以增强安全性
• 密码策略：集中式密码管理和策略
• 用户生命周期：自动配置和取消配置工作流

企业级授权

多层安全模型：

Request → Auth0 Token Validation → Scope Check → FGA Check → EspoCRM API
         (Authentication)         (Coarse-grained) (Fine-grained)

1. 第1层-OAuth作用域 （API级别授权）：

- espocrm:contacts:read -用户可以读取联系人吗？ - espocrm:contacts:write -用户可以创建/更新联系人吗？

1. 第2层-FGA （实体级授权）：

- 用户Alice可以阅读联系人#123吗？ - 用户Bob可以更新Lead#456吗？ - 基于关系动态计算的权限

细粒度访问控制：

• 实体级权限（不仅仅是实体类型级）
• 基于关系的访问（所有者、指定用户、团队成员）
• 分层权限（经理继承团队成员的权限）
• 无需更改代码的动态授权规则

部署架构的好处

传统API关键方法：

User A ──> Server Instance A ──> EspoCRM (API Key A)
User B ──> Server Instance B ──> EspoCRM (API Key B)
User C ──> Server Instance C ──> EspoCRM (API Key C)

Problems:
❌ Each user needs independent deployment
❌ Resource waste (multiple server instances)
❌ Scattered configuration, hard to manage
❌ No centralized monitoring or auditing

本项目（Auth0+FGA）：

                    ┌─────────────────┐
User A ──> Auth0 ───>│                 │
User B ──> Auth0 ───>│  MCP Server     ├──> EspoCRM (Service Account)
User C ──> Auth0 ───>│  (Single Instance)│
                    └─────────────────┘

Advantages:
✅ Single deployment, centralized management
✅ Resource efficient (one instance serves all users)
✅ Unified monitoring and auditing
✅ Users don't manage API keys

增强的安全性

基于令牌的安全性：

• 短期访问令牌（自动过期）
• 刷新令牌轮换
• 令牌撤销功能
• 没有API密钥暴露给最终用户

服务帐户模式：

• 单一服务帐户连接到EspoCRM
• 在MCP服务器层强制执行用户权限
• API密钥从未向用户公开
• 更容易轮换和管理凭据

合规就绪：

• Auth0中的集中审核日志
• 会话管理和跟踪
• 支持合规要求（SOC2、GDPR、HIPAA）

用例

理想用途：

1. 多应用环境

- 多个应用程序访问相同的EspoCRM数据 - 需要跨web、移动和API客户端的SSO - 示例：销售门户、客户门户、管理仪表板

1. 复杂的组织结构

- 矩阵组织（多个团队中的用户） - 分层权限（管理员→ 团队→ 实体） - 跨部门访问规则 - 示例：区域经理访问其所在区域的数据

1. 外部用户访问

- 具有自助访问功能的客户门户 - 具有有限权限的合作伙伴集成 - 承包商获得临时许可进入 - 示例：客户仅查看其帐户数据

1. 合规

- HIPAA（医疗数据访问控制） - GDPR（数据隐私和访问权） - SOX（财务数据隔离） - 示例：具有患者数据访问记录的医疗CRM

1. 动态权限要求

- 经常更改权限规则 - 访问控制的复杂业务逻辑 - 需要在不部署代码的情况下修改权限 - 示例：基于项目的访问权限、季节性权限

比较摘要

安装

先决条件

• Python 3.10或更高版本
• pip（Python包管理器）
• 已配置API的Auth0帐户
• 具有API访问权限的EspoCRM实例

设置

1. 克隆仓库

   cd EspoCRM-MCP-Auth0

1. 创建并激活虚拟环境

   # Create virtual environment
   python -m venv venv

   # Activate virtual environment
   # On Linux/macOS:
   source venv/bin/activate

   # On Windows:
   # venv\Scripts\activate

1. 安装依赖项

   pip install -r requirements.txt

1. 配置环境变量

   cp .env.example .env

编辑 .env 根据您的配置：

   # Auth0 Configuration
   AUTH0_DOMAIN=your-tenant.us.auth0.com
   AUTH0_AUDIENCE=https://your-api-identifier
   MCP_SERVER_URL=http://localhost:3001

   # EspoCRM Configuration
   ESPOCRM_URL=https://your-espocrm-instance.com
   ESPOCRM_API_KEY=your-api-key
   ESPOCRM_SECRET_KEY=your-secret-key-for-hmac
   ESPOCRM_AUTH_METHOD=apikey

   # Server Configuration
   PORT=3001
   DEBUG=true
   CORS_ORIGINS=*

   # OAuth Configuration (Optional - for dynamic token acquisition via Auth0 Universal Login)
   OAUTH_ENABLED=false
   OAUTH_CLIENT_ID=your-auth0-application-client-id
   OAUTH_CLIENT_SECRET=your-auth0-application-client-secret
   OAUTH_SECRET_KEY=your-random-secret-key-for-session-encryption

   # FGA Configuration (Optional - for fine-grained authorization)
   FGA_ENABLED=false
   FGA_API_URL=https://api.us1.fga.dev
   FGA_API_ISSUER=auth.fga.dev
   FGA_API_AUDIENCE=https://api.us1.fga.dev/
   FGA_STORE_ID=your-fga-store-id
   FGA_CLIENT_ID=your-fga-client-id
   FGA_CLIENT_SECRET=your-fga-client-secret
   FGA_AUTHORIZATION_MODEL_ID=your-authorization-model-id

1. （可选）配置OAuth以进行动态令牌获取

如果您希望MCP客户端（例如CherryStudio）通过Auth0通用登录进行交互式身份验证，请启用OAuth。看 OAuth设置 详细说明。

1. （可选）初始化FGA

如果你想使用细粒度授权：

   # First, configure FGA credentials in .env
   # Then run the initialization script
   python scripts/fga_init.py

这将创建授权模型和示例数据。将返回的型号ID添加到您的 .env 文件。

1. （可选）初始化演示数据

在EspoCRM中创建具有匹配FGA权限的示例实体进行测试：

   python scripts/demo_init.py ""

这 auth0_user_sub 是您的Auth0用户ID（例如。， auth0|6abc123def456)，您可以在中找到 Auth0仪表板→ 用户管理→ 用户→ 用户ID.

此脚本将：

- 在EspoCRM中创建示例帐户、联系人和潜在客户 - 编写FGA元组，授予您对这些实体的Auth0用户所有者权限

> 备注：要求EspoCRM正在运行，并且API用户具有创建权限。如果未配置FGA，则只会创建EspoCRM实体。

1. 运行服务器

   python -m src.server

或者直接使用uvicorn：

   uvicorn src.server:app --port 3001

配置

Auth0设置

1. 在Auth0仪表板中创建API
2. 将API标识符设置为 AUTH0_AUDIENCE
3. 为API配置作用域：

- espocrm:contacts:read / espocrm:contacts:write - espocrm:accounts:read / espocrm:accounts:write - espocrm:leads:read / espocrm:leads:write - espocrm:opportunities:read / espocrm:opportunities:write - espocrm:meetings:read / espocrm:meetings:write - espocrm:tasks:read / espocrm:tasks:write - espocrm:calls:read / espocrm:calls:write - espocrm:cases:read / espocrm:cases:write - espocrm:notes:read / espocrm:notes:write - espocrm:users:read - espocrm:teams:read / espocrm:teams:write - espocrm:entities:read / espocrm:entities:write

scopes

EspoCRM设置

1. 为API访问创建角色:

- 前往EspoCRM 行政 → 角色 → 创建角色 - 设置名称（例如。， API Full Access) - 授予 读, 创造, 编辑, 删除 您需要的实体类型（帐户、联系人、潜在客户等）的权限 - 保存角色

roles

1. 创建API用户:

- 首选 行政 → API用户 → 创建API用户 - 分配步骤1中创建的角色 - 选择身份验证方法：

API密钥验证 （更简单）：

- 集 ESPOCRM_AUTH_METHOD=apikey - 集 ESPOCRM_API_KEY 到生成的API密钥

HMAC身份验证 （更安全）：

- 集 ESPOCRM_AUTH_METHOD=hmac - 设置两者 ESPOCRM_API_KEY 和 ESPOCRM_SECRET_KEY

> 备注：如果API用户未分配角色，则所有API请求都将返回 403 Forbidden.

api

FGA设置（可选）

细粒度授权提供实体级访问控制。要启用FGA：

1. 创建FGA帐户:

- 注册地址： Okta FGA 或使用 OpenFGA - 创建新店铺 - 生成客户端凭据

1. 配置FGA:

- 集 FGA_ENABLED=true 在你的 .env 文件 - 添加您的FGA凭据： - FGA_API_URL：FGA API端点（例如。， https://api.us1.fga.dev) - FGA_STORE_ID：您的FGA商店ID - FGA_CLIENT_ID：您的FGA客户ID - FGA_CLIENT_SECRET：您的FGA客户机密 - FGA_API_ISSUER：（可选）默认值为 auth.fga.dev - FGA_API_AUDIENCE：（可选）默认值源自API URL

1. 初始化授权模型:

   python scripts/fga_init.py

这将为EspoCRM实体创建授权模型并写入示例元组。脚本将输出授权模型ID-将其添加到您的 .env 归档 FGA_AUTHORIZATION_MODEL_ID.

> 备注：The fga_init.py 脚本定义了FGA类型 contact, account，以及 lead 仅适用于基本演示。完整的工具集还使用FGA检查 meeting, task, case，以及 opportunity 实体，以及通过通用工具生成的动态实体类型。对于生产使用，在中扩展授权模型 fga_init.py 或您的FGA控制台，以包含这些额外的类型定义。看 src/tools/fga_config.py 获取FGA规则的完整列表。

1. 运作原理:

- FGA规则在中以声明方式定义 src/tools/fga_config.py （20多种不同工具的规则） - 对于静态实体类型： @apply_fga("tool_name") 装饰器自动应用规则 - 对于动态实体类型（通用工具）：运行时 check_fga_dynamic() 通话时检查 - 同时应用范围和FGA检查（深度防御） - 如果未配置FGA，则仅使用基于范围的授权 - 初始化脚本可以安全地运行多次（处理重复项）

fga_model

fga_tuple

OAuth设置（可选）

OAuth通过Auth0通用登录启用动态令牌获取，允许MCP客户端进行交互身份验证，而无需手动管理令牌。

1. 创建Auth0应用程序:

- 转到Auth0仪表板→ 应用程序→ 创建应用 - 选择“常规Web应用程序” - 注意客户端ID和客户端密码

1. 配置回调URL （在应用程序的“设置”选项卡中）：

- 添加 http://localhost:3001/auth/callback 到允许的回调URL - 添加 http://localhost:3001 允许的网络起源 - 添加 http://localhost:3001 到允许的注销URL

1. 配置API:

- 确保API配置有正确的作用域 - API标识符应匹配 AUTH0_AUDIENCE

1. 生成 OAUTH_SECRET_KEY:

   python -c "import secrets; print(secrets.token_urlsafe(32))"

1. 更新 .env:

   OAUTH_ENABLED=true
   OAUTH_CLIENT_ID=
   OAUTH_CLIENT_SECRET=
   OAUTH_SECRET_KEY=

与AI助手集成

此MCP服务器可以与Claude Desktop或CherryStudio等AI助手集成，以实现与EspoCRM数据的自然语言交互。

与CherryStudio集成

1. 启动MCP服务器:

   cd EspoCRM-MCP-Auth0/EspoCRM-MCP-Auth0
   source venv/bin/activate
   python -m src.server

1. 配置CherryStudio:

- 服务器类型：流式HTTP - 服务器URL: http://localhost:3001 - 不需要承载令牌

1. 身份验证流程 （自动）：

- CherryStudio发送请求→ 服务器返回401包含OAuth元数据 - CherryStudio通过以下方式发现Auth0 /.well-known/oauth-protected-resource - 浏览器打开Auth0通用登录页面进行用户身份验证 - 登录后，CherryStudio会自动收到访问令牌 - 令牌包含在所有后续MCP请求中

cherrystudio

用法示例

以下是使用自然语言通过Claude或CherryStudio使用MCP服务器的实际示例：

1.健康检查

用户：“检查EspoCRM连接状态”

AI助手调用: health_check()

结果:

{
  "status": "healthy",
  "user": "admin",
  "version": "7.5.0"
}

2.创建联系人

用户：“在EspoCRM中创建新联系人：

• 姓名：约翰·史密斯
• 电子邮件：john.smith@example.com
• 电话：+1-555-0100
• 职务：销售经理”

AI助手调用:

create_contact(
    first_name="John",
    last_name="Smith",
    email_address="john.smith@example.com",
    phone_number="+1-555-0100",
    title="Sales Manager"
)

结果: Successfully created contact: John Smith (ID: 123abc)

3.搜索联系人

用户：“查找姓氏为‘Smith’的所有联系人”

AI助手调用:

search_contacts(search_term="Smith")

结果:

Found 3 contacts:
  - ID: 123abc, Name: John Smith
  - ID: 456def, Name: Jane Smith
  - ID: 789ghi, Name: Bob Smith

4.获取联系方式

用户：“获取联系人ID 123abc的详细信息”

AI助手调用:

get_contact(contact_id="123abc")

结果:

{
  "id": "123abc",
  "firstName": "John",
  "lastName": "Smith",
  "emailAddress": "john.smith@example.com",
  "phoneNumber": "+1-555-0100",
  "title": "Sales Manager",
  "accountId": "acc123",
  "accountName": "ABC Corporation",
  "createdAt": "2024-01-15 10:30:00",
  "modifiedAt": "2024-01-15 10:30:00"
}

5.创建帐户

用户：“创建一家新公司：

• 名称：技术解决方案股份有限公司。
• 类型：客户
• 所属行业：信息技术
• 网站：https://techsolutions.com
• 电子邮件：info@techsolutions.com"

AI助手调用:

create_account(
    name="Tech Solutions Inc.",
    account_type="Customer",
    industry="Information Technology",
    website="https://techsolutions.com",
    email_address="info@techsolutions.com"
)

结果: Successfully created account: Tech Solutions Inc. (ID: acc456)

6.搜索帐户

用户：“查找信息技术行业的所有公司”

AI助手调用:

search_accounts(industry="Information Technology")

结果:

Found 2 accounts:
  - ID: acc456, Name: Tech Solutions Inc.
  - ID: acc789, Name: Data Systems Corp.

7.创建潜在客户

用户：“创建新的销售线索：

• 姓名：爱丽丝·约翰逊
• 来源：网站
• 电子邮件：alice.johnson@example.com
• 公司：技术解决方案股份有限公司。
• 状态：新建
• 注：通过网站联系表提交”

AI助手调用:

create_lead(
    first_name="Alice",
    last_name="Johnson",
    source="Website",
    email_address="alice.johnson@example.com",
    account_name="Tech Solutions Inc.",
    status="New",
    description="Submitted through website contact form"
)

结果: Successfully created lead: Alice Johnson (ID: lead789)

8.搜索潜在客户

用户：“显示网站上的所有新线索”

AI助手调用:

search_leads(source="Website", status="New")

结果:

Found 5 leads:
  - ID: lead789, Name: Alice Johnson
  - ID: lead101, Name: Bob Williams
  - ID: lead102, Name: Carol Davis
  - ID: lead103, Name: David Brown
  - ID: lead104, Name: Eve Wilson

9.通用实体搜索

用户：“寻找以‘技术’为名的机会”

AI助手调用:

search_entity(
    entity_type="Opportunity",
    filters={"name": "Tech"},
    select=["id", "name", "amount", "stage", "probability"],
    limit=10
)

结果:

Found 2 Opportunity:
  - ID: opp123, Name: Tech Project Deal
  - ID: opp456, Name: Tech Renewal Opportunity

10.获取任何实体详细信息

用户：“获取机会opp123详细信息，仅显示名称、金额和阶段”

AI助手调用:

get_entity(
    entity_type="Opportunity",
    entity_id="opp123",
    select=["name", "amount", "stage"]
)

结果:

{
  "id": "opp123",
  "name": "Tech Project Deal",
  "amount": 50000,
  "stage": "Negotiation"
}

11.创造机会

用户：“创造销售机会：

• 名称：技术解决方案平台许可证
• 账户：技术解决方案股份有限公司。
• 阶段：资格认证
• 金额：75000美元
• 结束日期：2025-06-30“

AI助手调用:

create_opportunity(
    name="Tech Solutions Platform License",
    account_id="acc456",
    stage="Qualification",
    amount=75000,
    close_date="2025-06-30"
)

结果: Successfully created opportunity: Tech Solutions Platform License (Qualification) (ID: opp789)

12.创建会议

用户：“安排与约翰·史密斯会面：

• 主题：Q1产品演示
• 日期：2025年4月15日10:00
• 结束时间：2025-04-15 11:00
• 地点：A会议室

AI助手调用:

create_meeting(
    name="Q1 Product Demo",
    date_start="2025-04-15T10:00:00Z",
    date_end="2025-04-15T11:00:00Z",
    location="Conference Room A",
    contacts_ids=["123abc"]
)

结果: Successfully created meeting: Q1 Product Demo (Planned) (ID: meeting001)

13.创建任务

用户：“为爱丽丝·约翰逊的线索创建一个后续任务：

• 主题：网站查询跟进
• 到期日期：2025年4月20日
• 优先级：高”

AI助手调用:

create_task(
    name="Follow up on website inquiry",
    status="Not Started",
    priority="High",
    due_date="2025-04-20",
    parent_type="Lead",
    parent_id="lead789"
)

结果: Successfully created task: Follow up on website inquiry (High) (ID: task001)

14.记录通话

用户：“记录与Bob Williams关于续约的呼出电话：

AI助手调用:

create_call(
    name="Renewal Discussion - Bob Williams",
    direction="Outbound",
    status="Held",
    description="Discussed annual contract renewal, interested in upgrading"
)

结果: Successfully logged call: Renewal Discussion - Bob Williams (Outbound) (ID: call001)

15.创建支持案例

用户：“为Tech Solutions Inc创建一个支持案例：

• 名称：与API v2的集成问题
• 类型：问题
• 优先级：高”

AI助手调用:

create_case(
    name="Integration issue with API v2",
    case_type="Problem",
    priority="High",
    account_id="acc456",
    description="Customer reports errors when using API v2 endpoints"
)

结果: Successfully created case: Integration issue with API v2 (High) (ID: case001)

16.添加注释

用户：“添加备注以联系John Smith：在通话中讨论了定价选项，通过电子邮件发送了提案。”

AI助手调用:

add_note(
    parent_type="Contact",
    parent_id="123abc",
    post="Discussed pricing options during call, sent proposal via email."
)

结果: Successfully added note to Contact 123abc (ID: note001)

17.搜索用户

用户：“在系统中查找名为'admin'的活动用户”

AI助手调用:

search_users(search_term="admin", is_active=True)

结果:

Found 2 users:
  - ID: user1, Name: admin (admin@example.com), Role: Administrator
  - ID: user2, Name: Sarah Admin (sarah.admin@company.com), Role: Manager

18.管理团队

用户：“将用户user1添加到团队销售团队”

AI助手调用:

add_user_to_team(user_id="user1", team_id="team_sales")

结果: Successfully added user user1 to team team_sales

API 参考

系统工具

健康检查

health_check() -> str

返回连接状态和EspoCRM版本信息。无需身份验证。

______________________________________________________________________

联系人管理

创建联系人

create_contact(
    first_name: str,
    last_name: str,
    email_address: str | None = None,
    phone_number: str | None = None,
    account_id: str | None = None,
    title: str | None = None,
    department: str | None = None,
    description: str | None = None
) -> str

范围: espocrm:contacts:write

搜索联系人

search_contacts(
    search_term: str | None = None,
    email_address: str | None = None,
    phone_number: str | None = None,
    account_id: str | None = None,
    limit: int = 20,
    offset: int = 0
) -> str

范围: espocrm:contacts:read

获取联系方式

get_contact(contact_id: str) -> str

范围: espocrm:contacts:read + FGA （所有者/指定用户/团队成员）

______________________________________________________________________

账户管理

创建账户

create_account(
    name: str,
    account_type: str | None = None,
    industry: str | None = None,
    website: str | None = None,
    email_address: str | None = None,
    phone_number: str | None = None,
    description: str | None = None
) -> str

范围: espocrm:accounts:write

搜索帐户

search_accounts(
    name: str | None = None,
    account_type: str | None = None,
    industry: str | None = None,
    limit: int = 20,
    offset: int = 0
) -> str

范围: espocrm:accounts:read

______________________________________________________________________

潜在客户管理

创建潜在客户

create_lead(
    first_name: str,
    last_name: str,
    source: str,
    email_address: str | None = None,
    phone_number: str | None = None,
    account_name: str | None = None,
    website: str | None = None,
    industry: str | None = None,
    assigned_user_id: str | None = None,
    status: str = "New",
    description: str | None = None
) -> str

范围: espocrm:leads:write

搜索潜在客户

search_leads(
    name: str | None = None,
    status: str | None = None,
    source: str | None = None,
    email_address: str | None = None,
    account_name: str | None = None,
    limit: int = 20,
    offset: int = 0
) -> str

范围: espocrm:leads:read

更新销售线索

update_lead(lead_id: str, **kwargs) -> str

范围: espocrm:leads:write + FGA （所有者/指定用户）

______________________________________________________________________

转换潜在客户

convert_lead(
    lead_id: str,
    create_account: bool = True,
    create_contact: bool = True,
    create_opportunity: bool = True,
    opportunity_amount: float | None = None,
    opportunity_stage: str = "Qualification"
) -> str

范围: espocrm:leads:write + FGA （所有者）

指定领导

assign_lead(lead_id: str, user_id: str) -> str

范围: espocrm:leads:write

______________________________________________________________________

机会管理

创造机会

create_opportunity(
    name: str,
    account_id: str,
    stage: str,
    amount: float | None = None,
    close_date: str | None = None,
    probability: int | None = None,
    description: str | None = None
) -> str

范围: espocrm:opportunities:write

搜索机会

search_opportunities(
    name: str | None = None,
    stage: str | None = None,
    min_amount: float | None = None,
    max_amount: float | None = None,
    account_id: str | None = None,
    limit: int = 20,
    offset: int = 0
) -> str

范围: espocrm:opportunities:read

______________________________________________________________________

会议管理

创建会议

create_meeting(
    name: str,
    date_start: str,
    date_end: str,
    location: str | None = None,
    description: str | None = None,
    status: str = "Planned",
    parent_type: str | None = None,
    parent_id: str | None = None,
    contacts_ids: list[str] | None = None,
    users_ids: list[str] | None = None
) -> str

范围: espocrm:meetings:write

搜索会议

search_meetings(
    date_from: str | None = None,
    date_to: str | None = None,
    status: str | None = None,
    location: str | None = None,
    limit: int = 20,
    offset: int = 0
) -> str

范围: espocrm:meetings:read

获取会议

get_meeting(meeting_id: str) -> str

范围: espocrm:meetings:read + FGA （所有者/指定用户）

更新会议

update_meeting(meeting_id: str, **kwargs) -> str

范围: espocrm:meetings:write + FGA （所有者/指定用户）

______________________________________________________________________

任务管理

创建任务

create_task(
    name: str,
    status: str = "Not Started",
    priority: str = "Normal",
    due_date: str | None = None,
    parent_type: str | None = None,
    parent_id: str | None = None,
    assigned_user_id: str | None = None,
    description: str | None = None
) -> str

范围: espocrm:tasks:write

搜索任务

search_tasks(
    name: str | None = None,
    status: str | None = None,
    priority: str | None = None,
    assigned_user_id: str | None = None,
    date_from: str | None = None,
    date_to: str | None = None,
    limit: int = 20,
    offset: int = 0
) -> str

范围: espocrm:tasks:read

获取任务

get_task(task_id: str) -> str

范围: espocrm:tasks:read + FGA （所有者/指定用户）

更新任务

update_task(task_id: str, **kwargs) -> str

范围: espocrm:tasks:write + FGA （所有者/指定用户）

分配任务

assign_task(task_id: str, user_id: str) -> str

范围: espocrm:tasks:write + FGA （所有者）

______________________________________________________________________

用户管理

搜索用户

search_users(
    search_term: str | None = None,
    is_active: bool | None = None,
    user_type: str | None = None,
    limit: int = 20,
    offset: int = 0
) -> str

范围: espocrm:users:read

通过电子邮件获取用户

get_user_by_email(email: str) -> str

范围: espocrm:users:read

______________________________________________________________________

团队与角色管理

将用户添加到团队

add_user_to_team(user_id: str, team_id: str, position: str | None = None) -> str

范围: espocrm:teams:write

从团队中删除用户

remove_user_from_team(user_id: str, team_id: str) -> str

范围: espocrm:teams:write

为用户分配角色

assign_role_to_user(user_id: str, role_id: str) -> str

范围: espocrm:teams:write

获取用户团队

get_user_teams(user_id: str) -> str

范围: espocrm:teams:read

获取团队成员

get_team_members(team_id: str) -> str

范围: espocrm:teams:read

搜索团队

search_teams(search_term: str | None = None, limit: int = 20) -> str

范围: espocrm:teams:read

获取用户权限

get_user_permissions(user_id: str) -> str

范围: espocrm:users:read

______________________________________________________________________

通信-呼叫

创建通话

create_call(
    name: str,
    direction: str = "Outbound",
    status: str = "Held",
    duration: int | None = None,
    parent_type: str | None = None,
    parent_id: str | None = None,
    description: str | None = None
) -> str

范围: espocrm:calls:write

搜索电话

search_calls(
    date_from: str | None = None,
    date_to: str | None = None,
    direction: str | None = None,
    status: str | None = None,
    limit: int = 20,
    offset: int = 0
) -> str

范围: espocrm:calls:read

______________________________________________________________________

沟通-案例

创建案例

create_case(
    name: str,
    case_type: str | None = None,
    priority: str = "Normal",
    status: str = "New",
    account_id: str | None = None,
    contact_id: str | None = None,
    description: str | None = None
) -> str

范围: espocrm:cases:write

搜索案例

search_cases(
    name: str | None = None,
    status: str | None = None,
    priority: str | None = None,
    case_type: str | None = None,
    account_id: str | None = None,
    limit: int = 20,
    offset: int = 0
) -> str

范围: espocrm:cases:read

更新案例

update_case(case_id: str, **kwargs) -> str

范围: espocrm:cases:write + FGA （所有者/指定用户）

______________________________________________________________________

通信-注释

添加备注

add_note(
    parent_type: str,
    parent_id: str,
    post: str,
    attachments: list[dict] | None = None
) -> str

范围: espocrm:notes:write

搜索笔记

search_notes(
    parent_type: str | None = None,
    parent_id: str | None = None,
    search_term: str | None = None,
    limit: int = 20,
    offset: int = 0
) -> str

范围: espocrm:notes:read

______________________________________________________________________

通用实体操作

创建实体

create_entity(entity_type: str, data: dict) -> str

范围: espocrm:entities:write

搜索实体

search_entity(
    entity_type: str,
    filters: dict[str, Any] | None = None,
    select: list[str] | None = None,
    limit: int = 20,
    offset: int = 0
) -> str

范围: espocrm:entities:read

获取实体

get_entity(entity_type: str, entity_id: str, select: list[str] | None = None) -> str

范围: espocrm:entities:read + FGA （动态）

更新实体

update_entity(entity_type: str, entity_id: str, data: dict) -> str

范围: espocrm:entities:write + FGA （动态）

删除实体

delete_entity(entity_type: str, entity_id: str) -> str

范围: espocrm:entities:delete + FGA （动态）

______________________________________________________________________

关系管理

链接实体

link_entities(
    entity_type: str,
    entity_id: str,
    link_field: str,
    related_ids: list[str]
) -> str

范围: espocrm:entities:write + FGA （动态）

取消实体链接

unlink_entities(
    entity_type: str,
    entity_id: str,
    link_field: str,
    related_ids: list[str]
) -> str

范围: espocrm:entities:write + FGA （动态）

获取实体关系

get_entity_relationships(
    entity_type: str,
    entity_id: str,
    link_field: str,
    where: dict | None = None,
    select: list[str] | None = None,
    limit: int = 20,
    offset: int = 0
) -> str

范围: espocrm:entities:read

完整工具参考

已实施的工具（46个工具）

1.系统

2.联系人管理（3）

3.账户管理（2）

4.潜在客户管理（5）

5.机会管理（2）

6.会议管理（4）

7.任务管理（5）

8.用户管理（2）

9.团队与角色管理（7）

10.沟通-通话（2）

11.沟通-案例（3）

12.沟通-注释（2）

13.通用实体操作（5）

14.关系管理（3）

FGA柱: ✅ = 已申请细粒度授权检查； 动态的 =运行时确定的实体类型；--=无FGA检查（仅范围授权）。

未来改进

未来的版本可能包括：

• ~~其他实体类型（机会、会议、任务等）~~✅ 实现
• ~~更新和删除操作~~✅ 实现
• ~~关系管理工具~~✅ 实现
• 批量操作（批量创建/更新/删除）
• 具有复杂过滤器和排序的高级搜索
• Webhook支持实时更新
• 缓存以提高性能
• 与EspoCRM数据更改的FGA元组同步
• 用于管理FGA权限的管理UI
• 实体的导出/导入功能
• 工具模式中的自定义字段支持

许可证

此项目根据Apache许可证2.0获得许可-请参阅 许可证 文件以获取详细信息。

贡献

欢迎投稿！请提交拉取请求或开放问题，以获得任何改进或错误修复。