Clouduxmcp

🚀 MediaCentral AI 助手

MediaCentral AI 助手是一款由人工智能驱动的工具，专为 Avid MediaCentral CTMS（连接工具包媒体服务）打造，配备直观的 React 用户界面。该应用程序支持通过自然语言与 MediaCentral 的 PAM（生产资产管理）和 MAM（媒体资产管理）系统进行交互。

✨ 主要特性

• 🤖 人工智能聊天界面：支持使用自然语言查询与 MediaCentral 系统进行交互。
• 🔍 系统浏览：可通过交互式树状导航，浏览文件夹、项目和资产。
• 🔐 OAuth2 认证：与 MediaCentral 进行安全认证。
• 📊 系统发现：自动检测 PAM/MAM 系统。
• 🎯 MCP 协议：用于集成 AI 工具的模型上下文协议。
• ⚡ 实时更新：提供实时反馈和交互式用户界面。

🔧 技术细节

架构

mcpserver/
├── avidmcpserver/          # 后端 FastAPI 服务器
│   ├── main.py             # REST API 端点
│   ├── mcp_server.py       # MCP 协议实现
│   ├── mcp_client.py       # OpenAI 集成
│   ├── auth_service.py     # OAuth2 认证
│   ├── ctms_service.py     # CTMS API 交互
│   ├── models.py           # 数据模型
│   ├── config.py           # 配置
│   ├── requirements.txt    # Python 依赖项
│   └── .env                # 环境变量
│
└── avidmcpui/              # 前端 React 应用程序
    ├── src/
    │   ├── components/
    │   │   ├── AIChatbot.jsx       # AI 聊天界面
    │   │   ├── AIChatbot.css       # 聊天样式
    │   │   ├── Authenticate.jsx    # 登录组件
    │   │   └── Authenticate.css    # 登录样式
    │   ├── App.jsx                 # 主应用组件
    │   └── main.jsx                # 入口点
    ├── package.json                # NPM 依赖项
    └── vite.config.js              # Vite 配置

项目结构

后端文件

• main.py：FastAPI 应用程序，包含 REST 端点和 CORS 中间件。
• mcp_server.py：MCP 协议的实现和工具定义。
• mcp_client.py：集成 OpenAI GPT - 4 并实现函数调用。
• auth_service.py：负责 OAuth2 认证和令牌管理。
• ctms_service.py：处理 CTMS API 交互和系统浏览。
• models.py：使用 Pydantic 数据模型进行验证。
• config.py：环境配置。

前端文件

• AIChatbot.jsx：主聊天界面，支持 Markdown 渲染。
• Authenticate.jsx：登录表单组件。
• BrowseTree：用于系统导航的交互式树状组件。
• App.jsx：路由管理和主布局。

所使用的技术

后端

• FastAPI：现代异步 Web 框架。
• Uvicorn：ASGI 服务器。
• httpx：异步 HTTP 客户端。
• OpenAI：集成 GPT - 4。
• Pydantic：数据验证。

前端

• React 19：用户界面库。
• Vite：构建工具和开发服务器。
• react - markdown：Markdown 渲染。

📦 安装指南

1. 克隆仓库

git clone https://github.com/pandiaaman/CloudUxMCP.git
cd mcpserver

2. 后端设置

创建虚拟环境（如果不存在）

# 导航到后端目录
cd avidmcpserver

# 创建虚拟环境
python -m venv .venv

# 激活虚拟环境
.\.venv\Scripts\Activate.ps1

# 安装依赖项
pip install -r requirements.txt

配置环境变量

在 avidmcpserver 目录下创建一个 .env 文件：

# MediaCentral 配置
MCS_HOST=your-mediacentral-host.com
MCS_USERNAME=your-username
MCS_PASSWORD=your-password

# OpenAI 配置
OPENAI_API_KEY=sk-proj-your-openai-api-key

# 服务器配置（可选）
HOST=0.0.0.0
PORT=8000

注意：可以将 .env.example 复制为 .env 并更新其中的凭证：

cp .env.example .env

3. 前端设置

# 导航到前端目录
cd ..\avidmcpui

# 安装依赖项
npm install

🚀 快速开始

运行应用程序

选项 1：分别启动两个服务

终端 1 - 后端服务器

# 导航到后端目录
cd avidmcpserver

# 激活虚拟环境（如果尚未激活）
.\.venv\Scripts\Activate.ps1

# 启动 FastAPI 服务器并开启自动重载
uvicorn main:app --reload --host 0.0.0.0 --port 8000

后端 API 将在以下地址可用：

• API：http://localhost:8000
• API 文档：http://localhost:8000/docs
• 健康检查：http://localhost:8000/health

终端 2 - 前端服务器

# 导航到前端目录
cd avidmcpui

# 启动 Vite 开发服务器
npm run dev

前端用户界面将在以下地址可用：

• UI：http://localhost:5173

选项 2：快速启动脚本（Windows）

在根目录下创建一个 start.ps1 文件：

# 在后台启动后端
Start-Process powershell -ArgumentList "-NoExit", "-Command", "cd avidmcpserver; .\.venv\Scripts\Activate.ps1; uvicorn main:app --reload --host 0.0.0.0 --port 8000"

# 等待后端启动
Start-Sleep -Seconds 3

# 在后台启动前端
Start-Process powershell -ArgumentList "-NoExit", "-Command", "cd avidmcpui; npm run dev"

Write-Host "✅ 服务已启动！"
Write-Host "后端 API：http://localhost:8000"
Write-Host "前端 UI：http://localhost:5173"

运行脚本：

.\start.ps1

💻 使用示例

1. 认证

1. 在浏览器中打开 http://localhost:5173。
2. 输入你的 MediaCentral 凭证：
   • MCS 主机：你的 MediaCentral 主机 URL。
   • 用户名：你的用户名。
   • 密码：你的密码。
3. 点击“认证”。

2. 与 AI 助手聊天

认证成功后，你可以使用自然语言与 AI 进行交互：

示例查询：

• "Show me all connected systems"（显示所有连接的系统）
• "What PAM systems are available?"（有哪些 PAM 系统可用？）
• "Browse the AvidWG system"（浏览 AvidWG 系统）
• "Show me what's in the Projects folder"（显示项目文件夹中的内容）
• "List all MAM systems"（列出所有 MAM 系统）
• "Get service roots"（获取服务根目录）

3. 交互式系统浏览

AI 将以交互式树状结构显示系统：

• 📁 文件夹/项目：点击可深入浏览。
• 📄 资产：查看详细信息。
• 展开/折叠：使用 ▶/▼ 图标进行导航。

📚 详细文档

API 端点

认证

• POST /api/authenticate：与 MediaCentral 进行认证。
• GET /api/auth/status：检查认证状态。

聊天

• POST /api/chat：向 AI 助手发送查询。
• POST /api/chat/clear：清除对话历史。

系统

• GET /api/systems：获取所有连接的系统。
• GET /api/systems/pam：仅获取 PAM 系统。
• GET /api/systems/mam：仅获取 MAM 系统。

资源

• GET /api/resources：获取可用资源。
• GET /api/service - roots：获取服务根目录。

健康检查

• GET /health：服务器健康检查。
• GET /api/openai/status：OpenAI API 密钥状态。

配置

后端配置

编辑 avidmcpserver/.env 文件：

# 必需
MCS_HOST=mediacentral-host.com
MCS_USERNAME=username
MCS_PASSWORD=password
OPENAI_API_KEY=sk-proj-...

# 可选
HOST=0.0.0.0
PORT=8000
LOG_LEVEL=INFO

前端配置

前端会自动连接到 http://localhost:8000 的后端 API。若要更改此设置，请编辑 avidmcpui/src/components/AIChatbot.jsx 和 avidmcpui/src/components/Authenticate.jsx。

故障排除

后端问题

问题：未找到虚拟环境

# 先创建虚拟环境
cd avidmcpserver
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt

问题：OpenAI API 密钥错误

• 验证 .env 文件中的 API 密钥是否有效。
• 在 https://platform.openai.com/account/billing 检查余额。
• 在 https://platform.openai.com/api - keys 获取新的密钥。

问题：MediaCentral 认证失败

• 验证 .env 文件中的 MCS_HOST、MCS_USERNAME 和 MCS_PASSWORD。
• 检查与 MediaCentral 的网络连接。
• 确保 OAuth 端点可访问。

问题：模块导入错误

# 重新安装依赖项
pip install --force-reinstall -r requirements.txt

前端问题

问题：无法连接到后端

• 确保后端在 http://localhost:8000 上运行。
• 检查 curl http://localhost:8000/health 是否正常工作。
• 验证后端是否启用了 CORS。

问题：npm install 失败

# 清除缓存并重新安装
npm cache clean --force
rm -rf node_modules package-lock.json
npm install

问题：端口 5173 已被占用

# 杀死使用端口 5173 的进程
netstat -ano | findstr :5173
taskkill /PID <PID> /F

# 或者使用不同的端口
npm run dev -- --port 3000

常见问题

问题：未找到 "react - markdown"

cd avidmcpui
npm install react-markdown

问题：浏览器控制台显示 CORS 错误

• 后端会自动为 http://localhost:5173 启用 CORS。
• 检查 main.py 是否有正确的 CORS 中间件配置。

开发

后端开发

# 激活虚拟环境
cd avidmcpserver
.\.venv\Scripts\Activate.ps1

# 以自动重载模式运行（开发模式）
uvicorn main:app --reload --host 0.0.0.0 --port 8000

# 运行测试
python test_complete.py
python test_browse.py

前端开发

# 启动带有热重载的开发服务器
cd avidmcpui
npm run dev

# 为生产环境构建
npm run build

# 预览生产构建
npm run preview

📄 许可证

本项目为专有和保密项目。

支持

如有问题或疑问：

• 在 GitHub 上创建一个 issue。
• 联系开发团队。
• 查看 API 文档：http://localhost:8000/docs

致谢

• 感谢 Avid Technology 提供 MediaCentral CTMS API。
• 感谢 OpenAI 提供 GPT - 4 语言模型。
• 感谢 FastAPI 和 React 社区。