使用说明

项目简介

ghl-mcp-template 是一个基于 Model Context Protocol (MCP) 构建的服务器，专注于为 GoHighLevel (GHL) 平台自动化 API 密钥的管理。它允许通过 Webhook 触发，自动登录 GHL 并为子账户生成 API 密钥，并将密钥安全地存储在数据库中。作为一个 MCP 服务器，它可以与任何兼容 MCP 协议的客户端进行交互，为 LLM 应用提供访问 GHL API 密钥的能力。

主要功能点

自动化 GHL 登录: 使用 Puppeteer 自动化模拟浏览器操作，实现 GHL 平台的登录。
子账户 API 密钥生成: 能够为指定的 GHL 子账户（location）自动生成 API 密钥。
数据库存储: 将生成的 API 密钥以及相关的元数据存储在数据库中，方便管理和查询。
Webhook 触发密钥生成: 支持通过 Webhook 请求触发 API 密钥的生成流程。
MCP 兼容服务器: 基于 '@modelcontextprotocol/core' 构建，符合 MCP 协议标准，可以作为 MCP 生态系统的一部分使用。
代理支持: 集成了代理轮换功能，增强了登录 GHL 平台的稳定性和安全性。

安装步骤

克隆仓库:

git clone https://github.com/bpousa/ghl-mcp-template.git
cd ghl-mcp-template

安装依赖:
```
npm install
```

配置环境变量: 复制 '.env.example' 文件并重命名为 '.env'，根据您的实际情况填写以下环境变量：

DB_HOST=your_database_host
DB_USER=your_database_user
DB_PASSWORD=your_database_password
DB_NAME=your_database_name
VPN_PROVIDER_API_KEY=your_proxy_api_key # (可选) 如果需要代理轮换，请配置代理API密钥

注意: 'VPN_PROVIDER_API_KEY' 是可选的，只有当您需要使用代理轮换功能时才需要配置。请确保安全存储您的数据库和代理 API 密钥。

创建数据库: 执行 'src/database/schema.sql' 文件中的 SQL 脚本，在 MySQL 数据库中创建 'ghl_api_keys' 表。
启动服务器:
```
npm start
```
服务器成功启动后，您将在控制台看到 "MCP server started successfully" 的提示信息。

服务器配置

对于 MCP 客户端，您需要配置以下信息以连接到此 MCP 服务器。以下是 JSON 格式的配置信息示例：

{
  "serverName": "ghl-mcp-server",
  "command": "npm",
  "args": ["start"]
}

配置参数说明:

serverName: 服务器名称，定义在 'src/index.js' 中，默认为 "ghl-mcp-server"。
command: 启动服务器的命令，这里使用 'npm'。
args: 启动命令的参数，这里使用 'start'，对应 'npm start' 命令。

注意: MCP 客户端只需要配置上述 'command' 和 'args' 即可启动和连接到 MCP 服务器。无需其他复杂配置，客户端通过标准 MCP 协议与服务器进行通信。

基本使用方法

此 MCP 服务器主要通过 'ghl-api-key' 资源暴露功能。客户端可以通过 MCP 协议调用 'ghl-api-key' 资源的 'generateKeyFromWebhook' 方法来生成 API 密钥。

资源 (Resource): 'ghl-api-key'

方法 (Method): 'generateKeyFromWebhook'

方法参数: 'generateKeyFromWebhook' 方法接受一个 JSON 对象作为参数，该对象应包含以下字段 (这些字段通常来自 Webhook 数据):

'locationId': GHL 子账户 (Location) 的 ID。
'ghlEmail': 用于登录 GHL 的邮箱账号。
'ghlPassword': 用于登录 GHL 的密码。
'agencyId': GHL Agency 的 ID。
'locationName' (可选): GHL 子账户名称，用于数据库记录。
'agencyName' (可选): GHL Agency 名称，用于数据库记录。
'triggeredBy' (可选): 触发密钥生成的来源，例如 "webhook"。

调用示例 (MCP 客户端角度):

假设您使用 MCP 客户端，您需要构造一个符合 MCP 协议的 JSON-RPC 请求，调用 'ghl-api-key' 资源的 'generateKeyFromWebhook' 方法，并传递必要的参数。

{
  "jsonrpc": "2.0",
  "method": "resources.ghl-api-key.methods.generateKeyFromWebhook",
  "params": {
    "locationId": "your_location_id",
    "ghlEmail": "your_ghl_email",
    "ghlPassword": "your_ghl_password",
    "agencyId": "your_agency_id",
    "locationName": "Location Name Example",
    "agencyName": "Agency Name Example",
    "triggeredBy": "manual_test"
  },
  "id": 1
}

服务器将处理此请求，自动登录 GHL，生成 API 密钥，并将其存储到数据库中。最终，服务器会返回一个 JSON-RPC 响应，包含生成的 API 密钥以及其他相关信息。

响应示例 (成功):

{
  "jsonrpc": "2.0",
  "result": {
    "success": true,
    "apiKey": "generated_api_key_value",
    "locationId": "your_location_id",
    "generatedAt": "2024-07-27T10:00:00.000Z"
  },
  "id": 1
}

错误处理:

如果密钥生成过程中发生错误，服务器会返回一个 JSON-RPC 错误响应，其中包含错误代码和错误信息。客户端需要根据错误响应进行相应的错误处理。

安全注意事项

请务必仔细阅读 'README.md' 文件中的 "Security Considerations" 部分，并采取必要的安全措施来保护您的 GHL 账号凭据、数据库连接信息以及代理 API 密钥。

关键词