Metadata-Version: 2.4
Name: timeverse-3dprinter-mcp
Version: 1.0.0
Summary: TimeVerse 3D Printer Control MCP Server — 支持多种通讯方式的 3D 打印机控制
Author: TimeVerse Studio
License: MIT
Project-URL: Homepage, https://github.com/elimyliu/timeverse-3dprinter-mcp
Project-URL: Repository, https://github.com/elimyliu/timeverse-3dprinter-mcp
Project-URL: Documentation, https://github.com/elimyliu/timeverse-3dprinter-mcp
Project-URL: Issues, https://github.com/elimyliu/timeverse-3dprinter-mcp/issues
Keywords: 3d-printer,mcp,octoprint,klipper,bambu-lab,gcode,3d-printing
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Manufacturing
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: System :: Hardware
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: mcp>=1.0.0
Requires-Dist: pyserial>=3.5
Requires-Dist: httpx>=0.27.0
Requires-Dist: websockets>=12.0
Requires-Dist: paho-mqtt>=2.0.0
Requires-Dist: zeroconf>=0.131.0
Requires-Dist: trimesh>=4.0.0

# TimeVerse 3D Printer MCP Server

![Python Version](https://img.shields.io/badge/python-3.12%2B-blue)
![MCP](https://img.shields.io/badge/MCP-1.0%2B-green)

**3D 打印机控制 MCP 服务器** — 支持 7 种通讯协议，提供实时状态监控、G-Code 处理、切片集成、网络发现等功能。通过 32 个 MCP 工具覆盖 3D 打印全生命周期管理。

---

## 目录

- [功能特性](#功能特性)
- [快速开始](#快速开始)
- [安装方式](#安装方式)
  - [方式一：通过 uvx 安装（推荐）](#方式一通过-uvx-安装推荐)
  - [方式二：通过 pip 安装](#方式二通过-pip-安装)
  - [方式三：直接 Python 运行](#方式三直接-python-运行)
- [凭证配置指南](#凭证配置指南)
  - [方法 A：配置文件（推荐）](#方法-a配置文件推荐)
  - [方法 B：环境变量](#方法-b环境变量)
  - [方法 C：工具调用时传入](#方法-c工具调用时传入)
- [MCP 客户端配置](#mcp-客户端配置)
  - [uvx 模式](#uvx-模式)
  - [pip 模式](#pip-模式)
  - [Python 直接运行模式](#python-直接运行模式)
- [工具列表](#工具列表)
  - [发现工具 (3 个)](#发现工具-3-个)
  - [打印工具 (7 个)](#打印工具-7-个)
  - [状态查询 (4 个)](#状态查询-4-个)
  - [文件管理 (4 个)](#文件管理-4-个)
  - [G-Code 指令 (7 个)](#g-code-指令-7-个)
  - [切片工具 (3 个)](#切片工具-3-个)
  - [管理工具 (4 个)](#管理工具-4-个)
- [传输协议说明](#传输协议说明)
- [项目结构](#项目结构)
- [环境变量参考](#环境变量参考)

---

## 功能特性

- **7 种传输协议**：USB 串口、OctoPrint REST API、Moonraker (Klipper)、Duet Web Control、Repetier Server、Bambu Lab MQTT、Raw TCP
- **32 个 MCP 工具**：覆盖发现、状态、打印、文件管理、G-Code 控制、切片、打印机管理
- **智能路由**：根据打印机类型自动选择最佳传输协议
- **G-Code 安全校验**：内置校验器检查温度、速度、流量等安全限制
- **多切片器集成**：支持 PrusaSlicer、CuraEngine、OrcaSlicer，内置 6 个预设配置
- **网络发现**：mDNS/Bonjour + 子网端口扫描自动发现局域网打印机
- **灵活的凭证系统**：配置文件、环境变量、显式参数三种配置方式

---

## 快速开始

```bash
# 1. 安装
pip install -e .

# 2. 配置凭证（见凭证配置章节）
# 创建 timeverse-3dprinter.config.json 或设置环境变量

# 3. 启动 MCP 服务器
timeverse-3dprinter-mcp
```

---

## 安装方式

### 方式一：通过 uvx 安装（推荐）

[uvx](https://docs.astral.sh/uv/) 是 Astral 提供的快速 Python 包运行工具：

```bash
# 直接运行（无需安装）
uvx timeverse-3dprinter-mcp

# 或全局安装后运行
uv tool install timeverse-3dprinter-mcp
uvx timeverse-3dprinter-mcp
```

从本地源码运行：

```bash
uvx --from . timeverse-3dprinter-mcp
```

### 方式二：通过 pip 安装

```bash
# 从 PyPI 安装
pip install timeverse-3dprinter-mcp

# 从本地源码安装
pip install -e .

# 启动服务器
timeverse-3dprinter-mcp
```

### 方式三：直接 Python 运行

```bash
# 克隆/下载源码后
cd timeverse-3dprinter-mcp

# 直接运行（无需安装）
python -m timeverse_3dprinter_mcp.server

# 或先安装依赖再运行
pip install mcp pyserial httpx websockets paho-mqtt zeroconf trimesh
python -m timeverse_3dprinter_mcp.server
```

---

## 凭证配置指南

远程打印需要认证凭证（API 密钥、访问码等）。不同传输协议需要的凭证如下：

| 传输协议 | 必需凭证 | 配置字段 |
|----------|---------|---------|
| **OctoPrint** | API Key | `api_key` |
| **Moonraker (Klipper)** | API Key（可选） | `api_key` |
| **Repetier Server** | API Key | `api_key` |
| **Bambu Lab** | 序列号 + 访问码 | `serial_number` + `access_code` |
| **Duet** | 无需 | — |
| **串口 (USB)** | 无需 | — |
| **Raw TCP** | 无需 | — |

**凭证优先级**（高 → 低）：显式传入参数 > 配置文件 > 环境变量

### 方法 A：配置文件（推荐）

在**当前工作目录**下创建 `timeverse-3dprinter.config.json`，或在用户目录 `~/.timeverse-3dprinter/config.json` 创建：

```json
{
  "printers": {
    "octopi": {
      "host": "192.168.1.100",
      "port": 5000,
      "transport": "octoprint",
      "api_key": "你的 OctoPrint API 密钥"
    },
    "klipper_box": {
      "host": "192.168.1.101",
      "port": 7125,
      "transport": "moonraker",
      "api_key": "你的 Moonraker API 密钥"
    },
    "bambu_x1": {
      "host": "192.168.1.102",
      "transport": "bambu",
      "serial_number": "打印机序列号",
      "access_code": "12345678"
    },
    "repetier_printer": {
      "host": "192.168.1.103",
      "port": 3344,
      "transport": "repetier",
      "api_key": "你的 Repetier API 密钥"
    }
  },
  "defaults": {
    "api_key": "",
    "username": "",
    "password": ""
  }
}
```

**配置文件搜索顺序：**
1. `./timeverse-3dprinter.config.json`（当前目录）
2. `~/.timeverse-3dprinter/config.json`（用户目录）

### 方法 B：环境变量

启动服务器前设置环境变量，或在 MCP 客户端配置的 `env` 字段中设置：

```bash
# Windows PowerShell
$env:TIMEVERSE_3DPRINTER_API_KEY = "你的全局 API 密钥"
$env:TIMEVERSE_3DPRINTER_USERNAME = "用户名"
$env:TIMEVERSE_3DPRINTER_PASSWORD = "密码"

# 按打印机名设置（将 MY_PRINTER 替换为实际打印机名）
$env:TIMEVERSE_3DPRINTER_MY_PRINTER_API_KEY = "打印机专用 API 密钥"
$env:TIMEVERSE_3DPRINTER_MY_PRINTER_ACCESS_CODE = "打印机访问码"
$env:TIMEVERSE_3DPRINTER_MY_PRINTER_SERIAL_NUMBER = "打印机序列号"

# Bambu Lab 专用
$env:TIMEVERSE_3DPRINTER_BAMBU_SERIAL_NUMBER = "Bambu 序列号"
$env:TIMEVERSE_3DPRINTER_BAMBU_ACCESS_CODE = "Bambu 访问码"
```

```bash
# Linux/macOS
export TIMEVERSE_3DPRINTER_API_KEY="你的全局 API 密钥"
export TIMEVERSE_3DPRINTER_BAMBU_SERIAL_NUMBER="Bambu 序列号"
export TIMEVERSE_3DPRINTER_BAMBU_ACCESS_CODE="Bambu 访问码"
```

### 方法 C：工具调用时传入

所有涉及远程连接的 28 个 MCP 工具都支持以下可选参数：

| 参数 | 类型 | 说明 |
|------|------|------|
| `api_key` | `str` | OctoPrint / Repetier / Moonraker API 密钥 |
| `access_code` | `str` | Bambu Lab 局域网访问码 |
| `serial_number` | `str` | Bambu Lab 打印机序列号 |
| `username` | `str` | 登录用户名 |
| `password` | `str` | 登录密码 |

示例：

```
# 在 MCP 客户端中调用工具时传入凭证
send_gcode_tool(
    printer="192.168.1.100",
    commands="M105",
    transport="octoprint",
    api_key="你的 OctoPrint API 密钥"
)

print_file_tool(
    file_path="model.gcode",
    printer="192.168.1.100",
    transport="octoprint",
    api_key="你的 OctoPrint API 密钥"
)

get_printer_status_tool(
    printer="192.168.1.102",
    transport="bambu",
    serial_number="BAMBU序列号",
    access_code="12345678"
)
```

---

## MCP 客户端配置

### uvx 模式

```json
{
  "mcpServers": {
    "timeverse-3dprinter": {
      "command": "uvx",
      "args": ["timeverse-3dprinter-mcp"],
      "env": {
        "TIMEVERSE_3DPRINTER_API_KEY": "你的 API 密钥",
        "TIMEVERSE_3DPRINTER_BAMBU_SERIAL_NUMBER": "Bambu 序列号",
        "TIMEVERSE_3DPRINTER_BAMBU_ACCESS_CODE": "Bambu 访问码"
      }
    }
  }
}
```

### pip 模式

```json
{
  "mcpServers": {
    "timeverse-3dprinter": {
      "command": "timeverse-3dprinter-mcp",
      "args": [],
      "env": {
        "TIMEVERSE_3DPRINTER_API_KEY": "你的 API 密钥"
      }
    }
  }
}
```

### Python 直接运行模式

```json
{
  "mcpServers": {
    "timeverse-3dprinter": {
      "command": "python",
      "args": ["-m", "timeverse_3dprinter_mcp.server"],
      "env": {
        "TIMEVERSE_3DPRINTER_API_KEY": "你的 API 密钥",
        "TIMEVERSE_3DPRINTER_LOG_LEVEL": "info"
      }
    }
  }
}
```

通过 uvx 从本地源码运行：

```json
{
  "mcpServers": {
    "timeverse-3dprinter": {
      "command": "uvx",
      "args": ["--from", "/path/to/timeverse-3dprinter-mcp", "timeverse-3dprinter-mcp"],
      "env": {
        "TIMEVERSE_3DPRINTER_API_KEY": "你的 API 密钥"
      }
    }
  }
}
```

---

### AI 客户端配置示例

#### TimeVerse Studio

在 TimeVerse Studio 的 MCP 配置界面中添加以下配置：

```json
{
  "mcpServers": {
    "timeverse-3dprinter": {
      "command": "uvx",
      "args": ["timeverse-3dprinter-mcp"],
      "env": {
        "TIMEVERSE_3DPRINTER_API_KEY": "你的 OctoPrint API 密钥",
        "TIMEVERSE_3DPRINTER_BAMBU_SERIAL_NUMBER": "Bambu 打印机序列号",
        "TIMEVERSE_3DPRINTER_BAMBU_ACCESS_CODE": "Bambu 局域网访问码"
      },
      "description": "3D 打印机控制 MCP 服务器"
    }
  }
}
```

#### Claude Desktop

将以下配置添加到 `claude_desktop_config.json`：

```json
{
  "mcpServers": {
    "timeverse-3dprinter": {
      "command": "uvx",
      "args": ["timeverse-3dprinter-mcp"],
      "env": {
        "TIMEVERSE_3DPRINTER_API_KEY": "你的 OctoPrint API 密钥"
      }
    }
  }
}
```

#### Cursor / Windsurf

在 MCP 配置文件中添加：

```json
{
  "mcpServers": {
    "timeverse-3dprinter": {
      "command": "uvx",
      "args": ["timeverse-3dprinter-mcp"]
    }
  }
}
```

> **注**：如果项目未发布到 PyPI，将 `args` 中的包名替换为本地路径：`["--from", "/path/to/timeverse-3dprinter-mcp", "timeverse-3dprinter-mcp"]`

#### VS Code (通过 Continue 扩展)

在 `~/.continue/config.json` 中添加：

```json
{
  "experimental": {
    "mcpServers": {
      "timeverse-3dprinter": {
        "command": "uvx",
        "args": ["timeverse-3dprinter-mcp"],
        "env": {
          "TIMEVERSE_3DPRINTER_API_KEY": "你的 API 密钥"
        }
      }
    }
  }
}
```

---

## 工具列表

### 发现工具 (3 个)

| 工具 | 说明 |
|------|------|
| `list_printers_tool` | 列出所有可连接的打印机（USB 串口 + 网络） |
| `discover_printers_tool` | 通过 mDNS 和端口扫描发现局域网打印机 |
| `get_printer_info_tool` | 获取指定打印机的详细信息 |

### 打印工具 (7 个)

| 工具 | 说明 |
|------|------|
| `print_file_tool` | 打印 G-Code 文件到目标打印机 |
| `slice_and_print_tool` | 切片 3D 模型后打印到目标打印机 |
| `start_print_tool` | 启动打印机上的打印任务 |
| `pause_print_tool` | 暂停当前打印任务 |
| `resume_print_tool` | 恢复已暂停的打印任务 |
| `stop_print_tool` | 停止当前打印任务 |
| `cancel_print_tool` | 取消打印，可选关闭加热器和电机 |

### 状态查询 (4 个)

| 工具 | 说明 |
|------|------|
| `get_printer_status_tool` | 查询打印机完整状态（在线、温度、进度、错误） |
| `get_temperatures_tool` | 查询喷头、热床、腔体温度 |
| `get_print_progress_tool` | 查询打印进度 |
| `get_position_tool` | 查询打印头位置 (X/Y/Z/E) |

### 文件管理 (4 个)

| 工具 | 说明 |
|------|------|
| `list_files_tool` | 列出打印机上的文件 |
| `upload_file_tool` | 上传文件到打印机 |
| `download_file_tool` | 从打印机下载文件 |
| `delete_file_tool` | 删除打印机上的文件 |

### G-Code 指令 (7 个)

| 工具 | 说明 |
|------|------|
| `send_gcode_tool` | 发送 G-Code 指令并获取响应 |
| `home_axes_tool` | 归位打印机轴到原点 |
| `set_temperature_tool` | 设置喷头/热床/腔体温度 |
| `set_fan_speed_tool` | 设置风扇转速 |
| `move_axis_tool` | 手动移动打印头 |
| `auto_bed_level_tool` | 执行自动调平 |
| `set_speed_flow_tool` | 设置速度和流量倍率 |

### 切片工具 (3 个)

| 工具 | 说明 |
|------|------|
| `slice_model_tool` | 将 3D 模型（STL/OBJ/3MF）切片为 G-Code |
| `list_slice_profiles_tool` | 列出可用切片配置文件 |
| `get_slice_estimate_tool` | 估算打印时间和耗材用量 |

### 管理工具 (4 个)

| 工具 | 说明 |
|------|------|
| `connect_printer` | 连接到打印机 |
| `disconnect_printer` | 断开打印机连接 |
| `emergency_stop` | 紧急停止 (M112) |
| `disable_motors` | 禁用步进电机 (M84) |

---

## 传输协议说明

| 协议 | 依赖库 | 适用场景 |
|------|--------|---------|
| **Serial (USB)** | `pyserial` | 核心 USB 连接，适用于 Marlin/RepRap/GRBL 固件 |
| **OctoPrint** | `httpx` | OctoPrint REST API + WebSocket 状态推送 |
| **Moonraker** | `httpx` | Klipper 固件通过 Moonraker API 控制 |
| **Duet** | `httpx` | Duet/RRF 系列主板 Web 控制 |
| **Repetier** | `httpx` | Repetier Server 多打印机管理 |
| **Bambu Lab** | `paho-mqtt` | X1/P1/A1 系列通过 MQTT 协议通信 |
| **Raw TCP** | `asyncio` | 直接 TCP 发送 G-Code（端口 9100） |

---

## 项目结构

```
timeverse-3dprinter-mcp/
├── pyproject.toml
├── src/timeverse_3dprinter_mcp/
│   ├── server.py                  # MCP 服务器入口（32 个工具）
│   ├── tools/                     # MCP 工具定义（6 个模块）
│   │   ├── discovery.py
│   │   ├── printing.py
│   │   ├── status.py
│   │   ├── files.py
│   │   ├── gcode.py
│   │   └── slicing.py
│   ├── transports/                # 传输层（7 种协议）
│   │   ├── base.py                # 抽象基类
│   │   ├── router.py              # 传输路由器
│   │   ├── serial_transport.py
│   │   ├── octoprint_transport.py
│   │   ├── moonraker_transport.py
│   │   ├── duet_transport.py
│   │   ├── repetier_transport.py
│   │   ├── bambu_transport.py
│   │   └── raw_tcp.py
│   ├── gcode/                     # G-Code 处理
│   │   ├── builder.py             # 指令构建器
│   │   ├── parser.py              # 文件解析器
│   │   ├── validator.py           # 安全校验
│   │   └── temp_monitor.py        # 温度监控
│   ├── slicing/                   # 切片器集成
│   │   ├── base.py
│   │   ├── prusaslicer.py
│   │   ├── cura_engine.py
│   │   ├── orcaslicer.py
│   │   └── profiles.py
│   ├── discovery/                 # USB/网络发现
│   │   ├── serial_scan.py
│   │   ├── mdns_discovery.py
│   │   └── network_scan.py
│   └── utils/                     # 工具模块
│       ├── config.py              # 凭证/配置管理
│       ├── types.py               # 数据模型
│       ├── errors.py              # 错误处理（21 种错误码）
│       ├── logger.py              # 日志
│       └── platform.py            # 平台检测
└── tests/
```

---

## 环境变量参考

| 变量名 | 默认值 | 说明 |
|--------|--------|------|
| `TIMEVERSE_3DPRINTER_LOG_LEVEL` | `info` | 日志级别：debug / info / warning / error |
| `TIMEVERSE_3DPRINTER_API_KEY` | — | 全局默认 API 密钥 |
| `TIMEVERSE_3DPRINTER_USERNAME` | — | 全局默认用户名 |
| `TIMEVERSE_3DPRINTER_PASSWORD` | — | 全局默认密码 |
| `TIMEVERSE_3DPRINTER_BAMBU_SERIAL_NUMBER` | — | Bambu Lab 打印机序列号 |
| `TIMEVERSE_3DPRINTER_BAMBU_ACCESS_CODE` | — | Bambu Lab 局域网访问码 |
| `TIMEVERSE_3DPRINTER_{名称}_API_KEY` | — | 按打印机名的 API 密钥（替换 `{名称}`） |
| `TIMEVERSE_3DPRINTER_{名称}_ACCESS_CODE` | — | 按打印机名的访问码 |
| `TIMEVERSE_3DPRINTER_{名称}_SERIAL_NUMBER` | — | 按打印机名的序列号 |
| `TIMEVERSE_3DPRINTER_{名称}_USERNAME` | — | 按打印机名的用户名 |
| `TIMEVERSE_3DPRINTER_{名称}_PASSWORD` | — | 按打印机名的密码 |
| `TIMEVERSE_3DPRINTER_MCP_PRUSASLICER_PATH` | — | 自定义 PrusaSlicer 可执行文件路径 |
| `TIMEVERSE_3DPRINTER_MCP_CURA_ENGINE_PATH` | — | 自定义 CuraEngine 可执行文件路径 |
| `TIMEVERSE_3DPRINTER_MCP_ORCASLICER_PATH` | — | 自定义 OrcaSlicer 可执行文件路径 |

---

## 许可证

MIT
