ConnectWise API Gateway MCP Server

ConnectWise API Gateway MCP 服务

此模型上下文协议（MCP）服务提供了与 ConnectWise Manage API 交互的完整接口，简化了开发者和 AI 助手的 API 发现、执行和管理。

核心能力

• API 发现： 使用关键词或自然语言搜索和探索 ConnectWise API 端点
• 简化 API 执行： 通过友好的参数处理和自动错误管理执行 API 调用
• 快速记忆系统： 保存和检索常用 API 查询，让工作流更高效
• 原始 API 访问： 发送自定义 API 请求，全面控制端点、方法和参数

主要功能

• 数据库支持的 API 发现： 使用根据 ConnectWise API 定义 JSON 构建的 SQLite 数据库，快速高效地查找端点
• 自然语言搜索： 通过对需求的对话式描述查找相关 API 端点
• 分类 API 导航： 按功能类别浏览 API 端点
• 详细文档访问： 查看 API 端点的全面信息，包括参数、架构和响应格式
• 自适应学习： 系统通过使用情况跟踪，了解哪些 API 调用对你最有价值

安装与设置

前提条件

• Python 3.10 或更高版本
• 可访问 ConnectWise Manage API 凭据
• ConnectWise API 定义文件（manage.json）——已包含在仓库中

安装步骤

选项 1：使用 GitHub NPM 包（推荐）

你可以直接从 GitHub 安装此包：

npm install -g jasondsmith72/CWM-API-Gateway-MCP

此方法会自动处理所有依赖项，并为 Claude Desktop 提供更简单的配置。

选项 2：手动安装

Windows

1. 克隆或下载仓库：

   git clone https://github.com/jasondsmith72/CWM-API-Gateway-MCP.git
   cd CWM-API-Gateway-MCP
   

2. 安装此包：

   pip install -e .
   

macOS

使用 NPM 安装方式时，只需运行：

npm install -g jasondsmith72/CWM-API-Gateway-MCP

手动安装：

1. 如果尚未安装，请安装 Python 3.10+：

   # Using Homebrew
   brew install [email protected]
   
   # Or using pyenv
   brew install pyenv
   pyenv install 3.10.0
   pyenv global 3.10.0
   

2. 克隆仓库：

   git clone https://github.com/jasondsmith72/CWM-API-Gateway-MCP.git
   cd CWM-API-Gateway-MCP
   

3. 创建虚拟环境（推荐）：

   python3 -m venv venv
   source venv/bin/activate
   

4. 安装此包：

   pip install -e .
   

Linux（Ubuntu/Debian）

使用 NPM 安装方式时，只需运行：

sudo npm install -g jasondsmith72/CWM-API-Gateway-MCP

手动安装：

1. 如果尚未安装，请安装 Python 3.10+：

   # For Ubuntu 22.04+
   sudo apt update
   sudo apt install python3.10 python3.10-venv python3.10-dev python3-pip
   
   # For older versions of Ubuntu/Debian
   sudo add-apt-repository ppa:deadsnakes/ppa
   sudo apt update
   sudo apt install python3.10 python3.10-venv python3.10-dev python3-pip
   

2. 克隆仓库：

   git clone https://github.com/jasondsmith72/CWM-API-Gateway-MCP.git
   cd CWM-API-Gateway-MCP
   

3. 创建虚拟环境（推荐）：

   python3.10 -m venv venv
   source venv/bin/activate
   

4. 安装此包：

   pip install -e .
   

安装后步骤

在任何平台（Windows、macOS 或 Linux）上安装后，请完成以下步骤：

1.（可选）构建 API 数据库

此仓库已包含预先构建的数据库，因此此步骤为可选。只有在需要使用更新版本的 ConnectWise API 定义文件时，才运行此步骤：

# On Windows
python build_database.py path/to/manage.json

# On macOS/Linux
python3 build_database.py path/to/manage.json

此步骤只需执行一次，或在 ConnectWise API 定义发生变化时执行。

2. 配置 API 凭据

使用 ConnectWise 凭据设置以下环境变量：

CONNECTWISE_API_URL=https://na.myconnectwise.net/v4_6_release/apis/3.0
CONNECTWISE_COMPANY_ID=your_company_id
CONNECTWISE_PUBLIC_KEY=your_public_key
CONNECTWISE_PRIVATE_KEY=your_private_key
CONNECTWISE_AUTH_PREFIX=yourprefix+  # Prefix required by ConnectWise for API authentication

这些凭据在身份验证过程中的使用方式如下：

• CONNECTWISE_API_URL：向你的 ConnectWise 实例发送所有 API 请求时使用的基础 URL

  url = f"{API_URL}{endpoint}"  # e.g., https://na.myconnectwise.net/v4_6_release/apis/3.0/service/tickets
  

• CONNECTWISE_COMPANY_ID：包含在每个请求的“clientId”标头中，用于识别你的公司

  headers = {'clientId': COMPANY_ID, ...}
  

• CONNECTWISE_PUBLIC_KEY 和 CONNECTWISE_PRIVATE_KEY：与 AUTH_PREFIX 一起使用，以创建基本身份验证凭据

  username = f"{AUTH_PREFIX}{PUBLIC_KEY}"  # e.g., "yourprefix+your_public_key"
  password = PRIVATE_KEY
  credentials = f"{username}:{password}"  # Combined into "yourprefix+your_public_key:your_private_key"
  

• CONNECTWISE_AUTH_PREFIX：添加在身份验证用户名中的公钥前缀。ConnectWise API 要求使用此前缀来识别集成类型（例如，“api+”、“integration+”等）

每个请求发送的最终 HTTP 标头如下所示：

'Authorization': 'Basic [base64 encoded credentials]'
'clientId': 'your_company_id'
'Content-Type': 'application/json'

Claude Desktop 配置

有两种方法可以与 Claude Desktop 集成：

方法 1：使用 NPM 包（推荐）

使用 NPM 安装该包：

npm install -g jasondsmith72/CWM-API-Gateway-MCP

然后配置 Claude Desktop（claude_desktop_config.json）：

{
  "mcpServers": {
    "CWM-API-Gateway-MCP": {
      "command": "npx",
      "args": [
        "-y",
        "@jasondsmith72/CWM-API-Gateway-MCP"
      ],
      "env": {
        "CONNECTWISE_API_URL": "https://na.myconnectwise.net/v4_6_release/apis/3.0",
        "CONNECTWISE_COMPANY_ID": "your_company_id",
        "CONNECTWISE_PUBLIC_KEY": "your_public_key",
        "CONNECTWISE_PRIVATE_KEY": "your_private_key",
        "CONNECTWISE_AUTH_PREFIX": "yourprefix+"
      }
    }
  }
}

方法 2：使用 Node.js 脚本（替代方法）

如果你已克隆代码仓库并安装依赖项，可以使用随附的 Node.js 脚本：

{
  "mcpServers": {
    "CWM-API-Gateway-MCP": {
      "command": "node",
      "args": ["C:/path/to/CWM-API-Gateway-MCP/bin/server.js"],
      "env": {
        "CONNECTWISE_API_URL": "https://na.myconnectwise.net/v4_6_release/apis/3.0",
        "CONNECTWISE_COMPANY_ID": "your_company_id",
        "CONNECTWISE_PUBLIC_KEY": "your_public_key",
        "CONNECTWISE_PRIVATE_KEY": "your_private_key",
        "CONNECTWISE_AUTH_PREFIX": "yourprefix+"
      }
    }
  }
}

方法 3：使用 Python 脚本的直接路径

如果你更愿意直接使用 Python 脚本：

{
  "mcpServers": {
    "CWM-API-Gateway-MCP": {
      "command": "python",
      "args": ["C:/path/to/CWM-API-Gateway-MCP/api_gateway_server.py"],
      "env": {
        "CONNECTWISE_API_URL": "https://na.myconnectwise.net/v4_6_release/apis/3.0",
        "CONNECTWISE_COMPANY_ID": "your_company_id",
        "CONNECTWISE_PUBLIC_KEY": "your_public_key",
        "CONNECTWISE_PRIVATE_KEY": "your_private_key",
        "CONNECTWISE_AUTH_PREFIX": "yourprefix+"
      }
    }
  }
}

在 macOS 和 Linux 上，请使用相应的路径格式：

{
  "mcpServers": {
    "CWM-API-Gateway-MCP": {
      "command": "python3",
      "args": ["/path/to/CWM-API-Gateway-MCP/api_gateway_server.py"],
      "env": {
        "CONNECTWISE_API_URL": "https://na.myconnectwise.net/v4_6_release/apis/3.0",
        "CONNECTWISE_COMPANY_ID": "your_company_id",
        "CONNECTWISE_PUBLIC_KEY": "your_public_key",
        "CONNECTWISE_PRIVATE_KEY": "your_private_key",
        "CONNECTWISE_AUTH_PREFIX": "yourprefix+"
      }
    }
  }
}

可以直接从命令行运行服务进行测试：

# If installed via NPM
cwm-api-gateway-mcp

# If using the Node.js script (after cloning the repository)
node bin/server.js

# Or using the Python script directly
# On Windows
python api_gateway_server.py

# On macOS/Linux
python3 api_gateway_server.py

可用工具

API Gateway MCP 服务提供了多个用于操作 ConnectWise API 的工具：

API 发现工具

工具	描述
search_api_endpoints	按查询字符串搜索 API 端点
natural_language_api_search	使用自然语言描述查找端点
list_api_categories	列出所有可用的 API 类别
get_category_endpoints	列出特定类别中的所有端点
get_api_endpoint_details	获取特定端点的详细信息

API 执行工具

工具	描述
execute_api_call	使用路径、方法、参数和数据执行 API 调用
send_raw_api_request	按照 "METHOD /path [JSON body]" 格式发送原始 API 请求

快速记忆工具

工具	描述
save_to_fast_memory	手动将 API 查询保存到快速记忆
list_fast_memory	列出快速记忆中保存的所有查询
delete_from_fast_memory	删除快速记忆中的特定查询
clear_fast_memory	清除快速记忆中的所有查询

使用示例

搜索与工单相关的端点

search_api_endpoints("tickets")

使用自然语言搜索

natural_language_api_search("find all open service tickets that are high priority")

执行 GET 请求

execute_api_call(
    "/service/tickets", 
    "GET", 
    {"conditions": "status/name='Open' and priority/name='High'"}
)

创建新的服务工单

execute_api_call(
    "/service/tickets", 
    "POST", 
    None,  # No query parameters 
    {
        "summary": "Server is down",
        "board": {"id": 1},
        "company": {"id": 2},
        "status": {"id": 1},
        "priority": {"id": 3}
    }
)

发送原始 API 请求

send_raw_api_request("GET /service/tickets?conditions=status/name='Open'")

查看快速记忆内容

list_fast_memory()

将有用的查询保存到快速记忆

save_to_fast_memory(
    "/service/tickets", 
    "GET", 
    "Get all high priority open tickets", 
    {"conditions": "status/name='Open' and priority/name='High'"}
)

了解快速记忆

快速记忆功能可让你保存和检索常用的 API 查询，从而通过多种方式优化工作流：

优势

• 节省时间： 无需记住确切的端点或参数，即可快速执行复杂的 API 调用
• 减少错误： 重用成功的 API 调用，尽可能减少潜在错误
• 自适应学习： 系统会了解哪些 API 调用对你最有价值
• 参数持久化： 参数和请求正文会被保存，以供日后使用

工作原理

1. 自动学习： 执行成功的 API 调用后，系统会提示你将其保存到快速记忆
2. 智能检索： 下次使用相同的 API 端点时，系统会先检查快速记忆
3. 重用参数： 如果调用时未提供参数，系统会自动使用快速记忆中保存的参数
4. 使用情况跟踪： 系统会跟踪每个查询的使用频率，并优先显示常用查询

快速记忆功能

• 自动建议参数： 如果未提供参数，系统会从快速记忆中建议参数
• 使用次数计数： 每次使用快速记忆中的查询时，其使用次数都会增加
• 搜索功能： 可以按描述或端点路径搜索已保存的查询
• 优先排序： 查询会按使用频率排序显示，最常用的查询位于顶部

管理快速记忆

• 查看已保存的查询： list_fast_memory()
• 搜索特定查询： list_fast_memory("search term")
• 删除查询： delete_from_fast_memory(query_id)
• 清除所有查询： clear_fast_memory()

Fast Memory 技术详情

Fast Memory 系统由 SQLite 数据库（fast_memory_api.db）提供支持，用于存储：

• 查询路径和方法
• 以 JSON 格式保存的参数和请求正文
• 使用指标和时间戳
• 便于用户理解的描述

数据库结构包括：

• id：每个已保存查询的唯一标识符
• description：用户提供的查询功能描述
• path：API 端点路径
• method：HTTP 方法（GET、POST、PUT 等）
• params：JSON 格式的查询参数
• data：JSON 格式的请求正文
• timestamp：上次使用查询的时间
• usage_count：查询的使用次数

故障排除

常见问题

找不到数据库错误

Error: Database file not found at [path]
Please run build_database.py script first to generate the database

解决方案： 使用 ConnectWise API 定义文件的路径运行 build_database.py 脚本：

python build_database.py path/to/manage.json

API 身份验证问题

HTTP error 401: Unauthorized

解决方案： 检查环境变量，确保所有 ConnectWise 凭据均正确：

• 确认 CONNECTWISE_COMPANY_ID、CONNECTWISE_PUBLIC_KEY 和 CONNECTWISE_PRIVATE_KEY 正确无误
• 确保 API 密钥在 ConnectWise 中拥有必要的权限
• 检查 CONNECTWISE_AUTH_PREFIX 是否已针对你的环境正确设置

API 调用超时

Request timed out. ConnectWise API may be slow to respond.

解决方案：

• 检查你的互联网连接
• ConnectWise API 可能正处于高负载状态
• 对于大型数据请求，可考虑在查询中添加更具体的筛选条件

日志和诊断

日志位置

• 主日志文件：api_gateway/api_gateway.log
• SQLite 数据库：
  • API 数据库：api_gateway/connectwise_api.db
  • Fast Memory 数据库：api_gateway/fast_memory_api.db

测试数据库

验证数据库是否已正确构建且可以访问：

python test_database.py

这将显示数据库统计信息，并确认数据库可以正常查询。

高级用法

优化 API 查询

使用 ConnectWise API 时，如需提升性能：

1. 使用具体条件： 使用精确的条件缩小查询范围

   execute_api_call("/service/tickets", "GET", {
       "conditions": "status/name='Open' AND dateEntered > [2023-01-01T00:00:00Z]"
   })
   

2. 限制字段选择： 仅请求所需字段

   execute_api_call("/service/tickets", "GET", {
       "conditions": "status/name='Open'",
       "fields": "id,summary,status,priority"
   })
   

3. 对大型结果分页： 使用 page 和 pageSize 参数

   execute_api_call("/service/tickets", "GET", {
       "conditions": "status/name='Open'",
       "page": 1,
       "pageSize": 50
   })
   

许可证

本软件属于专有和机密软件。禁止未经授权的复制、分发或使用。

致谢

• 使用 Model Context Protocol（MCP）框架构建
• 由 ConnectWise Manage API 提供支持