企业官网建设流程全解析

“让 AI 走进我的 3D 世界：一个 MCP server 的完整实现”——如果你经常跟 3D 设计工具和 AI 助手打交道，这句话大概一眼就能看懂在说什么：让大模型真正动手修改三维场景。我以前一直有一个痛点，AI 聊天很好用，但我的三维软件它碰不到。场景文件在本地软件里，模型在云端聊天，中间就像隔了一堵墙。这个项目就是在墙上凿开了一扇门：我实现了一个完整的 MCP server，它作为 AI 和三维设计工具之间的桥梁，让 AI 能按标准协议查询场景、建物体、移动修改。我会从需求背景、协议设计、代码实现到踩坑记录完整展开，适合想在自己工作流里接入 AI 的开发者、刚接触 MCP 概念的初学者，也适合所有想做“AI+生产工具”落地的朋友。

1. 项目立项：为什么我坚持用 MCP 而不是直接写脚本

1.1 问题背景：AI 能说不能做

我平时的工作里有一大块是搭 3D 场景，看起来挺酷，实际大量时间花在重复劳动上：建一堆基础几何体、摆位置、调尺寸、批量重命名、按网格排列。这种活不需要太多创意，但特别耗时间。我最早的想法很朴素，既然 AI 这么能聊，能不能让它直接帮我把场景搭出来？于是我试了市面上常见的对话工具，发现它们顶多给我一段脚本，我还得手动贴回三维软件里跑。更头疼的是，跑完经常出问题——坐标单位对不上、对象名对不上、没有容错。

问题不是 AI 笨，而是它根本不知道场景里现在有什么，也没有任何办法直接操作我的设计工具。让 AI 走进我的 3D 世界，缺的不是一个会聊天的模型，而是一个能让模型“动手”的通道。后来我接触到了 MCP（Model Context Protocol，模型上下文协议），才发现这条路才是正解：模型通过 MCP 客户端找到服务端，服务端暴露一批工具，模型再通过工具调用去操作真实世界。

1.2 MCP 核心概念一句话讲透

MCP 本质上是一套标准协议，你可以把每个 MCP server 理解成一个“USB-C 接口”——设备端厂商只要做一个统一接口，充电、传数据、连显示器都能走同一个口。AI 模型和三维软件之间也一样：三维软件侧只要把一个 MCP server 跑起来，暴露出 tools（工具）、resources（资源）和 prompts（提示），AI 侧不需要单独定制插件，直接用标准客户端连上来就行。

对我来说最大的好处是“一次适配，处处可接”：不管未来换哪个 AI 服务，只要它支持 MCP，我的三维工具链就能被它调用。以前那种“为某个模型单独写插件”的套路，升级一次换一个模型就得跟着改，简直是在给软件打工。MCP 这套标准把“聊天”和“操作”解耦得明明白白。

1.3 方案对比：三种打通方式各自优劣

我在决定用 MCP 之前，认真对比过另外两种常见做法，这里给你列个表：

MCP 方案不是没有成本，额外多了一层服务，但这层服务恰好是最值得的调节阀。权限控制、参数校验、审计日志、快照回滚都可以放在这一层做。没有这层服务，AI 就是个拿着大锤乱砸的实习生，有了一层可控的服务，AI 才真正变成了可以放心交代任务的同事。

2. 关键设计：MCP 协议怎么描述一个 3D 场景

2.1 第一件事：圈定 AI 的操作边界

我做这个项目的第一步不是写代码，而是先定边界。AI 能碰什么、不能碰什么，必须在一开始就约定好。我把工具分成两组：

可开放给 AI 的：

• 创建基础几何体：立方体、球体、圆柱体、平面
• 物体变换：移动、旋转、缩放
• 批量处理：按规则重命名、按网格排列
• 资源查询：返回场景内物体清单、包围盒、层级关系
• 快照：对当前场景做快照和回滚

不开放给 AI 的：

• 删除未备份的资产
• 执行任意代码或运行未知插件
• 修改全局渲染参数
• 导出最终生产文件
• 修改参考坐标系这类深层设置

为什么这么分？因为 AI 的决策是基于概率的，即使它 99% 的时候都正确，在真实生产里那 1% 也可能毁掉半天工作量。所以我给 AI 开放的操作范围，控制在“破坏力有限、可以撤销”的范围内。这一点一定要在做功能前想清楚，不然等模型开始自由发挥再想拦就来不及了。

2.2 第二件事：用 JSON-RPC 描述工具

MCP 底层用了 JSON-RPC 2.0 风格的请求响应。每个请求自带 id、method 和 params。以工具列表为例，AI 客户端启动后会先发一个 tools/list 请求，我的 server 返回一个 JSON 数组：

[ { "name": "create_box", "description": "以指定中心点创建立方体，position 为三维坐标，size 为边长，单位米。", "inputSchema": { "type": "object", "properties": { "name": {"type": "string", "description": "物体名称，建议使用英文标识"}, "x": {"type": "number", "description": "中心点 X 坐标，单位米"}, "y": {"type": "number", "description": "中心点 Y 坐标，单位米"}, "z": {"type": "number", "description": "中心点 Z 坐标，单位米"}, "size": {"type": "number", "minimum": 0.01, "maximum": 100, "description": "边长，单位米"} }, "required": ["name", "x", "y", "z", "size"] } } ]

这段定义看着简单，里面全是经验。description 决定了模型会不会用对工具，所以我把单位、坐标系、默认值全部写进去了。比如 Y 轴向上还是 Z 轴向上，不同软件约定不同，不写清楚 AI 真的会猜错。inputSchema 里的 minimum 和 maximum 也是关键，后面排查参数失控时会讲到。

再往后是 tools/call，请求体类似这样：

{ "method": "tools/call", "params": { "name": "create_box", "arguments": {"name": "platform", "x": 0, "y": 0, "z": 0, "size": 2} } }

server 返回结果时带上 content 和 isError 字段。协议层面能看到的东西就这么点，真正难的地方在于，怎么让 AI 拿到的信息足够执行任务，同时又不会信息爆炸。

2.3 第三件事：同步场景状态，避免 AI 瞎指挥

你可能会想：模型不是有上下文吗？让它记住场景不就行了？实际完全不行。3D 场景里的顶点、材质、灯光数据量巨大，上下文根本装不下，而且语言模型对精确坐标的记忆能力很差，聊着聊着它就给你编一个坐标出来。所以我的 MCP server 维护了一个“场景状态缓存”：每次工具调用成功后，都重新生成一份精简的场景摘要——物体 id、名称、中心坐标、包围盒、父子关系。

工具返回结果里同时附带最新版本号。比如移动一个物体后，返回：

{ "content": [ {"type": "text", "text": "Moved cube_a to (1.5, 0.0, 0.0)"}, {"type": "text", "text": "state_version: 42"} ] }

AI 如果想基于当前状态做下一步，直接读取返回值即可。这里我吃过亏：最开始我返回完整坐标列表，结果模型被海量数字淹没，反而忽略关键信息。后来把数据精简成“语义摘要”，模型理解准确率明显上升。

有个细节值得展开：我刻意不让 MCP server 主动把全场景推给 AI，而是等 AI 先调用一个“查询场景”的工具，按需返回。这样上下文里只有需要的数据，不会污染模型的注意力。这套按需拉取的思路，比无脑塞上下文高效得多。

2.4 安全护栏：权限、校验、回滚

AI 接入工具链之后，最怕它做不可逆操作。我在 MCP server 里做了三道护栏。

第一道护栏是工具白名单。没注册的工具不可调用，从机制上杜绝任意代码执行。MCP 协议只会响应你已经注册的 tools，所以不要把“执行脚本”这种工具暴露给模型。

第二道护栏是参数范围校验。inputSchema 里已经写了最小最大值，server 端执行前再校验一遍。模型理解“放大一点”可能直接传 1e9，这种离谱参数必须在进引擎前挡下来。

第三道护栏是快照回滚。每次成功操作前，如果有需要，我先对场景做快照，错乱时可以直接恢复。做这些不是为了让 AI 束手束脚，恰恰是为了让 AI 能放手干活。人出差错有责任约束，AI 出差错没有责任，所以系统必须有恢复能力。我在实际使用中把快照和审计日志绑在一起，调用工具前记录一笔，调用后记录一笔，出了事能查到哪个时间点、哪个会话、哪条指令触发了哪个操作。

3. 实操实现：一步一步把 MCP server 跑起来

3.1 环境与目录结构

先说明我的运行环境：一台装有三维设计软件的普通电脑，Python 3 解释器，再加一个支持 MCP 协议的大模型客户端。我特意没有用任何第三方 MCP SDK，而是用 Python 标准库手写了一个最小实现。好处是你看完核心逻辑，再去看官方 SDK 会非常容易，不会被封装挡住视线。

目录结构是这样的：

ai_3d_bridge/ server.py # MCP 服务端主循环 tools_3d.py # 3D 工具定义与分发 engine_bridge.py # 与三维软件 API 对接的桥接层 state.py # 场景状态缓存与快照管理 audit.log # 操作审计日志

职责划分很明确：server.py 只负责协议收发，tools_3d.py 只负责描述工具，engine_bridge.py 负责调用底层软件，state.py 负责记录状态。这样的分层有个好处，将来换一套三维软件，只需要改 engine_bridge.py 这一个文件。

3.2 一个最小 MCP server 主体

server.py 的核心是一个读取 stdin、写出 stdout 的事件循环。MCP 使用标准输入输出作为传输层，是因为客户端把 server 作为子进程跑起来非常方便，不需要配置端口，不需要守护进程。我用 Python 标准库实现的基础结构：

import json import sys def send(id_value, result=None, error=None): payload = {"jsonrpc": "2.0", "id": id_value} if error: payload["error"] = error else: payload["result"] = result sys.stdout.write(json.dumps(payload) + "\n") sys.stdout.flush() def handle_request(req): method = req.get("method") rid = req.get("id") if method == "initialize": return send(rid, { "protocolVersion": "2024-11-05", "capabilities": {"tools": {}} }) if method == "tools/list": return send(rid, {"tools": list_tools()}) if method == "tools/call": params = req.get("params", {}) name = params.get("name") arguments = params.get("arguments", {}) try: text, ok = run_tool(name, arguments) return send(rid, { "content": [{"type": "text", "text": text}], "isError": not ok }) except Exception as exc: return send(rid, error={"code": -32603, "message": str(exc)}) return send(rid, error={"code": -32601, "message": "method not found"}) for line in sys.stdin: line = line.strip() if not line: continue try: handle_request(json.loads(line)) except Exception as exc: send(None, error={"code": -32700, "message": str(exc)})

这段代码里有一个非常容易踩的坑：所有日志都不能打印到 stdout。我一开头用 print 调试，结果日志和协议报文混在一起，AI 客户端解析直接报错。要写日志必须写到 stderr 或文件，stdout 只留给 JSON-RPC 报文。

protocolVersion 写哪个版本，以官方最新文档为准。我这里写的版本号就是个占位，实际跑的时候去官方文档抄一份最新的回来就行，重点是理解消息交互流程。

3.3 注册 3D 工具集

在 tools_3d.py 里，我定义了一个 TOOLS 列表和一个分发函数。工具注册这块，description 是最关键的，绝不能只写“创建立方体”，一定要带上单位、坐标系、相对还是绝对。给 token 有限的模型看，这些细节直接决定结果。

TOOLS = [ { "name": "create_box", "description": "在场景中心点创建立方体，position 为 xyz 坐标，size 为边长，单位米", "inputSchema": { "type": "object", "properties": { "name": {"type": "string", "description": "物体名称，建议使用英文标识"}, "x": {"type": "number", "description": "中心 X 坐标，米"}, "y": {"type": "number", "description": "中心 Y 坐标，米"}, "z": {"type": "number", "description": "中心 Z 坐标，米"}, "size": {"type": "number", "minimum": 0.01, "maximum": 100, "description": "边长，米"} }, "required": ["name", "x", "y", "z", "size"] } }, { "name": "move_object", "description": "移动物体到新的坐标位置，relative 为 true 时表示相对位移", "inputSchema": { "type": "object", "properties": { "object_id": {"type": "string"}, "x": {"type": "number"}, "y": {"type": "number"}, "z": {"type": "number"}, "relative": {"type": "boolean", "default": False} }, "required": ["object_id", "x", "y", "z"] } }, { "name": "list_scene", "description": "返回场景内所有物体的语义摘要，不包含顶点数据", "inputSchema": { "type": "object", "properties": {} } }, { "name": "delete_object", "description": "按 object_id 删除物体，操作前自动创建快照", "inputSchema": { "type": "object", "properties": {"object_id": {"type": "string"}}, "required": ["object_id"] } } ] def run_tool(name, args): if name == "create_box": validate(args) return engine_bridge.create_box(args) if name == "move_object": validate(args) return engine_bridge.move_object(args) if name == "list_scene": return state.snapshot_as_text(), True if name == "delete_object": return engine_bridge.delete_object(args) return f"Unknown tool: {name}", False

inputSchema 不要过度复杂，除了必要的 JSON Schema 字段之外别塞自定义属性，很多客户端在解析时遇到看不懂的字段会直接报错。工具列表先保持精简，能让模型在几步内完成一个有用任务就够了。

3.4 状态同步与 engine_bridge

engine_bridge.py 是唯一的“沾三维软件味儿”的模块。它把上层发来的操作翻译成软件 API 调用，并更新 state。比如：

import state def create_box(args): # 调用三维软件自身的 Python API 创建对象 object_id = scene_api.create_primitive( kind="box", name=args["name"], position=(args["x"], args["y"], args["z"]), size=args["size"] ) state.record({ "object_id": object_id, "name": args["name"], "position": (args["x"], args["y"], args["z"]), "bounds": [args["size"] / 2] * 3 }) return f"Created box {object_id} at ({args['x']}, {args['y']}, {args['z']}) size {args['size']}", True

这里的 scene_api 替换成你自己用的三维软件接口就行，结构不变。我把所有涉及具体软件的部分都隔离在这一层，以后换软件只需要改这个文件。

state.py 维护一个简易字典，记录每个物体最近的状态和全局版本号：

_state = {} _version = 0 def record(obj_summary): global _version _state[obj_summary["object_id"]] = obj_summary _version += 1 def snapshot(): return {"version": _version, "objects": list(_state.values())} def snapshot_as_text(): lines = [f"state_version: {_version}"] for obj in _state.values(): lines.append(f"{obj['object_id']} | {obj['name']} | position={obj['position']} | bounds={obj['bounds']}") return "\n".join(lines) def rollback_to(version, snapshot): # 调用引擎层做恢复 pass

在实际生产版本里，state 和 engine_bridge 的粒度会比这细很多：要考虑物体被软件内部操作改了、要考虑批量操作时原子更新。但对第一版来说，这个设计已经足够跑通全链路了。

3.5 接入大模型客户端

server 跑起来之后，还剩最后一环：大模型客户端怎么连上它。现在常用的方式是在客户端里添加一个 MCP 服务配置，填上启动命令。服务启动后，客户端自动发送 tools/list 获取工具列表。你用自然语言问 AI 问题时，模型会根据工具的 description 自主决定是否调用、按什么参数调用。

这一步不需要你写太多代码，但有一个验证顺序值得参考。第一，先手动检查 server 能否启动，tools/list 返回的 JSON 是否合法。第二，用一个最简单的 MCP 客户端连接，问“场景里现在有什么”，看它是否会调用 list_scene。第三，再问“在原点创建一个边长 2 米的立方体”，看它是否自动调用 create_box 并传对参数。能走到第三步，哪怕中间出错了，你都真正踏入了“AI+3D”的门槛，剩下的全是细节打磨。

3.6 自然语言建场景演示

我记录一次最典型的实操对话。我在客户端输入：

在原点创建一个边长 2 米的立方体作为平台，然后在它上方 0.5 米处放一个半径 0.3 米的球。

模型的实际计算路径是这样的：首先调用 create_box，name=platform, x=0, y=0, z=0, size=2，得到 object_id 和 state_version。然后推理“上方 0.5 米”意味着球心位于 (0, 1.5, 0)，因为平台高度 2 米，顶面在 y=1，再加 0.5 米就是 1.5。接着调用 create_sphere，position=(0, 1.5, 0)，radius=0.3。服务器返回两次成功，场景里出现一个平台加一个球。

我盯着 JSON 日志看的时候，发现它确实理解了我工具描述里的坐标和单位。这里我要强调：我没有写任何“教学代码”，模型就是通过 description 学习到“y 轴向上、单位是米、坐标是中心点”的约定。所以工具描述质量，决定了 AI 使用工具的上限。

当然也有翻车的时候。它偶尔会把“上方 0.5 米”理解成绝对 y 坐标 0.5，这让我把 description 改成“所有坐标均为场景绝对坐标，若需要相对上方，请先通过 list_scene 确认物体当前位置再计算”。改完之后准确率大幅提升。这种“系统性补丁”就是做 MCP server 最花时间也最值得做的事。

4. 常见问题与排错：把踩过的坑一次说清

4.1 卡死与超时：事件循环没对齐

现象是客户端调用 create_box 后一直转圈，直到超时。我第一次遇到这个问题，第一反应是引擎 API 慢了。后来看进程才发现 server 主线程在等一个耗时操作完成，而 MCP 还在等其他请求，整个服务像被冻住。解决办法是：耗时工具调用放进线程池，主循环只负责收发消息。设计上更简单一点，可以让 tools/call 进入队列，worker 线程取走执行，结果再写回。

还有一个让我记忆深刻的大坑——我在 server.py 里用了 print 调试，日志和协议报文混在一起，客户端直接解析失败。排查了很久才发现，原来是自己在干净的通信信道里倒垃圾。后来 stdout 打印全部禁掉，问题才彻底消失。这个坑在 MCP 开发里属于必踩之一。

4.2 数据不一致：缓存和真实场景脱节

现象是 AI 先创建一个立方体，紧接着问“场景里一共有几个物体”，它回答 0 个。原因不是 AI 没记性，而是我的 state 缓存是启动时生成的，之后再也没有更新。MCP server 默认不会订阅三维软件内部的变化，所以我给所有工具调用都加了“操作后刷新”逻辑，并且在每次返回结果里带上当前版本号。

如果你的场景可能被多个脚本同时改动，这套方案还是不够，最好用三维软件自身的事件回调主动推给 server。但对第一版而言，工具调用后刷新缓存完全够用。每次返回版本号这个习惯也帮我省了很多排查时间——一旦发现版本号没变，就知道状态没有更新。

4.3 参数失控：AI 把场景搞崩了

现象是 AI 说“把球放大一点”，结果它真的传了一个 size: 1000000。核心原因是模型对数字没有太大直觉，我也没有在 schema 里限制范围。后来我在 inputSchema 里给所有数字加了 minimum 和 maximum，同时 server 端做了一次硬校验：

def validate(name, args): if name == "create_box": size = args.get("size", 2) if not (0.01 <= size <= 100): raise ValueError("size must be between 0.01 and 100") if name == "move_object": coords = [args.get(axis, 0) for axis in ("x", "y", "z")] if any(abs(c) > 1000 for c in coords): raise ValueError("coordinate out of range")

这样无论模型怎么发挥，极端参数都进不了引擎。这个经验可以推广到所有 AI 工具：schema 限制只是第一道门，执行前校验才是最后一道门。如果只依赖模型自觉，迟早会出乱子。

4.4 多会话并发：两个客户端窗口互相打架

现象是我同时开着两个客户端窗口，一个让 AI 删掉场景中所有物体，另一个让它移动物体，结果删除和移动交替执行，状态彻底乱套。MCP 本身支持多个会话，但三维软件的操作不能并行，所以我给 engine_bridge 的操作加了全局锁：

import threading _lock = threading.Lock() def create_box(args): with _lock: # 调用引擎 API pass

虽然牺牲了并发性，但在个人 3D 工作流里，串行操作远比并发惹麻烦好。如果以后真有并发需求，再考虑操作队列和事务补偿也不迟。对小规模场景，一个全局锁是最简单也最可靠的方案。

4.5 排查速查表

我把这些坑整理成一张表，方便你直接对照：

这张表是我多天踩坑的浓缩，遇到同样问题可以省下最痛苦的排错时间。

4.6 把审计日志坚持写下去

最后说一个我坚信多年的习惯：在 server 里把每次工具调用和结果追加到 audit.log。一开始看起来有点多余，但当你发现 AI 多删了一个物体、或者想复盘“它为什么会调用这个工具”时，日志会立刻告诉你，在哪个时间点、哪个会话、哪条指令触发了哪个工具。这是普通的版本管理给不了的信息。我也会在日志里保存当时的 state_version，回滚时直接定位目标版本。

import datetime def audit(operation, args, result, version): with open("audit.log", "a", encoding="utf-8") as f: f.write(f"{datetime.datetime.now().isoformat()} | {operation} | {args} -> {result} | version={version}\n")

个人项目做到这个程度，有人会觉得过度设计。但一段时间用下来，这套审计机制救了我好几次，尤其是当 AI 连续执行多步操作、中间一步出错时，没有日志你根本想不到它是在哪一步把场景弄乱的。

MCP server 做完以后，我对 AI 和 3D 结合的看法务实了不少。它解决的不是“AI 会不会建模”的问题，而是“AI 能不能在我的工作流里帮忙干活”的问题。真正的重点不是协议写得多漂亮，而是场景状态的同步、操作边界的约束、错误处理的兜底，这些都是在对话界面之外真正决定项目是否可用的细节。如果你的目标也是让 AI 参与你的 3D 工作流，建议哪怕只从一个 create_box 开始，跑通整条链路，你很快会发现下一步该做什么。我目前已经把重复的资产整理和原型生成交给 AI，关键节点仍由自己确认；下一步打算给 server 加上实时预览和双向同步，让 AI 不只站在场景外发指令，而是和我共享同一个 3D 工作台。