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