使用说明

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

视窗

克隆或下载存储库：

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

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

连接_ 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发现工具

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

快速记忆功能

自动参数建议： 如果没有提供，系统将建议快速存储器中的参数
使用计数器： 每次使用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获得更好的性能：

使用特定条件： 用精确的条件缩小您的查询范围

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

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

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

许可证

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

致谢

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