Metadata-Version: 2.3
Name: bookbridge-mcp
Version: 1.0.0
Summary: A powerful Model Context Protocol (MCP) server for Chinese-to-English book translation and document processing
License: MIT
Keywords: mcp,translation,document-processing,chinese-english,fastmcp
Author: Polly2014
Author-email: your.email@example.com
Requires-Python: >=3.10,<4.0
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
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Text Processing :: Linguistic
Requires-Dist: aiofiles (>=23.0.0)
Requires-Dist: beautifulsoup4 (>=4.12.0)
Requires-Dist: fastmcp (>=2.0.0)
Requires-Dist: markdown (>=3.5.0)
Requires-Dist: pydantic (>=2.5.0)
Requires-Dist: python-docx (>=1.1.0)
Requires-Dist: python-dotenv (>=1.0.0)
Project-URL: Documentation, https://github.com/Polly2014/BookBridge-MCP-Server#readme
Project-URL: Homepage, https://github.com/Polly2014/BookBridge-MCP-Server
Project-URL: Repository, https://github.com/Polly2014/BookBridge-MCP-Server
Description-Content-Type: text/markdown

# BookBridge-MCP

[![GitHub](https://img.shields.io/badge/GitHub-BookBridge--MCP--Server-blue?logo=github)](https://github.com/Polly2014/BookBridge-MCP-Server)
[![Python](https://img.shields.io/badge/Python-3.10+-blue?logo=python)](https://www.python.org/)
[![Poetry](https://img.shields.io/badge/Poetry-Dependency%20Management-blue?logo=poetry)](https://python-poetry.org/)
[![FastMCP](https://img.shields.io/badge/FastMCP-2.12.2+-green)](https://github.com/pydantic/fastmcp)
[![uv](https://img.shields.io/badge/uv-compatible-green?logo=python)](https://docs.astral.sh/uv/)

> 🚀 **Now with uvx support!** Run directly from GitHub with zero installation: 
> ```bash
> uvx --from git+https://github.com/Polly2014/BookBridge-MCP-Server bookbridge-server
> ```

A powerful Model Context Protocol (MCP) server for Chinese-to-English book translation and document processing, built with FastMCP framework.

## 🌉 Overview

BookBridge-MCP provides a comprehensive solution for translating Chinese books and documents to English while preserving formatting and structure. The server follows a **client-side LLM architecture**, where the MCP server handles document processing and provides translation resources, while LLM interactions are performed on the client side.

## ✨ Key Features

- **Zero Installation Required**: Run directly from GitHub using `uvx`
- **Document Processing**: Convert between Word (.docx) and Markdown formats
- **Smart Resource Management**: Organize and track translation projects
- **Professional Translation Prompts**: Specialized prompts for different content types
- **Client-Side LLM Architecture**: Clean separation between document processing and AI inference
- **Batch Processing**: Handle multiple documents efficiently
- **Format Preservation**: Maintain original document structure and formatting

## 🏗️ Architecture

```
┌─────────────────┐    MCP Protocol    ┌─────────────────┐
│                 │◄──────────────────►│                 │
│   MCP Client    │                    │  BookBridge     │
│                 │                    │  MCP Server     │
│  + LLM Calls    │                    │                 │
│  + UI/Logic     │                    │  + Tools        │
│                 │                    │  + Resources    │
│                 │                    │  + Prompts      │
└─────────────────┘                    └─────────────────┘
         │                                       │
         │                                       │
         v                                       v
┌─────────────────┐                    ┌─────────────────┐
│   OpenAI API    │                    │   Document      │
│   (Client-side) │                    │   Processing    │
│                 │                    │   (Server-side) │
└─────────────────┘                    └─────────────────┘
```

## ⚡ Quick Start

### Method 1: Using uvx (Recommended - Run Directly from GitHub)

**No installation needed!** Run directly from GitHub using `uvx`:

```bash
# Run directly from GitHub
uvx --from git+https://github.com/Polly2014/BookBridge-MCP-Server bookbridge-server
```

**Update your MCP configuration** (`mcp.json`):
```json
{
  "servers": {
    "Book-Bridge-MCP": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/Polly2014/BookBridge-MCP-Server",
        "bookbridge-server"
      ],
      "type": "stdio"
    }
  }
}
```

### Method 2: Local Development Installation

#### 1. Install Dependencies
```bash
# Clone the repository
git clone https://github.com/Polly2014/BookBridge-MCP-Server.git
cd BookBridge-MCP-Server

# Automated setup (recommended)
python setup_poetry.py

# Or if Poetry is already installed
poetry install
```

#### 2. Test Environment  
```bash
# Verify installation
poetry run python test_environment.py

# Test MCP functionality
poetry run python test_simple.py
```

#### 3. Start Server
```bash
# Start the MCP server
poetry run python start.py
```

#### 4. Run Client Example
```bash
# Test with client example
poetry run python examples/client_example.py
```

#### 5. Development Commands
```bash
# Run tests: poetry run pytest
# Format code: poetry run black .
# Type checking: poetry run mypy src/
# All checks: make check (or make.bat check on Windows)
```

### Method 3: Using npx-like approach with uv

If you prefer an npx-like experience, you can also use:

```bash
# Run directly with uv (if published to PyPI)
uvx bookbridge-mcp
```

---

## 🚀 Detailed Installation

### 1. Prerequisites

- Python 3.10 or higher
- Poetry (recommended) or pip

### 2. Installation

#### Option A: Using Poetry (Recommended)

```bash
git clone https://github.com/your-repo/BookBridge-MCP.git
cd BookBridge-MCP

# Automated setup (installs Poetry if needed)
python setup_poetry.py

# Or manual setup if Poetry is already installed
poetry install --with dev --with client
```

#### Option B: Using pip

```bash
git clone https://github.com/your-repo/BookBridge-MCP.git
cd BookBridge-MCP
pip install -r requirements.txt
```

### 3. Start the MCP Server

#### Using Poetry:
```bash
poetry run python start.py
# or
poetry run bookbridge-server
# or using make commands
make run              # Unix/Linux/Mac
make.bat run          # Windows
```

#### Using pip:
```bash
python start.py
```

The server will start and listen for MCP connections on the configured port.

### 3. Client-Side Integration

The MCP server provides tools, resources, and prompts. Your client application handles the LLM interactions:

```python
from examples.client_example import BookBridgeClient

# Initialize client with your OpenAI API key
client = BookBridgeClient(api_key="your_openai_api_key")

# Translate a document
result = await client.translate_document(
    file_path="./my_chinese_book.docx",
    content_type="academic"  # or "general", "technical", "creative"
)

# Save the translation
output_path = await client.save_translation(
    result, 
    "./output/translated_book.md"
)
```

## 🛠️ MCP Server Capabilities

### Tools

1. **`process_document`** - Convert documents between Word and Markdown formats
2. **`list_documents`** - List and manage documents in the project
3. **`get_document_info`** - Get detailed information about a specific document
4. **`create_translation_project`** - Set up new translation projects
5. **`get_translation_metrics`** - Calculate translation quality metrics

### Resources

- **Document Registry** - Track all processed documents
- **Project Files** - Access source and output documents
- **Translation History** - View previous translations

### Prompts

- **General Translation** - For everyday content
- **Academic Translation** - For scholarly and research texts
- **Technical Translation** - For documentation and manuals
- **Creative Translation** - For literary and creative works

## 📁 Project Structure

```
BookBridge-MCP/
├── server.py                 # Main MCP server
├── start.py                  # Server startup script
├── requirements.txt          # Dependencies
├── config.env               # Configuration
├── src/
│   ├── document_processor.py # Document conversion
│   ├── resource_manager.py   # File and project management
│   ├── prompts.py            # Translation prompts
│   └── translator.py         # Translation utilities
├── examples/
│   └── client_example.py     # Client implementation example
├── input_documents/          # Source documents
├── output_documents/         # Translated documents
└── temp_documents/           # Temporary files
```

## 🔧 Configuration

### MCP Client Configuration

You can configure your MCP client in three ways:

#### Option 1: Using uvx with GitHub (Recommended)

Edit your `mcp.json` file:

```json
{
  "servers": {
    "Book-Bridge-MCP": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/Polly2014/BookBridge-MCP-Server",
        "bookbridge-server"
      ],
      "type": "stdio"
    }
  }
}
```

**Advantages:**
- ✅ No local installation required
- ✅ Always runs the latest version from GitHub
- ✅ Automatic dependency management via uv
- ✅ Clean and simple configuration

#### Option 2: Using Local Installation

```json
{
  "servers": {
    "Book-Bridge-MCP": {
      "command": "python",
      "args": [
        "D:\\path\\to\\BookBridge-MCP\\server.py"
      ],
      "cwd": "D:\\path\\to\\BookBridge-MCP",
      "type": "stdio"
    }
  }
}
```

#### Option 3: Using npx-like syntax (if published to PyPI)

```json
{
  "servers": {
    "Book-Bridge-MCP": {
      "command": "uvx",
      "args": ["bookbridge-mcp"],
      "type": "stdio"
    }
  }
}
```

### Server Configuration

Edit `config.env` to customize settings:

```env
# Document Processing Settings
INPUT_DIR=./input_documents
OUTPUT_DIR=./output_documents
TEMP_DIR=./temp_documents

# Translation Settings (for client reference)
SOURCE_LANGUAGE=chinese
TARGET_LANGUAGE=english

# MCP Server Settings
SERVER_NAME=BookBridge-MCP
SERVER_VERSION=1.0.0
```

## �️ Development Workflow

### Using Poetry (Recommended)

Poetry provides better dependency management and development workflow:

```bash
# Complete development setup
poetry install --with dev --with client
poetry run pre-commit install

# Development commands using Poetry
poetry run python start.py          # Start server
poetry run pytest                   # Run tests  
poetry run pytest --cov=src         # Tests with coverage
poetry run black .                  # Format code
poetry run isort .                  # Sort imports
poetry run flake8 src/              # Lint code
poetry run mypy src/                # Type checking
```

### Using Make Commands

For convenience, use the provided Makefile (Unix/Linux/Mac) or make.bat (Windows):

```bash
# Unix/Linux/Mac
make dev-setup      # Complete development setup
make run            # Start server
make test           # Run tests
make format         # Format code
make lint           # Lint code
make type-check     # Type checking
make check          # Run all checks
make clean          # Clean temporary files

# Windows
make.bat dev-setup  # Complete development setup
make.bat run        # Start server
make.bat test       # Run tests
make.bat format     # Format code
make.bat lint       # Lint code
make.bat type-check # Type checking
make.bat check      # Run all checks
make.bat clean      # Clean temporary files
```

### Package Management

```bash
# Add new dependency
poetry add package_name

# Add development dependency
poetry add --group dev package_name

# Add client dependency (optional for client usage)
poetry add --group client package_name

# Update dependencies
poetry update

# Show installed packages
poetry show

# Environment information
poetry env info
```

## �💡 Usage Examples

### Basic Document Translation

```python
# Process and translate a Word document
result = await client.translate_document(
    file_path="./books/chinese_novel.docx",
    content_type="creative"
)

print(f"Translated {result['summary']['original_words']} words")
print(f"Used {result['summary']['token_usage']} tokens")
```

### Batch Processing

```python
# Process multiple documents
documents = ["doc1.docx", "doc2.md", "doc3.docx"]

for doc in documents:
    result = await client.translate_document(doc, "academic")
    await client.save_translation(result, f"./output/{doc}_translated.md")
```

### Custom Content Types

You can request specific translation prompts from the server:

```python
# Get specialized prompt for technical content
prompt = await client.get_translation_prompt("technical")

# Use prompt for custom translation
translation = await client.translate_content(
    content="技术文档内容...",
    content_type="technical"
)
```

## 🎯 Client-Side LLM Benefits

1. **Flexibility**: Clients can use any LLM provider or model
2. **Security**: API keys stay on the client side
3. **Scalability**: Server focuses on document processing
4. **Customization**: Clients can customize translation parameters
5. **Cost Control**: Clients manage their own LLM usage

## 📊 Translation Quality Features

- **Smart Chunking**: Preserve document structure when splitting large texts
- **Format Preservation**: Maintain headers, lists, and emphasis
- **Metrics Calculation**: Analyze translation quality and completeness
- **Content-Type Optimization**: Specialized prompts for different text types

## 🧪 Testing

### Running Tests

Using Poetry:

```bash
# Run all tests
poetry run pytest

# Run tests with coverage
poetry run pytest --cov=src --cov-report=html --cov-report=term

# Run specific test file
poetry run pytest tests/test_document_processor.py

# Run tests in verbose mode
poetry run pytest -v

# Quick test (stop on first failure)
poetry run pytest -x
```

Using Make commands:

```bash
# Unix/Linux/Mac
make test
make test-coverage
make quick-test

# Windows  
make.bat test
make.bat test-coverage
make.bat quick-test
```

### Running Examples

Test the client example:

```bash
# Using Poetry
poetry run python examples/client_example.py

# Using Make
make client-example        # Unix/Linux/Mac
make.bat client-example    # Windows
```

### Development Testing

```bash
# Run architecture tests
poetry run python test_architecture.py

# Test individual components
poetry run python test_components.py
```

## 🤝 Contributing

### Development Setup

1. Fork the repository
2. Clone your fork:
   ```bash
   git clone https://github.com/your-username/BookBridge-MCP.git
   cd BookBridge-MCP
   ```
3. Set up development environment:
   ```bash
   # Complete setup with Poetry
   make dev-setup           # Unix/Linux/Mac
   make.bat dev-setup       # Windows
   
   # Or manually
   poetry install --with dev --with client
   poetry run pre-commit install
   ```

### Development Workflow

1. Create a feature branch: `git checkout -b feature/your-feature`
2. Make your changes
3. Run quality checks:
   ```bash
   make check              # Unix/Linux/Mac
   make.bat check          # Windows
   ```
4. Add tests for new functionality
5. Commit your changes: `git commit -m "Add your feature"`
6. Push to your fork: `git push origin feature/your-feature`
7. Submit a pull request

### Code Quality

This project uses:
- **Black** for code formatting
- **isort** for import sorting
- **flake8** for linting
- **mypy** for type checking
- **pytest** for testing
- **pre-commit** for automated checks

All checks must pass before merging.

## 📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

## 🆘 Support

For issues and questions:

1. Check the examples directory for usage patterns
2. Review the MCP server logs for debugging
3. Open an issue on GitHub for bugs or feature requests

---

**BookBridge-MCP**: Bridging languages, preserving meaning. 🌉📚

