Metadata-Version: 2.4
Name: avc-mcp-client
Version: 0.1.0
Summary: MCP client for AVC video enhancement service
Project-URL: Homepage, https://github.com/avc/avc-mcp-client
Project-URL: Documentation, https://github.com/avc/avc-mcp-client#readme
Project-URL: Repository, https://github.com/avc/avc-mcp-client
Author: AVC Team
License-Expression: MIT
Keywords: ai,enhancement,mcp,video
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.3.0; extra == 'dev'
Description-Content-Type: text/markdown

# 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

```bash
pip install avc-mcp-client
```

Or with uv:

```bash
uv pip install avc-mcp-client
```

## Quick Start

### URL Video

```python
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

```python
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

```python
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

```python
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

```python
from avc_mcp_client import Resolution

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

#### VideoType

```python
from avc_mcp_client import VideoType

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

#### TaskStatus

```python
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()`:

```python
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()`:

```python
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()`:

```python
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

```python
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

```bash
# 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
