内容
# 连接智慧MCP
本地stdio MCP服务器，向Claude暴露**23个只读的连接智慧管理工具**。它封装了[`xssentials`](https://github.com/XssentialsAI/xssentials) 连接智慧客户端，并通过stdio进行MCP通信。凭证存储在1Password中，并在启动时通过`op run`解析 —— 明文密钥从不接触磁盘。根据设计，默认为只读（参见[只读不变性](#只读不变性)）。
这些说明针对**macOS上的Claude Desktop**（在**Cowork**选项卡中使用）。
> **急需？** 以下[ELI5快速入门](#-安装它像我-5岁) 大多数人只需要这些步骤。编号参考部分在后面。
---
## 🧸 安装它像我5岁
按顺序执行以下七个步骤。将灰色框中的内容复制并粘贴到**终端**应用程序中（按`⌘ + Space`，输入"终端"，然后按Enter）。
### 步骤 1 — 安装两个辅助应用程序
该服务器需要 **1Password** （安全存储秘密密钥）和 **Homebrew** （一个工具安装程序）。如果您还没有Homebrew，请粘贴以下内容并按照提示进行操作：
```bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```
然后安装1Password及其命令行助手：
```bash
brew install --cask 1password
brew install 1password-cli
```
打开 **1Password 应用程序 → 设置 → 开发者** 并启用 **"与 1Password CLI 集成。"** （这样服务器就可以使用您的指纹解锁秘密，而无需您登录。）
### 步骤 2 — 下载代码
```bash
mkdir -p ~/mcp && cd ~/mcp
git clone https://github.com/XssentialsAI/xssentials.git
git clone https://github.com/XssentialsAI/connectwise-mcp.git
```
### 步骤 3 — 设置（复制整个块）
```bash
cd ~/mcp/connectwise-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -e ../xssentials
pip install -e .
```
### 步骤 4 — 创建您的秘密密钥文件
您需要一个ConnectWise **API 成员**，并具有公钥/私钥对（参见[凭证](#4-凭证-您的连接智慧-api-密钥) 以获取相关信息）。将这些信息放入1Password项目中，然后：
```bash
cp cw.env.example cw.env
open -e cw.env
```
在打开的文件中，将每个`op://...`行指向您的1Password项目，保存并关闭。不要粘贴原始密钥 — 使用`op://`引用。（`cw.env`被git忽略，因此它永远不会被上传。）
### 步骤 5 — 获取Claude需要的两个路径
运行此命令并**保留它打印的两个行** — 您将在步骤 6 中粘贴它们：
```bash
echo "op path: $(which op)"
echo "python path: $PWD/.venv/bin/python"
```
### 步骤 6 — 告诉Claude Desktop关于服务器的信息
在Claude Desktop中：**设置 → 开发者 → 编辑配置**。这将打开一个名为`claude_desktop_config.json`的文件。使其如下所示，替换为您在步骤 5 中的两个路径和您的实际主文件夹：
```json
{
"mcpServers": {
"connectwise": {
"command": "/opt/homebrew/bin/op",
"args": [
"run",
"--env-file=/Users/YOU/mcp/connectwise-mcp/cw.env",
"--",
"/Users/YOU/mcp/connectwise-mcp/.venv/bin/python",
"-m",
"connectwise_mcp"
]
}
}
}
```
保存文件，确保 **1Password 应用已解锁**，然后 **完全退出并重新打开Claude Desktop**（⌘Q，然后再次打开）。
> ⚠️ **不要** 使用Cowork中的 **"+ 添加自定义连接器"** 按钮。这按钮用于互联网上的网络服务器。此服务器在 **您的Mac** 上运行，因此请在 **编辑配置**（上面）中进行操作。
### 步骤 7 — 在Cowork中启用并测试
1. 在Claude Desktop中打开 **Cowork** 选项卡。
2. 进入 **自定义 → 连接器**。您将看到 **connectwise** 在列表中 — 切换其开关为 **开启**。
3. （可选）点击 **工具权限** 以选择允许/询问/阻止每个工具。ConnectWise是只读的，因此 **允许** 对所有工具都是安全的。
4. 在Cowork聊天中输入： **"运行cw_ping"**。您应该在几秒钟内收到一个包含ConnectWise版本和区域的卡片。 🎉
如果出现问题，请参见 [故障排除](#故障排除)。
---
## 参考
### 1. 先决条件
- **macOS** 且具有 **Python 3.10+** (`python3 --version`)
- **1Password 应用程序**（桌面版）+ **1Password CLI** (`op`)，并启用*开发者 → 与 1Password CLI 集成*
- **Claude Desktop** — https://claude.ai/download
### 2. 获取代码
将所有三个仓库克隆为兄弟节点（服务器依赖于 `xssentials`）：
```bash
mkdir -p ~/mcp && cd ~/mcp
git clone https://github.com/XssentialsAI/xssentials.git
git clone https://github.com/XssentialsAI/connectwise-mcp.git
```
### 3. 安装
```bash
cd ~/mcp/connectwise-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -e ../xssentials # 满足 xssentials 依赖项，无需网络获取
pip install -e .
```
### 4. 凭证（您自己的ConnectWise API密钥）
1. 在ConnectWise Manage中： **系统 → 成员 → API 成员** → 创建一个API成员。
2. 在该成员上，生成一个 **公钥/私钥对** （私钥仅显示一次 — 保存它）。
3. 您的 **clientId** 是来自 https://developer.connectwise.com 的开发人员注册UUID。
将这些信息存储在1Password中，然后 `cp cw.env.example cw.env` 并将每个 `op://vault/item/field` 引用指向您的项目。五个必填字段和身份验证注释在 `cw.env.example` 中有文档记录。验证引用是否解析：
```bash
op run --env-file=cw.env -- printenv CW_COMPANY_ID # 应该打印您的公司ID
```
### 5. 安装到Claude Desktop（编辑配置）
**设置 → 开发者 → 编辑配置** 打开 `~/Library/Application Support/Claude/claude_desktop_config.json`。添加 [步骤 6](#步骤-6-告诉-claude-desktop-关于服务器的信息) 中显示的 `connectwise` 条目。
**使用绝对路径** — Claude Desktop 使用最小的 `PATH` 启动服务器，不包括Homebrew，因此裸露的 `"op"` 或 `"python"` 将失败。 使用 `which op` 查找您的 `op`（Apple Silicon → `/opt/homebrew/bin/op`，Intel → `/usr/local/bin/op`）。解锁1Password，然后退出并重新打开Claude Desktop。
### 6. 在Cowork中启用（自定义选项卡）
本地服务器通过 **编辑配置** 安装，但在 **Cowork → 自定义 → 连接器** 中启用，与网络和自定义连接器并列。启用 **connectwise**。使用 **工具权限** （允许/询问/阻止）控制各个工具 — 这里都是只读的，因此允许是安全的。
### 7. 验证
在Cowork聊天中： **"运行cw_ping"** → 包含CW版本、区域（例如 `NA`）和 `isCloud: True` 的markdown卡片，时间应在 ~2秒内。
## 故障排除
- **服务器无法启动 / "命令未找到"** — 您使用了裸露的 `op` 或 `python`。两者在配置中都必须是 **绝对路径** （Claude Desktop不继承您的shell `PATH`）。
- **秘密无法解析 / `op` 提示** — 打开并解锁1Password桌面应用程序，并确认已启用 *开发者 → 与1Password CLI集成*。
- **服务器未在自定义列表中** — 确认JSON有效，并且您完全退出（⌘Q）并重新打开了Claude Desktop。检查 **设置 → 开发者** 以获取服务器的状态/日志。
- **`pip install -e .` 找不到 `xssentials`** — 先运行 `pip install -e ../xssentials`。
- **来自ConnectWise的401错误** — 重新检查1Password中的五个字段；基本头部是 `<company_id>+<public_key>:<private_key>`，并且需要所有五个字段。
## 工具索引
`connectwise_mcp/__main__.py` 中注册了23种工具：
| 工具 | CW 资源 | 用途 |
|---|---|---|
| `cw_ping` | `/system/info` | 身份验证测试 |
| `cw_find` | 并行跨资源 | 跨公司、项目、工单、机会、发票、采购订单的模糊查找 |
| `cw_company` | `/company/companies` | 按ID或名称查找单个公司 |
| `cw_project_list` | `/project/projects` | 项目搜索与筛选 |
| `cw_project_status` | `/project/projects/{id}` + AR + 开放工单 | 单个项目汇总 |
| `cw_invoice_lookup` | `/finance/invoices/{id}` + 产品线 | 单个发票整合 |
| `cw_invoice_list` | `/finance/invoices` | 发票搜索与筛选 |
| `cw_ar_aging` | `/finance/invoices` | 每个公司/项目的AR账龄桶 |
| `cw_service_tickets` | `/service/tickets` | 跨板块的服务工单搜索 |
| `cw_ticket_detail` | `/service/tickets/{id}` + 注释 + 时间 | 单个工单整合 |
| `cw_time_entries` | `/time/entries` | 时间条目搜索与筛选 |
| `cw_opportunity_status` | `/sales/opportunities/{id}` | 单个机会汇总 |
| `cw_purchasing_status` | `/procurement/purchaseorders` | 采购订单头 + 行项目，或按供应商的采购订单列表 |
| `cw_pick_ship_status` | `/procurement/products` | 采购准备就绪标志 |
| `cw_sales_orders` | `/sales/salesOrders` | 销售订单搜索 |
| `cw_purchase_approvals` | n/a | 结构化差距消息（无审批端点） |
| `cw_inventory` | `/procurement/warehouseBins` | 按仓库仓位查询库存数量 |
| `cw_product_catalog` | `/procurement/catalog` | 按查询/制造商搜索目录 |
| `cw_configurations` | `/company/configurations` | 配置项 |
| `cw_expense_reports` | `/expense/entries` | 费用条目搜索 |
| `cw_query` | 任意GET | 通用逃生口；通过 `fields="parent/child"` 进行嵌套标量投影 |
| `cw_report` | `/system/reports/{name}` | 以扁平Markdown表格运行CW系统报告 |
| `cw_schedule_entries` | `/schedule/entries` | 时间表条目搜索（分配技术人员预订） |
## 只读不变性
只读性在两个层次上强制执行：
1. **客户端级别** — `xssentials.connectwise.client._request` 对任何非GET HTTP方法引发 `NotImplementedError`。
2. **验证器级别** — `connectwise_mcp._validators.enforce_get_only` 保护 `cw_query` 路径。
在任何提交上验证：
```bash
grep -nE '_request\("(POST|PUT|PATCH|DELETE)"' connectwise_mcp/__main__.py # 预期为零命中
```
## 许可证
内部Xssentials工具。ConnectWise是ConnectWise, LLC的商标。
