AVC MCP Client (Python)

Python client for AVC video enhancement MCP service.

Requirements

• Python >= 3.10
• httpx >= 0.27.0
• pydantic >= 2.0.0

Installation

pip install avc-mcp-client

Or with uv:

uv pip install avc-mcp-client

Quick Start

URL Video

from avc_mcp_client import AVCMCPClient, Resolution

# Initialize client
client = AVCMCPClient(
    base_url="http://192.168.0.7:8001",
    api_key="your-api-key"
)

# Sync video enhancement (blocks until complete)
result = client.enhance_video_sync(
    video_url="https://example.com/video.mp4",
    type="url",  # default
    resolution=Resolution.P720
)

if result.success:
    print(f"Enhanced video: {result.video_url}")

Local File

from avc_mcp_client import AVCMCPClient, VideoType

client = AVCMCPClient(
    base_url="http://192.168.0.7:8001",
    api_key="your-api-key"
)

# Local file enhancement
result = client.enhance_video_sync(
    video_url="/path/to/video.mp4",
    type=VideoType.LOCAL,  # or "local"
    resolution="720p"
)

if result.success:
    print(f"Enhanced video: {result.video_url}")

Async Client

import asyncio
from avc_mcp_client import AsyncAVCMCPClient

async def main():
    client = AsyncAVCMCPClient(
        base_url="http://192.168.0.7:8001",
        api_key="your-api-key"
    )

    # Start async enhancement
    task = await client.enhance_video_async(
        video_url="https://example.com/video.mp4",
        resolution="1080p"
    )
    print(f"Task ID: {task.task_id}")

    # Wait for completion
    final = await client.wait_for_task(task.task_id, timeout=600.0)
    if final.success:
        print(f"Enhanced video: {final.video_url}")

asyncio.run(main())

API Reference

AVCMCPClient

Sync client for MCP service.

Constructor

AVCMCPClient(
    base_url: str = "http://192.168.0.7:8001",
    api_key: str | None = None,
    timeout: float = 600.0,
    poll_interval: float = 5.0,
)

Methods

Method	Description
enhance_video_sync(video_url, resolution, type, timeout)	Enhance video synchronously
enhance_video_async(video_url, resolution, type)	Start async enhancement
get_task_status(task_id)	Query task status
wait_for_task(task_id, timeout, poll_interval)	Wait for task completion

AsyncAVCMCPClient

Async client for MCP service (same API, all methods are async).

Types

Resolution

from avc_mcp_client import Resolution

Resolution.P480   # "480p"
Resolution.P540   # "540p"
Resolution.P720   # "720p" (default)
Resolution.P1080  # "1080p"
Resolution.P2K    # "2k"

VideoType

from avc_mcp_client import VideoType

VideoType.URL    # "url" (default)
VideoType.LOCAL  # "local"

TaskStatus

from avc_mcp_client import TaskStatus

TaskStatus.WAIT       # Waiting to be processed
TaskStatus.START      # Task started
TaskStatus.PROCESSING # Currently processing
TaskStatus.COMPLETED  # Successfully completed
TaskStatus.FAILED     # Processing failed
TaskStatus.TIMEOUT    # Processing timed out

Result Types

EnhanceResult

Result of enhance_video_sync():

result.success      # bool - Whether operation succeeded
result.task_id      # str | None - Task ID
result.status       # TaskStatus | None - Current status
result.video_url    # str | None - Enhanced video URL (if completed)
result.message      # str | None - Status message
result.error        # str | None - Error message (if failed)

AsyncTaskResult

Result of enhance_video_async():

result.success      # bool - Whether task was created
result.task_id      # str | None - Task ID
result.status       # TaskStatus | None - Initial status
result.message      # str | None - Status message

TaskStatusResult

Result of get_task_status() and wait_for_task():

result.success      # bool - Whether query succeeded
result.task_id      # str | None - Task ID
result.status       # TaskStatus | None - Current status
result.video_url    # str | None - Enhanced video URL (if completed)
result.message      # str | None - Status message
result.error        # str | None - Error message (if failed)

Exceptions

Exception	Description
MCPClientError	Base exception
MCPConnectionError	Connection failed
MCPParseError	Response parsing failed
MCPToolError	Tool execution failed
MPCTimeoutError	Operation timed out
MCPAuthenticationError	Authentication failed
FileSizeExceededError	File size exceeds 100MB limit
FileNotFoundError	Local file not found

Error Handling

from avc_mcp_client import AVCMCPClient
from avc_mcp_client.exceptions import (
    MCPClientError,
    MCPConnectionError,
    MCPAuthenticationError,
    MPCTimeoutError,
    MCPToolError,
    FileSizeExceededError,
    FileNotFoundError,
)

client = AVCMCPClient(
    base_url="http://192.168.0.7:8001",
    api_key="your-api-key"
)

try:
    result = client.enhance_video_sync(
        video_url="/path/to/video.mp4",
        type="local"
    )
except FileNotFoundError as e:
    print(f"文件不存在: {e}")
except FileSizeExceededError as e:
    print(f"文件过大: {e}")
except MCPAuthenticationError as e:
    print(f"认证失败: {e}")
except MCPConnectionError as e:
    print(f"连接失败: {e}")
except MPCTimeoutError as e:
    print(f"操作超时: {e}")
except MCPToolError as e:
    print(f"工具错误: {e} (code: {e.code})")
except MCPClientError as e:
    print(f"客户端错误: {e}")

Development

# Install dev dependencies
uv pip install -e ".[dev]"

# Run tests
uv run pytest -v

# Run integration tests (requires MCP server)
uv run pytest -v -m integration

License

MIT