CWM-API-网关-MCP

Name: CWM-API-网关-MCP
Author: jasondsmith72

作者：jasondsmith727 星标更新：2025-03-25

安装使用来源：spider==github.com

项目介绍

ConnectWise API Gateway MCP 服务器

此 Model Context Protocol (MCP) 服务器提供了一个全面的接口，用于与 ConnectWise Manage API 进行交互。它简化了 API 发现、执行和管理，适用于开发者和 AI 助手。

核心功能

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

克隆或下载仓库：

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+（如果尚未安装）：

# 使用 Homebrew
brew install python@3.10

# 或者使用 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+（如果尚未安装）：

# 对于 Ubuntu 22.04+
sudo apt update
sudo apt install python3.10 python3.10-venv python3.10-dev python3-pip

# 对于较旧版本的 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 定义文件时才运行此步骤：

# 在 Windows 上
python build_database.py path/to/manage.json

# 在 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+  # ConnectWise API 身份验证所需的前缀

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

CONNECTWISE_API_URL: 所有 API 请求的基本 URL

url = f"{API_URL}{endpoint}"  # 例如，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}"  # 例如，"yourprefix+your_public_key"
password = PRIVATE_KEY
credentials = f"{username}:{password}"  # 合并为 "yourprefix+your_public_key:your_private_key"

CONNECTWISE_AUTH_PREFIX: 必须添加到身份验证用户名前的前缀。ConnectWise API 需要此前缀来识别集成类型（例如，"api+"、"integration+" 等）

发送的最终 HTTP 头如下所示：

'Authorization': 'Basic [base64 编码的凭据]'
'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+"
      }
    }
  }
}

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

# 如果通过 NPM 安装
cwm-api-gateway-mcp

# 如果使用 Node.js 脚本（克隆仓库后）
node bin/server.js

# 或者直接使用 Python 脚本
# 在 Windows 上
python api_gateway_server.py

# 在 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("查找所有高优先级的开放服务工单")

执行 GET 请求

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

创建新的服务工单

execute_api_call(
    "/service/tickets", 
    "POST", 
    None,  # 无查询参数 
    {
        "summary": "服务器宕机",
        "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", 
    "获取所有高优先级的开放工单", 
    {"conditions": "status/name='Open' and priority/name='High'"}
)

了解快速内存

快速内存功能允许您保存和检索常用的 API 查询，从而在多个方面优化您的工作流程：

优势

节省时间： 快速执行复杂的 API 调用，无需记住确切的端点或参数
减少错误： 重用成功的 API 调用以最小化潜在错误
自适应学习： 系统会学习哪些 API 调用对您最有价值
参数持久性： 参数和请求体存储以供将来使用

工作原理

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

快速内存功能

自动参数建议： 如果未提供参数，系统将从快速内存中建议参数
使用计数器： 每次使用快速内存中的查询时，其使用次数增加
搜索能力： 通过描述或端点路径搜索已保存的查询
优先级： 按使用频率显示查询，最常使用的查询排在最前面

管理您的快速内存

查看已保存的查询： list_fast_memory()
搜索特定查询： list_fast_memory("搜索词")
删除查询： 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: 查询的使用次数

故障排除

常见问题

数据库未找到错误

错误：数据库文件未找到 [路径]
请先运行 build_database.py 脚本来生成数据库

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

python build_database.py path/to/manage.json

API 身份验证问题

HTTP 错误 401: 未经授权

解决方案： 检查您的环境变量，确保所有 ConnectWise 凭证正确：

验证您的 CONNECTWISE_COMPANY_ID、CONNECTWISE_PUBLIC_KEY 和 CONNECTWISE_PRIVATE_KEY
确保 API 密钥在 ConnectWise 中具有必要的权限
检查 CONNECTWISE_AUTH_PREFIX 是否正确设置

API 调用超时

请求超时。ConnectWise API 可能响应缓慢。

解决方案：

检查您的互联网连接
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
})

许可

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

致谢

使用 Model Context Protocol (MCP) 框架构建
由 ConnectWise Manage API 提供支持