README.md

metadata

title: Multimodal MCP Conversation Viewer - With AI Agent Integration
emoji: 🗣️
colorFrom: blue
colorTo: purple
sdk: docker
app_file: app.py
pinned: false
short_description: Use AI Agent to view self build Multimodal MCP Conversations

Conversation Viewer (with page-agent AI)

This project extends mcp-conversation-viewer-modern with page-agent for AI-powered browser automation.

A standalone web application for viewing exported conversation history JSON files and displaying related multimedia content.

Features

• 📁 Conversation List: Display all exported conversation history files
• 🔍 Conversation Details: Complete display of conversation content, including message flow and attachments
• 🖼️ Multimedia Display: Direct playback and viewing of images, videos, and audio
• 📊 Statistics: Show message count, user/AI message ratio, etc.
• 🔄 Real-time Updates: Automatically detect new files and refresh the list
• 📱 Responsive Design: Adapted for desktop and mobile devices

page-agent AI Integration

This project includes page-agent for AI-powered browser automation. Users can control the web interface with natural language commands.

Related Documentation

For detailed integration information, see: PAGE-AGENT-INTEGRATION.md

This includes:

• Model testing results and API configuration
• Source code modification details
• Limitations and solution options

Docker Usage with page-agent

When running with Docker, you need to set the API key via environment variable. Default port is 7860:

# Build and run with API key
docker build -t conversation-viewer .
docker run -d -p 7860:7860 -e OPENCODE_API_KEY=your-api-key -e PORT=7860 conversation-viewer

Or using docker-compose:

version: '3.8'
services:
  conversation-viewer:
    build: .
    ports:
      - "7860:7860"
    environment:
      - PORT=7860
      - OPENCODE_API_KEY=sk-your-api-key-here
    volumes:
      - ./hist:/app/hist
      - ./data/files:/app/data/files

Note:

• Without setting OPENCODE_API_KEY, the page-agent will not be loaded (conditional loading based on API key presence)
• The default port in Dockerfile is 7860 (Hugging Face Spaces standard)

Directory Structure

conversation-viewer/
├── app.py                    # FastAPI main application
├── requirements.txt          # Python dependencies
├── start_english.bat        # Windows startup script (English)
├── README.md                # Documentation
├── test_port.py             # Port testing utility
├── uv.lock                  # uv dependency lock file
├── .venv/                   # Python virtual environment
├── data/                    # Data directory
│   └── files/              # Multimedia files (to be linked)
├── hist/                    # Conversation history JSON files
├── static/                  # Static files (CSS/JS) - currently empty
└── templates/               # HTML templates
    ├── index.html          # Home page template
    └── conversation.html   # Conversation details template

Quick Start

Method 1: Using uv (Recommended)

uv is a fast Python package manager and resolver that provides better dependency management.

1. Install uv (if not already installed)

# Windows
pip install uv

# Or use other installation methods, refer to: https://github.com/astral-sh/uv

2. Start the service

# Windows - double click start_english.bat
# Or run from command line:
start_english.bat

# The script will automatically:
# 1. Check if uv is installed
# 2. Create virtual environment (.venv) if not exists
# 3. Install dependencies
# 4. Start the service

Method 2: Using traditional method

1. Install dependencies

pip install -r requirements.txt

2. Start the service

# Directly run the application
python app.py --port 9051

3. Prepare Data

There are two ways to prepare data:

Method A: Create symbolic link (Recommended)

# Execute in conversation-viewer directory
mklink /J data\files ..\..\data\files

Method B: Copy files

# Copy multimedia files
copy ..\..\data\files\* data\files\

# Copy conversation history files to hist directory
copy *.json hist\

4. Access the Application

Open browser and visit: http://localhost:9051

Note: Default port is 9051 (greater than 9050). To change the port:

python app.py --port 9060  # Use port 9060

Usage Instructions

Export Conversation History

1. In the application, click the "⬇️ Download" button below AI reply messages
2. The system will automatically download JSON files to the browser's default download directory
3. Copy the downloaded JSON files to the conversation-viewer/hist/ directory

View Conversations

1. Visit http://localhost:9051 to view the conversation list
2. Click the "View Details" button to enter the conversation details page
3. On the details page you can:
   • View complete message flow
   • Play videos and audio
   • View images
   • Download attachment files

File Access

• Multimedia files accessed via /files/{file_id}
• Conversation history accessed via /conversation/{filename}
• API endpoints: /api/conversations and /api/conversation/{filename}

Configuration

Changing Port

You can change the port via command line arguments:

# Start with specified port
python app.py --port 9060

# Or modify port parameters in the startup script

You can also modify the default port in the code (edit app.py):

parser.add_argument("--port", type=int, default=9051, help="Service port number (default: 9051)")

Changing File Paths

Edit app.py and modify the following configuration:

BASE_DIR = Path(__file__).parent
FILES_DIR = BASE_DIR / "data" / "files"  # Multimedia files directory
HIST_DIR = BASE_DIR / "hist"             # Conversation history directory

API Endpoints

Get Conversation List

GET /api/conversations

Response example:

{
  "success": true,
  "data": [
    {
      "filename": "conversation_20240115_103000.json",
      "metadata": {...},
      "stats": {...},
      "preview": "User's first message...",
      "export_time": "2024-01-15T10:30:00",
      "size_kb": 45.2
    }
  ],
  "count": 1
}

Get Conversation Details

GET /api/conversation/{filename}

Get Multimedia Files

GET /files/{file_id}

Notes

1. File Security: The application checks file paths to prevent directory traversal attacks
2. File Types: Supports common image, video, and audio formats
3. Encoding Issues: Ensure JSON files use UTF-8 encoding
4. Performance Considerations: Large conversation files (>10MB) may affect loading speed

Troubleshooting

Issue 1: Images/Videos not displaying

• Check if files exist in data/files/ directory
• Check file permissions
• Check if file URLs are correct

Issue 2: Conversation list is empty

• Check if there are JSON files in hist/ directory
• Check if JSON file format is correct
• Check console error messages

Issue 3: Service fails to start

• Check Python version (requires Python 3.7+)
• Check if dependencies are installed
• Check if port 9051 is occupied, try another port:

  python app.py --port 9060
  

Issue 4: start_english.bat not working

• Ensure file encoding is ASCII/ANSI (not UTF-8 with BOM)
• Check if uv is installed: where uv
• Run from command line to see error messages

Development

Adding New Features

1. Add new route handler functions in app.py
2. Add or modify HTML templates in templates/
3. Add CSS/JS files in static/

Customizing Styles

Modify CSS styles in templates/, or add custom CSS files to static/css/

Extending Multimedia Support

Add new file type support in the media_types dictionary in app.py.

License

MIT License