内容
<p align="center">
<img src="https://splice-cad.com/icons/bundle-icon.svg" alt="Splice CAD" width="80" />
</p>
# Splice CAD 服务器
Splice CAD 服务器，用于 [Splice CAD](https://splice-cad.com) 电缆组件和线束设计工具。让 AI 代理搜索零件、构建线束计划、创建具有丰富规格的组件，并生成制造文档。
与 **Claude Code**、**ChatGPT**、**Cursor**、**Windsurf**、**Codex CLI** 和任何 MCP 兼容的客户端配合使用。
> **测试版** — Splice CAD 目前处于测试阶段。[请求访问](https://splice-cad.com) 以开始使用。
## 安装
**从 npm** （即将推出）：
```bash
npx @splice-cad/mcp
```
**从源码**：
```bash
git clone https://github.com/splice-cad/splice-cad-mcp.git
cd splice-cad-mcp
npm install
npm run build
```
然后将您的 MCP 配置指向已构建的文件：
```json
"command": "node",
"args": ["/path/to/splice-cad-mcp/dist/index.js"]
```
**要求：**
- Node.js 18+
- 具有 API 密钥的 Splice CAD 帐户（在帐户 > API 密钥中生成）
## 快速安装
**Claude Code** （一条命令）：
```bash
claude mcp add splice-cad -e SPLICE_API_URL=https://splice-cad.com -e SPLICE_API_KEY=your-key -- npx @splice-cad/mcp
```
有关其他工具，请参见下面的设置部分。
## 设置
### Claude Code
```json
// ~/.claude/mcp.json
{
"mcpServers": {
"splice-cad": {
"command": "npx",
"args": ["@splice-cad/mcp"],
"env": {
"SPLICE_API_URL": "https://splice-cad.com",
"SPLICE_API_KEY": "your-api-key"
}
}
}
}
```
自动批准所有工具：
```bash
claude config add permissions.allow "mcp__splice-cad__*"
```
### Cursor
```json
// .cursor/mcp.json
{
"mcpServers": {
"splice-cad": {
"command": "npx",
"args": ["@splice-cad/mcp"],
"env": {
"SPLICE_API_URL": "https://splice-cad.com",
"SPLICE_API_KEY": "your-api-key"
}
}
}
}
```
### Windsurf
```json
// ~/.windsurf/mcp.json
{
"mcpServers": {
"splice-cad": {
"command": "npx",
"args": ["@splice-cad/mcp"],
"env": {
"SPLICE_API_URL": "https://splice-cad.com",
"SPLICE_API_KEY": "your-api-key"
}
}
}
}
```
### ChatGPT（开发者模式）
在 ChatGPT 设置中，添加一个 MCP 服务器：
- **命令：** `npx @splice-cad/mcp`
- **环境：** `SPLICE_API_URL=https://splice-cad.com`, `SPLICE_API_KEY=your-key`
### OpenAI 响应 API
```python
import openai
response = openai.responses.create(
model="gpt-4.1",
input="Build me a 4-pin Deutsch DT connector harness",
tools=[{
"type": "mcp",
"server_label": "splice-cad",
"server_url": "npx @splice-cad/mcp",
"require_approval": "never",
"headers": {
"SPLICE_API_URL": "https://splice-cad.com",
"SPLICE_API_KEY": "your-api-key"
}
}]
)
```
### Codex CLI
```bash
codex --mcp splice-cad="npx @splice-cad/mcp"
```
## 环境变量
| 变量 | 是否必需 | 描述 |
|----------|----------|-------------|
| `SPLICE_API_URL` | 是 | Splice 后端 URL |
| `SPLICE_API_KEY` | 是 | API 密钥（在 Splice 的帐户 > API 密钥中） |
| `SPLICE_BRIDGE_PORT` | 否 | WebSocket 桥接端口（默认：`9876`） |
| `SPLICE_BRIDGE_SECRET` | 否 | WebSocket 身份验证共享密钥（自动生成） |
## 提示
### 上下文提示
设置代理的操作模式 — 使用哪些工具，避免哪些工具，以及正确的工作流程：
| 提示 | 模式 | 描述 |
|--------|------|-------------|
| `plan-live` | WebSocket | 处理浏览器中打开的计划 — 实时画布更新，支持撤销/重做 |
| `component-creator-live` | WebSocket | 在组件创建器中工作 — 实时更新表单、规格、SVG 和引脚 |
| `api-mode` | REST API | 无需浏览器 — 创建项目、构建计划、搜索零件、管理线束 |
### 任务提示
包括其操作上下文的逐步工作流程：
| 提示 | 模式 | 描述 |
|--------|------|-------------|
| `build-harness` | API | 根据描述或数据表构建完整的电缆线束 |
| `create-component` | API | 根据 MPN 或数据表创建具有规格、图像、引脚标签的零件 |
| `review-live-plan` | 实时 | 连接 WebSocket，读取实时计划状态，建议改进 |
| `cleanup-layout` | 实时 | 读取组件位置并重新组织以获得更好的布局 |
| `import-from-spreadsheet` | API | 根据 CSV/Excel 接线计划构建线束 |
## 工具（27）
### 零件和组件
| 工具 | 描述 |
|------|-------------|
| `search_connectors` | 模糊搜索（“molex 4 pin”，“deutsch dt”） |
| `search_wires` | 模糊搜索（“22 awg red”） |
| `search_cables` | 模糊搜索（“4 core shielded”） |
| `get_part` | 按 ID 获取完整零件详细信息 |
| `create_component` | 创建具有图像、规格、SVG、引脚标签的组件 |
| `create_cable` | 创建多导体电缆 |
| `lookup_part` | DigiKey 查找（图像、数据表、规格） |
| `get_category_templates` | 每个组件类别的默认规格 |
### 项目和计划
| 工具 | 描述 |
|------|-------------|
| `list_projects` | 列出用户的项目 |
| `create_project` | 创建新项目 |
| `get_project` | 获取具有计划和组件的项目 |
| `get_plan` | 获取计划数据（可筛选） |
| `save_plan` | 保存 PlanData JSON（自动纠正颜色） |
| `get_plan_summary` | 组件、引脚、连接、警告 |
| `validate_plan` | 检查结构问题 |
| `generate_assembly` | 从计划选择中生成线束 |
### 传统线束
| 工具 | 描述 |
|------|-------------|
| `list_harnesses` | 列出独立线束 |
| `create_harness` | 从 WorkingHarness JSON 创建 |
| `get_harness` | 加载具有 BOM 的液压线束 |
| `save_harness` | 保存修改后的线束 |
| `get_harness_summary` | 紧凑的摘要 |
### 实时桥接（WebSocket）
| 工具 | 描述 |
|------|-------------|
| `is_bridge_connected` | 检查连接的浏览器标签 |
| `execute_command` | 单个命令（实时画布更新） |
| `execute_commands` | 批处理（原子，单个撤销） |
| `undo` / `redo` | 浏览器中撤销/重做 |
| `get_live_state` | 查询实时状态（计划、组件、SVG） |
## 资源
| URI | 描述 |
|-----|-------------|
| `splice://schema/plan-data` | PlanData JSON 模式 + 行为规则 |
| `splice://schema/harness-data` | WorkingHarness 模式 |
| `splice://examples/plans` | 现实世界线束模式 |
## 示例
参见 **[EXAMPLES.md](EXAMPLES.md)** 以获取详细的操作指南，包括：
- 带有压接端子的终端块
- 从 CSV 接线计划导入
- 实时：从数据表 PDF 生成电缆组件
- 实时：读取 KiCad 原理图并创建 4 页中 21 个连接器
- 实时：审查和修复打开的计划
## 架构
有两个通信路径 — 一个到 Splice 云，一个完全本地：
**单个代理（默认 — 嵌入式桥接）：**
```
┌──────────────┐ stdio ┌──────────────────┐
│ AI 代理 │◄────────────►│ MCP 服务器 │
│ （Claude、 │ │ （splice-cad） │
│ Cursor、 │ │ │
│ ChatGPT） │ │ ┌────────────┐ │
└──────────────┘ │ │ WS 桥接 │ │
│ │ :9876 │ │
│ └─────┬──────┘ │
└────────┼─────────┘
│ WebSocket（本地）
┌────────▼─────────┐
│ Splice 浏览器 │──── HTTPS ───► splice-cad.com
│ 标签 │
└──────────────────┘
```
**多代理（独立 splice-bridge）：**
```
代理 A 代理 B
│ │
MCP 服务器 A MCP 服务器 B （两者都作为 WebSocket 客户端连接）
│ │
└──── splice-bridge ────┘ ← Rust 二进制文件在 :9876
│
┌──────┴──────┐
标签 1（项目：abc） 标签 2（项目：xyz）
```
### REST 工具（save_plan、search_connectors 等）
这些工具对 `splice-cad.com` 的 Splice API 进行 HTTPS 请求。您的 API 密钥验证每个请求。数据通过互联网传输。这些工具无需打开浏览器即可工作。
### 实时桥接工具（execute_command、get_live_state 等）
这些工具 **完全在您的本地机器上通信**：
1. MCP 服务器在 `localhost:9876` 上启动一个 WebSocket 服务器
2. Splice 浏览器标签连接到它（当启用代理桥接时）
3. 代理命令流程：代理 → MCP 进程 → WebSocket → 浏览器标签
4. 浏览器执行命令 — 与在 UI 中单击相同
5. 画布实时更新，操作出现在撤销历史记录中
**实时桥接命令不会让数据离开您的机器。** WebSocket 连接仅限于 `localhost` — 它永远不会触及互联网。 Splice CAD 云不涉及实时命令执行。
### 多代理模式（splice-bridge）
要同时在不同项目上运行多个代理，请使用独立的 [splice-bridge](https://github.com/splice-cad/splice-bridge) 路由器：
```
代理 A（Claude Code） 代理 B（Cursor）
│ │
MCP 服务器 A MCP 服务器 B
│ │
└────────── splice-bridge ─────┘ ← 独立 Rust 二进制文件
│
┌──────────┴──────────┐
│ │
浏览器标签 1 浏览器标签 2
（项目：abc） （项目：xyz）
```
MCP 服务器会自动检测 `splice-bridge` 是否已在桥接端口运行。如果是，它将作为 WebSocket **客户端** 连接，而不是启动自己的嵌入式服务器。不需要配置更改 — 只需在启动代理之前启动 `splice-bridge` 即可。
参见 [splice-bridge README](https://github.com/splice-cad/splice-bridge) 以获取安装和使用信息。
### 什么去哪里
| 操作 | 路径 | 数据是否离开机器？ |
|--------|------|---------------------|
| 搜索零件 | HTTPS → splice-cad.com | 是 |
| 保存/加载计划 | HTTPS → splice-cad.com | 是 |
| 创建组件 | HTTPS → splice-cad.com | 是 |
| `execute_command`（实时） | WebSocket → localhost:9876 | **否** |
| `get_live_state`（实时） | WebSocket → localhost:9876 | **否** |
| `undo` / `redo`（实时） | WebSocket → localhost:9876 | **否** |
## 安全
### API 密钥
您的 Splice API 密钥验证所有 REST API 调用。它是：
- 仅存储在您的 MCP 配置文件中（从不发送到 AI 代理或记录）
- 限定您的用户帐户 — 只能访问您自己的项目和线束
- 可随时在 Splice 帐户 > API 密钥中撤销
- 按您的订阅层级限制速率（每周请求配额）
**请勿将您的 API 密钥提交到 git。** 使用环境变量或本地配置文件。
### WebSocket 桥接
WebSocket 桥接仅在 `localhost` 上运行：
- **无互联网暴露** — WS 服务器绑定到 `127.0.0.1`，而非 `0.0.0.0`
- **共享密钥** — MCP 服务器在启动时生成一个随机密钥，并将其写入 `~/.splice-bridge.json`。浏览器必须发送此密钥才能进行身份验证。这可防止其他本地进程发送命令。
- **每个命名空间一个连接** — 如果两个标签尝试使用相同的命名空间连接，则较旧的连接将被断开
- **端口可配置** — 如果 9876 与另一个服务冲突，请更改 `SPLICE_BRIDGE_PORT`
### AI 代理可以访问的内容
通过 MCP 工具，代理可以：
- **读取** 您的项目、计划、线束和零件（与您在应用程序中看到的内容相同）
- **写入** 计划和线束（创建、修改、保存 — 与您在 UI 中编辑相同）
- **执行命令** 在实时画布上（当桥接连接时）
- **搜索** 共享的零件数据库
代理 **无法**：
- 访问其他用户的私有数据
- 删除您的帐户或更改您的密码
- 访问您的计算机上的文件（超出 AI 客户端本身提供的文件）
- 对除 Splice API 和 localhost WebSocket 之外的任何其他网络请求
### 建议
- 仅在积极使用时启用代理桥接
- 在保存之前查看代理操作 — 所有实时更改都可以使用 Ctrl+Z 撤销
## 开发
### 构建
```bash
npm install
npm run build
```
### 重新生成模式（需要 Splice 前端源代码）
```bash
SPLICE_FRONTEND_PATH=/path/to/splice/frontend npm run build:full
```
## 许可证
MIT
