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

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

# 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: 所有 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+"
      }
    }
  }
}

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

# 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("搜索词")
• 删除查询： 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 驱动