项目简介

这是一个基于Model Context Protocol (MCP) 标准实现的服务器应用。它的主要功能是接收一个2D图像文件（本地路径或网络URL），通过图像处理将其转换为适合3D打印的STL格式浮雕模型。

主要功能点

• 图像转浮雕模型： 将任何2D图像转换为具有深度信息的3D浮雕模型。
• 尺寸控制： 可以精确控制生成的3D模型的宽度和最大厚度。
• 添加底座： 可以在浮雕模型下方添加一个指定厚度的底座，方便3D打印。
• 深度反转： 支持反转浮雕深度，改变高低区域的效果。
• 细节级别调整： 允许控制图像处理的分辨率，影响模型细节和文件大小。
• 输出文件： 生成处理后的深度图（PNG格式）和最终的3D模型（STL格式），并提供文件路径。

安装步骤

1. 克隆仓库： 打开终端，运行以下命令下载项目代码：

   git clone https://github.com/bigchx/mcp_3d_relief.git
   cd mcp_3d_relief
   

2. 安装依赖： 确保您已安装 Python 3.10+ 和 'uv' 包管理工具。然后运行以下命令安装项目所需的库：

   uv pip sync requirements.txt
   

服务器配置

要让支持MCP协议的客户端（如某些LLM客户端或开发工具）能够发现并运行此服务器，您需要在客户端的MCP服务器配置文件中添加相应的配置项。典型的配置信息格式为JSON，需要指定服务器的名称、启动命令及其参数。

根据本项目仓库的信息，您需要添加一个名为 '"mcp_3d_relief"' 的服务器配置，并指定使用 'uv' 命令来运行项目目录下的 'server.py' 文件。

以下是配置所需的信息结构描述（这不是直接的代码，而是您需要填写到客户端配置文件中的信息）：

• 服务器名称 (Server Name): 设置为 '"mcp_3d_relief"'。这是客户端用来识别此服务器的唯一名称。
• 启动命令 (Command): 设置为 '"uv"'。这是执行服务器的程序名。
• 启动参数 (Args): 设置为一个字符串数组，包含启动 'server.py' 所需的参数。通常是 '["--directory", "【您的项目根目录路径】", "run", "server.py"]'。请务必将 '【您的项目根目录路径】' 替换为您在安装步骤中克隆的项目仓库的实际路径。

例如，如果您的项目克隆到 '/home/user/mcp_3d_relief' 目录，那么启动参数数组应类似于 '["--directory", "/home/user/mcp_3d_relief", "run", "server.py"]'。

完成配置后，您的MCP客户端即可通过此配置启动和连接到图像转3D浮雕MCP服务器。

基本使用方法

一旦服务器通过上述配置启动并连接到MCP客户端，LLM或其他客户端可以将其视为一个可调用的“工具”。要使用此工具生成3D浮雕模型，客户端需要向服务器发送一个工具调用请求，并提供以下参数：

• 'image_path' (字符串): 输入图像的路径。可以是服务器可以访问的本地文件路径，或者一个公开的网络图片URL。
• 'model_width' (浮点数, 可选): 生成的3D模型的宽度（单位：毫米）。默认为 50.0。
• 'model_thickness' (浮点数, 可选): 生成的3D模型的最大厚度/高度（单位：毫米）。默认为 5.0。
• 'base_thickness' (浮点数, 可选): 模型底座的厚度（单位：毫米）。默认为 2.0。
• 'skip_depth' (布尔值, 可选): 是否跳过内置的深度图生成过程，直接使用输入的灰度图像作为深度信息（需要输入的是灰度图）。默认为 'false'。
• 'invert_depth' (布尔值, 可选): 是否反转深度信息。如果设置为 'true'，图像中较亮的区域将对应模型较低的部分，反之亦然。默认为 'false'。
• 'detail_level' (浮点数, 可选): 控制深度图的细节级别。值越高，细节越丰富，但处理时间和STL文件大小会显著增加。默认为 1.0。

工具调用成功后，服务器将返回一个JSON响应，通常包含以下信息：

• 'status' (字符串): 表示操作是否成功，例如 '"success"' 或 '"failed"'。
• 'depth_map_path' (字符串): 生成的深度图文件的服务器本地路径。
• 'stl_path' (字符串): 生成的STL 3D模型文件的服务器本地路径。

客户端（如LLM）可以使用这些返回的路径进一步处理或访问生成的文件。