内容
# 融合工具smith MCP
安全性第一的Autodesk Fusion 360 MCP插件，适用于需要检查、规划、验证和打包CAD更改的代理，而无需盲目运行原始脚本。
融合工具smith MCP在Fusion 360内部运行，通过本地HTTP在端口`9100`暴露MCP，具有可流式HTTP和旧版HTTP/SSE兼容性，并将实时发现数据写入`~/.fusion_mcp.json`。该插件默认情况下是可选的，不会自动随着Fusion启动。
已安装的Fusion插件文件夹仍命名为`FusionMCP`，以便与现有的本地安装保持兼容。
## 为什么选择工具smith
通用的Fusion MCP服务器通常会暴露一个原始的脚本桥。工具smith在该桥周围添加了一个有纪律的CAD工作流程：
- 在编辑之前检查实时模型。
- 映射草图、特征、参数、投影几何和下游依赖项。
- 在原始Fusion API脚本之前，通过结构化的工具路由代理。
- 预检导出和模型突变。
- 将危险工具与正常检查/建模工作流程分开。
- 记录本地的编辑工具调用日志。
在需要代理表现得像一个谨慎的CAD助手而不是仅仅执行Python脚本时使用工具smith。
有关通用CAD工具的积压情况，请参见 [docs/tooling-roadmap.md](docs/tooling-roadmap.md)。
有关公共Fusion MCP比较说明的详细信息，请参见 [docs/external-fusion-mcp-sweep.md](docs/external-fusion-mcp-sweep.md)，这些说明为工具smith的采用层提供了参考。
## 优势
- 检查现有设计：草图、特征、参数、投影几何、选择、依赖关系报告和坐标映射。
- 更安全的模型修改：显式操作、预检、下游消费者警告、设计状态比较前后和验证工具。
- 导出安全：预检的STEP/STL/PDF工作流程。
- 本地运行时强化：固定端口、承载令牌支持、无令牌`/health`、会话TTL清理、单个活动SSE客户端和自动Antigravity配置同步。
- 机器可读的采用元数据：初始化说明、MCP工具/资源注释、`fusion://agent/server-capabilities`、`fusion://agent/tool-profiles`和`fusion://agent/tool-first-workflow`。
## 运行时结构
```text
MCP客户端
-> http://127.0.0.1:9100/sse
-> FusionMCP插件运行在Fusion 360内部
-> Fusion API在Fusion的主线程上
```
发现文件：
```text
C:\Users\<您>\.fusion_mcp.json
```
发现文件包括：
- `sse_url`: 旧版查询令牌URL，供仅支持URL身份验证的客户端使用。
- `bearer_sse_url`: 优先的无令牌URL。
- `streamable_http_url`: 优先的流式HTTP端点。
- `authorization_header`: 优先的承载身份验证头。
- `transports`: 广告的传输模式。
- `port` 和 `token`。
## 从此检查安装
详细的安装和故障排除说明在 [docs/installation.md](docs/installation.md) 中。
以可编辑模式安装管理CLI：
```powershell
python -m pip install -e .
```
安装或刷新Fusion插件文件：
```powershell
fusion-mcp install-addin
```
如果旧版原型插件文件夹`Fusion MCP Addin`存在，安装程序会将其移动到`AddInsDisabled`，以便它无法继续声称端口`9100`或提供过时的工具。如果您故意测试该旧插件，请仅使用`--keep-legacy-addin`。
构建一个可分发的插件ZIP：
```powershell
fusion-mcp package-addin
```
该软件包被写入：
```text
dist\FusionMCP-addin.zip
```
然后从Fusion 360启动或重启`FusionMCP`插件：
```text
Utilities > Add-Ins > Scripts and Add-Ins > Add-Ins > FusionMCP > Run
```
清单将`runOnStartup`设置为`false`。仅在需要时启动插件。
## 验证
运行实时烟雾测试：
```powershell
fusion-mcp test-live
```
`fusion-mcp doctor`还会检查广告的工具注册表。如果安装后缺少必需工具，它将返回非零值，并建议重新加载Fusion插件。
或者直接使用PowerShell脚本：
```powershell
powershell -ExecutionPolicy Bypass -File scripts/test_fusion_mcp_live.ps1
```
检查运行时健康状况：
```powershell
Invoke-RestMethod http://127.0.0.1:9100/health | ConvertTo-Json
```
预期的健康输出包括`discovery`、`transports`、`active_sessions`、`active_http_sessions`、`task_manager_running`和`pending_tasks`。它不应包括令牌或`sse_url`。
## 客户端配置
打印旧式和承载样式的客户端代码段：
```powershell
fusion-mcp print-client-config
```
导出MCP模式包，无需启动Fusion：
```powershell
fusion-mcp dump-schemas --output dist\mcp-schemas.json
```
为客户端集成测试运行确定性的无Fusion模拟服务器：
```powershell
fusion-mcp mock-server --port 9101
```
模拟服务器在`/sse`处公开`/health`和流式HTTP MCP调用。它宣传与`dump-schemas`相同的离线工具/资源/提示表面，但工具调用返回确定性的模拟数据而不是触摸Fusion。
对于Antigravity/Gemini样式的配置，FusionMCP在插件启动时自动同步此文件：
```text
C:\Users\<您>\.gemini\config\mcp_config.json
```
手动同步仍然可用：
```powershell
fusion-mcp sync-config
```
## 工具配置文件
通过CLI和MCP资源层提供机器可读的配置文件：
```powershell
fusion-mcp list-profiles
```
```text
fusion://agent/tool-profiles
```
服务器采用元数据以JSON格式提供：
```text
fusion://agent/server-capabilities
```
该资源总结了支持的传输、发现密钥、初始化说明、安全门、工具/资源注释覆盖、配置文件、提示和功能计数，以便客户端可以路由而无需刮取README文本。
在公开工具给代理或记录工作流程时使用这些心智配置文件：
- `core`：准备就绪、运行时诊断、工作流程路由和更改日志工具。
- `inspection`：设计快照、物理属性和打印适应性检查、草图/特征/参数/依赖关系检查、选择查询、身体面/边目标、装配参考/关节检查、材料/外观报告、时间线/树检查和突变预检。
- `modeling`：结构化草图、约束、投影、拉伸/旋转/扫描/扫描/圆角/倒角/壳、偏移面、组合、图元、组件目标构造几何、刚性点到点关节、圆角切割/凹槽、孔模式、镜像/模式、外观发现/应用、网格转换和组件组织。
- `parameters`：用户/模型参数读取和编辑、参数化规划、草图尺寸编辑和参数CSV导入/导出。
- `export`：预检的STEP/STL/PDF导出以及静止帧捕获助手。
- `presentation`：视口相机、可见性分级、用户提示、截图和`capture_demo_sequence`静止帧序列。
- `document`：文档列表、装配树/参考读取、时间线读取、时间线标记移动和功能配方克隆。
- `docs`：本地Fusion API、工作流程和最佳实践查找。
- `dangerous`：原始脚本、清除日志、文档激活/恢复、撤销、删除和抑制工具。只有在结构化工具不足时才使用。
## 功能矩阵
| 领域 | Toolsmith公开的内容 |
| --- | --- |
| 运行时安全 | `doctor`、初始化说明、离线模式导出、运行时诊断、固定端口健康检查、流式HTTP/SSE元数据、承载认证、MCP只读/破坏性/幂等工具注释、资源排名注释、更改日志、结构化工具路由 |
| 检查 | 设计快照、草图/特征/依赖关系检查、身体面/边目标、装配源/参考/关节报告、物理属性报告、材料/外观报告、网格感知`inspect_printability`警告 |
| 安全建模 | 类型化草图、受保护的草图约束创建/删除、拉伸、旋转、扫描、扫描、目标令牌圆角/倒角/壳、 `offset_face_or_press_pull`、孔、凹槽、镜像、模式、构造几何、刚性点到点关节 |
| 参数 | 用户/模型参数读取、安全编辑、参数化规划、尺寸编辑、CSV导入/导出 |
| 导出和演示 | 预检的STL/STEP/PDF导出、截图、分级可见性、静止帧演示序列 |
| MCP提示 | 工具优先路由、工作流程提示、线程紧固件、钣金规划、打印适应性审查和物理属性审查的提示 |
| 危险工具 | 原始脚本、保护的撤销/恢复、时间线删除/抑制和文档激活与普通工作流程隔离 |
## 开发
运行单元套件：
```powershell
python -m unittest discover -s tests
```
运行结构化实时夹具，当FusionMCP加载并需要更深入的端到端覆盖时：
```powershell
powershell -ExecutionPolicy Bypass -File scripts/test_fusion_mcp_inspection_fixture.ps1
```
有用的启动提示在 [examples/prompts.md](examples/prompts.md) 中。
使用 [docs/demo-script.md](docs/demo-script.md) 记录README的短demo GIF/视频。
## CI 和发布
GitHub Actions运行单元套件，检查无Fusion的模拟/模式表面，并构建插件ZIP。
要发布带有附加插件的GitHub版本：
```powershell
git tag v1.0.0
git push origin v1.0.0
```
## 许可证
MIT。参见 [LICENSE](LICENSE)。
## 更改日志
FusionMCP将本地JSONL工具调用审计条目写入：
```text
C:\Users\<您>\.fusion_mcp\journal.jsonl
```
通过MCP读取它：
```text
fusion://runtime/change-journal
```
或调用：
```text
get_change_journal
clear_change_journal
```
日志中删除了令牌、身份验证头、原始脚本和长字符串参数。
## 本地文档
FusionMCP公开本地Fusion API和最佳实践索引：
```text
fusion://docs/fusion-api
```
使用以下命令搜索：
```text
search_local_fusion_docs
```
这是官方Autodesk文档的离线伴侣，旨在在编写原始Fusion API脚本之前进行快速规划。
## 安全注意事项
- Fusion API调用必须通过`TaskManager`在Fusion的主线程上执行。
- `run_fusion_script`故意作为最后的工具，需要意图/间隙字段。
- 查询令牌身份验证仍用于旧客户端，但推荐使用承载令牌身份验证。
- 如果编辑文件后行为未更改，请重新加载插件或重启Fusion；Fusion可能仍在内存中保留旧的Python模块。
