ConnectWise API 网关 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 安装该软件包：

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

选项 2：手动安装

视窗

1. 克隆或下载存储库：

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

2. 安装软件包：

   pip install -e .

macOS

对于 NPM 安装方法，只需运行：

对于手动安装：

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

   # Using Homebrew brew install python@3.10 # 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 安装方法，只需运行：

对于手动安装：

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 定义文件时才运行此步骤：

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

2.配置API凭证

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

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

• 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 标头如下所示：

Claude 桌面配置

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

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

使用 NPM 安装包：

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

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

如果您已经克隆了存储库并安装了依赖项，则可以使用包含的 Node.js 脚本：

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

如果您更喜欢直接使用 Python 脚本：

对于 macOS 和 Linux，请使用适当的路径格式：

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

可用工具

API Gateway MCP 服务器提供了多种用于与 ConnectWise API 配合使用的工具：

API 发现工具

API执行工具

快速记忆工具

使用示例

搜索与工单相关的端点

使用自然语言搜索

执行 GET 请求

创建新服务单

发送原始 API 请求

查看快速内存内容

将有用的查询保存到快速内存

理解快速记忆

快速记忆功能允许您保存和检索常用的 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()

快速内存技术细节

快速记忆系统由 SQLite 数据库 ( fast_memory_api.db ) 提供支持，该数据库存储：

• 查询路径和方法

• JSON 格式的参数和请求主体

• 使用情况指标和时间戳

• 用户友好的描述

数据库结构包括：

• id ：每个已保存查询的唯一标识符

• description ：用户提供的查询描述

• path ：API 端点路径

• method ：HTTP 方法（GET、POST、PUT 等）

• params ：JSON格式的查询参数

• data ：JSON 格式的请求主体

• timestamp ：上次使用查询的时间

• usage_count ：查询已被使用的次数

故障排除

常见问题

数据库未找到错误

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

API 身份验证问题

**解决方案：**检查您的环境变量以确保所有 ConnectWise 凭据正确无误：

• 验证您的CONNECTWISE_COMPANY_ID 、 CONNECTWISE_PUBLIC_KEY和CONNECTWISE_PRIVATE_KEY

• 确保 API 密钥在 ConnectWise 中具有必要的权限

• 检查CONNECTWISE_AUTH_PREFIX是否根据您的环境正确设置

API 调用超时

解决方案：

• 检查您的互联网连接

• ConnectWise API 可能正在承受高负载

• 对于大数据请求，请考虑在查询中添加更具体的过滤器

日志和诊断

日志位置

• 主日志文件： api_gateway/api_gateway.log

• SQLite 数据库：

  • API 数据库： api_gateway/connectwise_api.db

  • 快速内存数据库： api_gateway/fast_memory_api.db

测试数据库

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

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

高级用法

优化 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 })

执照

本软件为专有且保密的软件。未经授权，禁止复制、分发或使用。

致谢

• 使用模型上下文协议 (MCP) 框架构建

• 由 ConnectWise Manage API 提供支持