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 安装该软件包：

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

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

选项 2：手动安装

视窗

克隆或下载存储库：
git clone https://github.com/jasondsmith72/CWM-API-Gateway-MCP.git cd CWM-API-Gateway-MCP
安装软件包：
pip install -e .

macOS

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

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

对于手动安装：

如果尚未安装，请安装 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
克隆存储库：
git clone https://github.com/jasondsmith72/CWM-API-Gateway-MCP.git cd CWM-API-Gateway-MCP
设置虚拟环境（推荐）：
python3 -m venv venv source venv/bin/activate
安装软件包：
pip install -e .

Linux（Ubuntu/Debian）

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

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

对于手动安装：

如果尚未安装，请安装 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
克隆存储库：
git clone https://github.com/jasondsmith72/CWM-API-Gateway-MCP.git cd CWM-API-Gateway-MCP
设置虚拟环境（推荐）：
python3.10 -m venv venv source venv/bin/activate
安装软件包：
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 桌面配置

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

方法一：使用 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 调用对您最有价值
**参数持久性：**存储参数和请求主体以供将来使用

工作原理

**自动学习：**当您成功执行 API 调用时，系统会提示您将其保存到快速内存
**智能检索：**下次使用相同的 API 端点时，系统会首先检查快速内存
**参数重用：**如果您没有为调用提供参数，系统将自动使用快速内存中保存的参数
**使用情况跟踪：**系统跟踪每个查询的使用频率，并优先考虑经常使用的查询

快速记忆功能

**自动参数建议：**如果没有提供参数，系统将从快速内存中建议参数
**使用计数器：**每次使用快速内存中的查询时，其使用计数都会增加
**搜索功能：**通过描述或端点路径搜索已保存的查询
**优先级：**查询按使用频率的顺序显示，最常用的查询位于顶部

管理你的快速记忆

查看已保存的查询： 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 ：查询已被使用的次数

故障排除

常见问题

数据库未找到错误

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
- 快速内存数据库： api_gateway/fast_memory_api.db

测试数据库

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

python test_database.py

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

高级用法

优化 API 查询

为了获得更好的 ConnectWise API 性能：

使用具体条件：使用精确条件缩小查询范围
execute_api_call("/service/tickets", "GET", { "conditions": "status/name='Open' AND dateEntered > [2023-01-01T00:00:00Z]" })
**限制字段选择：**仅请求您需要的字段
execute_api_call("/service/tickets", "GET", { "conditions": "status/name='Open'", "fields": "id,summary,status,priority" })
**对大结果进行分页：**使用 page 和 pageSize 参数
execute_api_call("/service/tickets", "GET", { "conditions": "status/name='Open'", "page": 1, "pageSize": 50 })

执照

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

致谢

使用模型上下文协议 (MCP) 框架构建
由 ConnectWise Manage API 提供支持

Integrations