金大哥 - clouduxmcp MCP 详情

article

README

🚀 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. 认证

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

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 社区。