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

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

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