使用说明

MCP多模态自动化工作区

中文说明

概述

该项目实施了一个完整的多模态工程自动化框架，该框架基于 **模型上下文协议（MCP）**核心设计理念 外部预构建的MCP服务/插件 带着一个 定制内部MCP工具服务器，两者在单个VS Code工作区内协同运行：

外层: .vscode/mcp.json 声明了第三方MCP服务——Playwright、GitHub、Blender MCP、FreeCAD MCP、Godot MCP和官方MATLAB MCP——通过stdio或HTTP连接，所有这些服务都通过VS Code Copilot Agent分发。
自定义图层: omni_mcp.py 在一个Python文件中实现了15个模块的54个工具，涵盖了办公文档、图像处理、视频转码、3D建模、科学计算和系统实用程序。

这些层共同允许LLM代理执行端到端工作流——“获取数据”→ 生成报告→ 渲染3D场景→ 导出视频→ 部署游戏”——在一次对话中，所有调用都通过标准MCP协议进行，以实现完全可重复性。

⭐ 测试报告: mcp_test/FINAL_REPORT.md
📋 执行日志: mcp_test/logs/run_log.md

项目亮点

项目	描述
核心服务器	`omni_mcp.py` --54个MCP工具，单文件实现，stdio传输
集成中心	`.vscode/mcp.json` --7项服务的统一注册（参见插件安装指南)
测试证据	`mcp_test/` --输入、输出、日志和报告；48/48个工具，合格率100%
实用脚本	`render_formulas.py` + `replace_formulas.py` --用于学术PPT的LaTeX公式渲染管道

能力矩阵

模块	工具	覆盖范围
PPTX	3	创建（标题/内容/图像/样式）、阅读幻灯片结构、编辑（文本/注释/布局）
DOCX	3	创建（段落/表格/图像/列表，学术/商业预设样式）、阅读、查找和替换
XLSX	4	创建工作簿（多页）、读取、追加写入、插入图表
PDF	6	生成（使用CJK字体级联注册）、读取、合并、拆分、水印、光栅化为PNG
IMAGE	5	创建画布、读取元数据、处理管道（调整大小/裁剪/过滤/文本等）、格式转换、多图像合成（网格/水平/垂直）
BLENDER	3	Python脚本执行、场景结构查询、EEVEE/Cycles渲染
SVG	1	基于文本描述的矢量场景合成
图表	2	单幅图表+多子图仪表板（条形图/折线图/散点图/饼图/面积图/历史图/热图/雷达图/方框图/茎图/台阶图）
MATLAB	2	表达式求值，.m脚本执行（兼容GBK编码）
FFMPEG	6	媒体探测、转码、时间范围剪辑、帧截图、GIF生成、自定义执行
GIMP	2	脚本Fu批处理（GIMP控制台无头），Python Fu脚本
INKSCAPE	2	执行INKSCAPE操作命令，SVG→PNG/PDF格式转换
FREECAD	2	FreeCADCmd脚本执行，带STEP导出的参数化形状建模
GODOT	3	GDScript项目执行、场景运行（具有超时弹性）、导出为可执行文件
UTILS	10	文件读/写/复制/移动/删除/列表/打开，shell执行，Python执行，系统信息

系统架构

┌─────────────────────────────────────────────────────┐
│                VS Code Copilot Agent                │
│             (LLM ↔ Tool Dispatcher)                 │
└──────────┬──────────────────────────┬───────────────┘
           │ stdio                    │ stdio / HTTP
           ▼                          ▼
┌─────────────────────┐  ┌──────────────────────────┐
│    omni-mcp         │  │   External MCP Services  │
│  (omni_mcp.py)      │  │  ┌─────────────────────┐ │
│                     │  │  │ playwright (npx)    │ │
│  54 tools across    │  │  ├─────────────────────┤ │
│  15 modules         │  │  │ github (HTTP API)   │ │
│                     │  │  ├─────────────────────┤ │
│  Office / Image /   │  │  │ blender-mcp (uvx)   │ │
│  Media / CAD /      │  │  ├─────────────────────┤ │
│  Chart / Utils      │  │  │ freecad-mcp (uvx)   │ │
│                     │  │  ├─────────────────────┤ │
│                     │  │  │ godot-mcp (npx)     │ │
│                     │  │  ├─────────────────────┤ │
│                     │  │  │ matlab (Go binary)  │ │
│                     │  │  └─────────────────────┘ │
└─────────────────────┘  └──────────────────────────┘
           │                          │
           ▼                          ▼
┌─────────────────────────────────────────────────────┐
│              Local Executables & Runtimes           │
│  Blender · MATLAB · FFmpeg · GIMP · Inkscape ·      │
│  FreeCAD · Godot · Python · Node.js                 │
└─────────────────────────────────────────────────────┘

调度流程：代理接收用户意图→ 选择工具→ 通过stdio/HTTP调用相应的MCP服务→ 服务委托给本地可执行文件→ 返回JSON结果或生成的工件。

详细设置指南

3.1环境准备

Python依赖关系

pip install mcp python-pptx python-docx openpyxl pymupdf Pillow matplotlib numpy reportlab

外部软件

下表列出了已完全验证的版本组合。并非所有模块都是必需的——未安装软件的模块将在调用时返回明确的“未找到”诊断。

软件	测试版本	目的	安装
搅拌机	4.x	3D场景脚本+渲染	blender.org
MATLAB	R2024b+	科学计算、信号处理、绘图	MathWorks官方安装程序
FFmpeg	7.x	视频转码、剪辑、GIF	`winget install FFmpeg` 或手动下载
GIMP	3.0.8	图像批处理	gimp.org （必须包括gimp控制台）
Inkscape	1.4.2	SVG编辑+格式转换	inkscape.org
FreeCAD	1.0+	参数化CAD建模	freecad.org
戈多	4.6.1	游戏项目执行+导出	godotengine.org
Node.js	18+	运行npx推出的外部MCP	nodejs.org
紫外线	0.4+	运行uvx启动的外部MCP	`pip install uv` 或 `winget install astral-sh.uv`

包管理器先决条件

外部MCP服务通过以下方式启动 npx （Node.js）或 uvx （紫外线）。首先验证可用性：

# Check Node.js / npm / npx
node -v          # Expected: v18.x or higher
npx --version    # Expected: 10.x or higher

# Check uv / uvx
uv --version     # Expected: 0.4.x or higher
uvx --version    # Expected: same (uvx is a uv subcommand)

如果 npx 不可用，请先安装Node.js。如果 uvx 不可用，请安装 uv 第一。

3.2 omni-mcp可执行路径配置

打开 omni_mcp.pyThe CONFIG 顶部的部分声明了每个外部可执行文件的路径常量。服务器使用 _find() 启动时自动搜索常用安装目录的功能，但建议手动验证：

# ========== CONFIG ==========
BLENDER  = r"D:\Blender\blender.exe"
MATLAB   = _find(r"C:\Program Files\MATLAB\*\bin\matlab.exe",
                 r"D:\MATLAB\*\bin\matlab.exe") or "matlab"
FFMPEG   = _find(r"C:\Users\*\...\*ffmpeg*\ffmpeg*.exe") or "ffmpeg"
GIMP     = _find(r"D:\GIMP*\bin\gimp-console-*.exe", ...) or "gimp"
INKSCAPE = _find(r"D:\Inkscape*\bin\inkscape.exe", ...) or "inkscape"
FREECAD  = _find(r"D:\FreeCAD*\bin\FreeCADCmd.exe", ...) or "FreeCADCmd"
GODOT    = _find(r"D:\Godot*\Godot*.exe", ...) or "godot"

重要：GIMP必须指向 gimp-console-*.exe，不 gimp-*.exe （GUI版本）。由于显示初始化，GUI构建会导致批处理模式超时。见测试报告中的缺陷D-02。

3.3外部MCP服务配置

注册了七项服务 mcp.json。每一项都记录在下面，包括其目的、启动机制、先决条件和验证方法。

3.3.1剧作家（浏览器自动化）

"playwright": {
  "command": "cmd",
  "args": ["/c", "npx", "@playwright/mcp@latest"],
  "type": "stdio"
}

目的：提供无头浏览器控件——页面导航、元素交互、屏幕截图、表单填充——用于web数据收集或UI自动化测试。
先决条件：已安装Node.js 18+。在第一次调用时，npx会自动下载 @playwright/mcp 包裹。
浏览器内核安装：首次使用前必须：
```
npx playwright install chromium
```
验证：呼叫 browser_navigate 使用任何URL的工具，并确认返回页面快照。

3.3.2 GitHub（存储库和问题管理）

"github": {
  "type": "http",
  "url": "https://api.githubcopilot.com/mcp/",
  "headers": {
    "Authorization": "Bearer ${env:GITHUB_TOKEN}"
  }
}

目的：提供GitHub存储库操作——问题读/写、PR创建和审核、文件内容检索、分支管理。
先决条件：需要有效的GitHub令牌。如果你用VS Code登录GitHub Copilot ${env:GITHUB_TOKEN} 变量是自动注入的，不需要手动设置环境变量。
验证：呼叫 get_me 用于检查经过身份验证的用户身份的工具。

3.3.3搅拌机MCP（实时3D场景控制）

"blender-mcp": {
  "command": "cmd",
  "args": ["/c", "uvx", "blender-mcp"],
  "type": "stdio"
}

目的：通过WebSocket连接到正在运行的Blender实例，用于实时场景查询、Python脚本注入和视口屏幕截图捕获。适用于交互式3D建模工作流程。
与omni-mcp的区别：omni-mcp blender_exec 在无头CLI模式下启动Blender进行批渲染；blender mcp连接到一个开放的blender GUI进行实时操作。
先决条件:
1. uv 已安装(uvx 是它的子命令）。
2. 这 搅拌机mcp插件 必须安装在Blender中：
  - 获取插件文件： pip download blender-mcp --no-deps -d . 并从中提取或克隆 GitHub 并定位 addon.py.
  - 在Blender中：编辑→ 偏好→ 附加组件→ 从磁盘安装→ 选择 addon.py.
  - 启用插件。“BlenderMCP”面板出现在3D视口侧栏中。点击 启动MCP服务器 启动WebSocket侦听器（默认端口9876）。
3. 在MCP服务器处于活动状态时保持Blender运行。
验证：呼叫 get_scene_info --它应该返回当前场景的对象列表、材质和元数据。

3.3.4 FreeCAD MCP（实时参数化CAD控制）

"freecad-mcp": {
  "command": "cmd",
  "args": ["/c", "uvx", "freecad-mcp"],
  "type": "stdio"
}

目的：通过RPC连接到正在运行的FreeCAD实例，用于实时文档创建、零件建模、视图捕获和STEP导出。
与omni-mcp的区别：omni-mcp freecad_exec 通过FreeCADCmd（无头CLI）运行脚本；freecad mcp保持与freecad GUI的实时RPC连接，用于具有即时视觉反馈的交互式建模。
先决条件:
1. uv 安装。
2. 这 freecad mcp服务器宏 必须安装在FreeCAD中：
  - 在FreeCAD中：宏→ 宏→ 创建一个名为的新宏 freecad_mcp_server.py.
  - 粘贴在中发布的服务器脚本 freecad mcp存储库.
  - 运行宏--FreeCAD将在上启动RPC侦听器 localhost:9875.
3. 在宏处于活动状态时保持FreeCAD运行。
验证：呼叫 list_documents 或 create_document 并确认有效响应。

3.3.5 Godot MCP（游戏引擎项目操作）

"godot-mcp": {
  "command": "cmd",
  "args": ["/c", "npx", "-y", "@satelliteoflove/godot-mcp"],
  "type": "stdio"
}

目的：为游戏开发工作流提供Godot项目场景管理、节点操作和GDScript执行。
先决条件:
1. 已安装Node.js 18+。
2. 已安装Godot 4.x（GDScript 2.0语法要求版本≥4.0）。
3. 首次调用自动安装 @satelliteoflove/godot-mcp 通过npx(-y 跳过确认）。
备注：导出到可执行文件需要在Godot编辑器（编辑器）中预下载平台导出模板→ 管理导出模板）。
验证：调用现有Godot项目目录中的场景/节点查询工具。

3.3.6 MATLAB官方MCP（由MathWorks提供）

"matlab": {
  "command": "D:\\MCP\\matlab-mcp-core-server.exe",
  "args": [
    "--initial-working-folder=D:\\MCP\\mcp_test\\outputs",
    "--matlab-display-mode=nodesktop",
    "--disable-telemetry=true"
  ],
  "type": "stdio"
}

仓库: matlab/matlab-mcp核心服务器 (170★,Go，由MathWorks正式维护）
目的：启动/退出MATLAB，执行代码，运行 .m 文件、运行测试、静态代码分析（检查代码）、检测已安装的工具箱。
与omni-mcp的区别：omni-mcp matlab_eval/matlab_exec 呼叫 matlab -batch 每次通过CLI冷启动MATLAB进程；官方MCP保持 持续MATLAB会话 具有可变持久性和 nodesktop 无头模式，显著提高了执行效率。
先决条件:
1. MATLAB R2020b+已安装 matlab 在系统PATH中。
2. 下载 v0.5.0 Windows二进制文件到 D:\MCP\matlab-mcp-core-server.exe.
验证：呼叫 detect_matlab_toolboxes 或 evaluate_matlab_code （代码： disp('hello')).

3.3.7 omni-mcp（自定义工具服务器）

"omni-mcp": {
  "command": "python",
  "args": ["d:\\MCP\\omni_mcp.py"],
  "type": "stdio"
}

目的：该项目的核心——提供所有54个自定义工具（见上面的能力矩阵）。
先决条件：安装了所有pip依赖项的Python 3.10+。
验证：呼叫 system_info --它应该返回每个外部工具的操作系统详细信息、内存、Python版本和可用性状态。

3.4完整的mcp.json参考

{
  "servers": {
    "playwright": {
      "command": "cmd",
      "args": ["/c", "npx", "@playwright/mcp@latest"],
      "type": "stdio"
    },
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer ${env:GITHUB_TOKEN}"
      }
    },
    "blender-mcp": {
      "command": "cmd",
      "args": ["/c", "uvx", "blender-mcp"],
      "type": "stdio"
    },
    "freecad-mcp": {
      "command": "cmd",
      "args": ["/c", "uvx", "freecad-mcp"],
      "type": "stdio"
    },
    "godot-mcp": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@satelliteoflove/godot-mcp"],
      "type": "stdio"
    },
    "omni-mcp": {
      "command": "python",
      "args": ["d:\\MCP\\omni_mcp.py"],
      "type": "stdio"
    },
    "matlab": {
      "command": "D:\\MCP\\matlab-mcp-core-server.exe",
      "args": [
        "--initial-working-folder=D:\\MCP\\mcp_test\\outputs",
        "--matlab-display-mode=nodesktop",
        "--disable-telemetry=true"
      ],
      "type": "stdio"
    }
  },
  "inputs": []
}

3.5烟雾测试（推荐增量顺序）

配置后，按以下顺序验证依赖链：

步骤	工具调用	验证目标
1	`system_info`	omni-mcp启动+外部刀具路径检测
2	`file_write` → `file_read`	基本文件I/O，工作目录可写
3	`xlsx_create` → `xlsx_read`	办公文档生成管道
4	`ffmpeg_info`	多媒体工具链可用性
5	`img_create` → `img_info`	图像处理流水线
6	`blender_render` 或 `get_scene_info` （混合器mcp）	3D渲染管道
7	`matlab_eval` （omni-mcp）	科学计算管道（CLI模式）
8	`evaluate_matlab_code` （matlab官方MCP）	matlab持久会话模式
9	`gimp_exec`	GIMP批处理流水线

一旦烟雾测试通过，参考 mcp_test/ 用于全面回归测试的输入和日志。

3.6参考测试资产

资源	路径	描述
试验报告	`mcp_test/FINAL_REPORT.md`	完整的48个工具测试记录，包括11个缺陷的根本原因分析
执行日志	`mcp_test/logs/run_log.md`	按时间顺序排列的每个工具调用日志
测试输入	`mcp_test/inputs/`	JSON数据、压缩参数和其他预设输入
测试工件	`mcp_test/outputs/`	所有生成的文件（PPTX/DOCX/PDF/PNG/STEP/EXE等）

已知限制和技术债务

4.1刀具深度不均匀

虽然覆盖范围很广，但一些工具是在“共同路径优先”的基础上实现的。高级格式控制（例如PPTX主幻灯片定制、PDF表单字段操作）或特定于行业的工作流不完全支持。

4.2参数约定不一致

一些接口（例如。， xlsx_create)需要嵌套JSON结构，如 writes: [{"range":"A1:G18","values":[...]}]，而另一些则使用平面标量参数。这种不一致性增加了调用者学习成本，并增加了无声参数组装错误的概率。在测试过程中，由于格式不匹配导致多次失败，没有产生错误消息。

4.3粗粒度验证和错误语义

目前，大多数工具都依赖于通用异常转发，而没有统一的错误代码系统、字段级验证或结构化诊断上下文。例如，将不正确的内容格式传递给 pdf_create 生成空白PDF，而不是错误消息。

4.4严重的外部依赖性和环境敏感性

Blender、GIMP、FreeCAD和Godot的行为因版本、插件状态和操作系统区域设置而异。相同的配置可以在不同的机器上产生不同的结果——例如，MATLAB在中文Windows上输出GBK编码，GIMP 3.0更改了其批处理模式调用语法。在测试中记录的11个缺陷中，有7个与这种环境耦合有关。

4.5单文件架构可扩展性

omni_mcp.py 将所有54个工具、配置常量和辅助函数集中在大约1750行中。虽然这支持快速原型制作，但代码导航、多贡献者协作和单元测试隔离成本将随着工具数量的增长而增加。

4.6有限的跨平台支持

路径常数、进程创建标志(CREATE_NO_WINDOW)，编码处理是围绕Windows假设构建的。Linux和macOS开箱即用的兼容性需要一个专用的抽象层。

4.7基本文档样式

生成的PPTX、DOCX和PDF文件使用基本的系统字体（Calibri、Arial、SimSun）和简单的布局。没有Office主题引擎——颜色、排版和元素定位都是功能性的，但尚未准备好发布。 将OmniMCP视为快速原型制作工具：快速生成结构和内容，然后在本机编辑器（PowerPoint、Word、Acrobat等）中优化样式。需要自定义字体或品牌的用户可以在中修改字体/颜色常数 omni_mcp.py 直接。

发展路线图

优先级	方向	行动项目
P0	模块化重组	拆分为域子包(`office/`, `media/`, `cad/`, `utils/`)具有独立的工具注册
P0	统一参数架构	采用Pydantic进行强类型验证和自动生成文档
P1	标准化误差模型	定义统一的错误代码（工具不可用/参数无效/运行时异常）+结构化诊断
P1	异步作业模型	引入任务队列和进度查询API，用于呈现、转码和导出操作
P2	自动化测试	构建分层测试：单元+工具冒烟+端到端回归
P2	插件可扩展性	从硬编码注册演变为接受外部包的插件注册
P3	跨平台适应	抽象路径解析和过程管理；测试Linux/macOS兼容性
P3	文件硬化	为每个模块提供最少的可运行示例、参数模板和故障排除手册

存储库结构

MCP/
├── .vscode/
│   └── mcp.json                  # MCP service registration hub
├── omni_mcp.py                   # Custom MCP server (54 tools, single-file implementation)
├── render_formulas.py            # LaTeX formula rendering script
├── replace_formulas.py           # PPT formula replacement script
├── MCP_Academic_Ultimate.pptx    # Academic presentation PPT
├── assets/
│   ├── formulas/                 # Rendered formula images
│   ├── charts/                   # Chart assets
│   └── diagrams/                 # Architecture diagrams
├── mcp_test/
│   ├── FINAL_REPORT.md           # Test report (48 tools + 11 defect analyses)
│   ├── logs/
│   │   └── run_log.md            # Per-tool execution log
│   ├── inputs/                   # Test input data
│   └── outputs/                  # Test artifacts (PPTX/DOCX/PDF/PNG/STEP/EXE, etc.)
│       └── godot_game_pro/       # Complete Godot Roguelite game project
└── CyberMoto/                    # Auxiliary project

许可证

该项目根据 MIT许可证.欢迎捐款。