ConnectWise API Gateway MCP Server

ConnectWise API网关MCP服务器

此模型上下文协议（MCP）服务器为与ConnectWise Manage API交互提供了一个全面的接口。它为开发人员和人工智能助手简化了API的发现、执行和管理。

核心能力

• API发现： 使用关键字或自然语言搜索和探索ConnectWise API端点
• 简化的API执行： 使用友好的参数处理和自动错误管理执行API调用
• 快速存储系统： 保存和检索常用的API查询以实现更高效的工作流
• 原始API访问： 发送自定义API请求，并完全控制端点、方法和参数

主要特点

• 数据库包API发现： 使用从ConnectWise API定义JSON构建的SQLite数据库进行快速、高效的端点查找
• 自然语言搜索： 使用所需内容的对话描述查找相关的API端点
• 分类的API导航： 浏览按功能类别组织的API端点
• 详细文档访问： 查看有关API端点的全面信息，包括参数、架构和响应格式
• 适应性学习： 系统通过使用情况跟踪了解哪些API调用对您最有价值

安装和设置

先决条件

• Python 3.10或更高版本
• 访问ConnectWise管理API凭据
• ConnectWise API定义文件(manage.json)-包含在存储库中

安装步骤

选项1：使用GitHub NPM包（推荐）

您可以直接从GitHub安装该软件包：

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

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

选项2：手动安装

视窗

1. 克隆或下载存储库：

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

1. 安装软件包：

   pip install -e .

macOS

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

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

对于手动安装：

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

1. 克隆存储库：

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

1. 设置虚拟环境（推荐）：

   python3 -m venv venv
   source venv/bin/activate

1. 安装软件包：

   pip install -e .

Linux（Ubuntu/Debian）

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

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

对于手动安装：

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

1. 克隆存储库：

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

1. 设置虚拟环境（推荐）：

   python3.10 -m venv venv
   source venv/bin/activate

1. 安装软件包：

   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

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

• 连接\_ 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_公钥 和 CONNECTWISE_私有密钥：与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集成：

方法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网关MCP服务器为使用ConnectWise API提供了多种工具：

API发现工具

API执行工具

快速记忆工具

使用示例

搜索与票证相关的端点

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调用时，系统会提示您将其保存到Fast Memory
2. 智能检索： 下次使用相同的API端点时，系统将首先检查Fast Memory
3. 参数重用： 如果您没有为通话提供参数，系统会自动使用保存在快速内存中的参数
4. 使用情况跟踪： 该系统跟踪每个查询的使用频率，并对频繁使用的查询进行优先级排序

快速记忆功能

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

管理你的快速记忆

• 查看已保存的查询： list_fast_memory()
• 搜索特定查询： list_fast_memory("search term")
• 删除查询： delete_from_fast_memory(query_id)
• 清除所有查询： clear_fast_memory()

快速存储器技术细节

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

解决方案： 跑吧 build_database.py 使用ConnectWise API定义文件的路径编写脚本：

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]"
   })

1. 限制字段选择： 仅请求您需要的字段

   execute_api_call("/service/tickets", "GET", {
       "conditions": "status/name='Open'",
       "fields": "id,summary,status,priority"
   })

1. 分页大结果： 使用页面和页面大小参数

   execute_api_call("/service/tickets", "GET", {
       "conditions": "status/name='Open'",
       "page": 1,
       "pageSize": 50
   })

许可证

该软件是专有和机密的。禁止未经授权的复制、分发或使用。

致谢

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