ConnectWise API Gateway MCP Server

ConnectWise API Gateway MCP Server

一个模型上下文协议服务器，它为与 ConnectWise Manage API 交互提供了一个全面的接口，从而简化了开发者和 AI 助手对 API 的发现、执行和管理。

Category
访问服务器

README

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：手动安装

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+：

    # 使用 Homebrew
brew install python@3.10

# 或使用 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+：

    # 对于 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

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

# 在 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 请求到您的 ConnectWise 实例的基本 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 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+"
      }
    }
  }
}

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

# 如果通过 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 网关 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,  # 无查询参数
    {
        "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()

快速内存技术细节

快速内存系统由 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，请执行以下操作：

  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 提供支持

推荐服务器

Baidu Map

Baidu Map

百度地图核心API现已全面兼容MCP协议，是国内首家兼容MCP协议的地图服务商。

官方
精选
JavaScript
Playwright MCP Server

Playwright MCP Server

一个模型上下文协议服务器，它使大型语言模型能够通过结构化的可访问性快照与网页进行交互，而无需视觉模型或屏幕截图。

官方
精选
TypeScript
Magic Component Platform (MCP)

Magic Component Platform (MCP)

一个由人工智能驱动的工具，可以从自然语言描述生成现代化的用户界面组件，并与流行的集成开发环境（IDE）集成，从而简化用户界面开发流程。

官方
精选
本地
TypeScript
Audiense Insights MCP Server

Audiense Insights MCP Server

通过模型上下文协议启用与 Audiense Insights 账户的交互，从而促进营销洞察和受众数据的提取和分析，包括人口统计信息、行为和影响者互动。

官方
精选
本地
TypeScript
VeyraX

VeyraX

一个单一的 MCP 工具，连接你所有喜爱的工具：Gmail、日历以及其他 40 多个工具。

官方
精选
本地
graphlit-mcp-server

graphlit-mcp-server

模型上下文协议 (MCP) 服务器实现了 MCP 客户端与 Graphlit 服务之间的集成。 除了网络爬取之外，还可以将任何内容（从 Slack 到 Gmail 再到播客订阅源）导入到 Graphlit 项目中，然后从 MCP 客户端检索相关内容。

官方
精选
TypeScript
Kagi MCP Server

Kagi MCP Server

一个 MCP 服务器，集成了 Kagi 搜索功能和 Claude AI，使 Claude 能够在回答需要最新信息的问题时执行实时网络搜索。

官方
精选
Python
e2b-mcp-server

e2b-mcp-server

使用 MCP 通过 e2b 运行代码。

官方
精选
Neon MCP Server

Neon MCP Server

用于与 Neon 管理 API 和数据库交互的 MCP 服务器

官方
精选
Exa MCP Server

Exa MCP Server

模型上下文协议（MCP）服务器允许像 Claude 这样的 AI 助手使用 Exa AI 搜索 API 进行网络搜索。这种设置允许 AI 模型以安全和受控的方式获取实时的网络信息。

官方
精选