Bookbridge MCP Server

BookBridge-MCP

🎉 表示庆祝或喜悦的符号，中文中可直接用其图形表达，或译为“庆祝”、“喜悦”等词，具体根据语境而定。 现已在PyPI上发布！ 只需一个简单命令即可安装： ``bash uvx bookbridge-mcp ` 或者直接从GitHub运行： `bash uvx --from git+https://github.com/Polly2014/BookBridge-MCP-Server bookbridge-mcp ``

一个基于FastMCP框架的强大模型上下文协议（MCP）服务器，用于中译英书籍翻译和文档处理。

🌉 概述

BookBridge-MCP 提供了一套全面的解决方案，用于将中文书籍和文件翻译成英文，同时保持其格式和结构不变。服务器遵循一种（此处原文未完整，以下为假设补充的翻译）：先进的处理流程，确保翻译的准确性和格式的完整性 客户端大型语言模型（LLM）架构在此系统中，MCP服务器负责文档处理并提供翻译资源，而大型语言模型（LLM）的交互则在客户端进行。

✨ 主要特点

• 📦 可在 PyPI 上获取使用以下方式安装： uvx bookbridge-mcp
• 无需安装直接从 PyPI 或 GitHub 运行 uvx
• 文档处理在Word（.docx）和Markdown格式之间进行转换
• 智能资源管理组织并跟踪翻译项目
• 专业翻译提示针对不同类型内容的专用提示
• 客户端大型语言模型（LLM）架构文档处理与AI推理之间的清晰分离
• 批处理高效处理多份文档
• 格式保持保持原文档的结构和格式

🏗️ 建筑学

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

⚡ 快速启动

方法1：使用uvx配合PyPI（推荐！🌟）

最简单的方法——已发布在PyPI上！

# Run directly from PyPI - simple and clean!
uvx bookbridge-mcp

更新您的MCP配置 (mcp.json):

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

优点：

• ✅ 已发布在PyPI - 稳定版本
• ✅ 无需安装
• ✅ 自动依赖管理
• ✅ 快速且可靠
• ✅ 简单的一行配置

______________________________________________________________________

方法2：直接从GitHub运行（最新代码）

始终获取最新的开发版本：

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

更新您的MCP配置 (mcp.json):

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

优点：

• ✅ 始终拥有最新代码
• ✅ 无需本地安装
• ✅ 通过 uv 实现自动依赖管理
• ✅ 非常适合测试新功能

______________________________________________________________________

方法3：本地开发安装

1. 安装依赖项

# 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. 测试环境

# Verify installation
poetry run python test_environment.py

# Test MCP functionality
poetry run python test_simple.py

3. 启动服务器

# Start the MCP server
poetry run python start.py

4. 运行客户端示例

# Test with client example
poetry run python examples/client_example.py

5. 开发命令

# 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)

______________________________________________________________________

📦 安装方法对比

______________________________________________________________________

方法4：传统pip安装（备选方案）

如果您更喜欢使用传统的 pip 安装方式：

# Install from PyPI
pip install bookbridge-mcp

# Run the server (both commands work)
bookbridge-mcp
# or
bookbridge-server

注带有 uvx，你无需手动安装——它会自动处理一切！

______________________________________________________________________

🚀 详细安装步骤

1. 前提条件

• Python 3.10或更高版本
• 诗歌（推荐）或 pip

2. 安装

选项A：使用诗歌（推荐）

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

选项B：使用pip

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

3. 启动MCP服务器

运用诗歌：

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

使用 pip：

python start.py

服务器将启动，并在配置的端口上监听MCP连接。

3. 客户端集成

MCP服务器提供工具、资源和提示。您的客户端应用程序负责处理与大型语言模型（LLM）的交互：

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 服务器功能

工具

1. process_document - 在Word和Markdown格式之间转换文档
2. list_documents - 列出并管理项目中的文档
3. get_document_info - 获取特定文档的详细信息
4. create_translation_project - 建立新的翻译项目
5. get_translation_metrics - 计算翻译质量指标

资源

• 文档注册表 - 跟踪所有已处理的文件
• 项目文件 - 访问源文档和输出文档
• 翻译历史 - 查看之前的翻译

提示

• 一般翻译 - 用于日常内容
• 学术翻译 - 用于学术和研究文本
• 技术翻译 - 用于文档和手册
• 创意翻译 - 对于文学和创意作品

📁 项目结构

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

🔧 配置

MCP客户端配置

您可以以三种方式配置您的MCP客户端：

选项1：使用uvx与GitHub（推荐）

编辑你的 mcp.json 文件：

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

优点：

• ✅ 无需本地安装
• ✅ 始终运行GitHub上的最新版本
• ✅ 通过uv实现自动依赖管理
• ✅ 清晰简洁的配置

选项2：使用本地安装

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

选项3：使用类似npx的语法（如果已发布到PyPI）

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

服务器配置

编辑 config.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

开发工作流程

使用诗歌（推荐）

诗歌提供了更佳的依赖管理和开发工作流程：

# 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

使用Make命令

为方便起见，请使用提供的 Makefile（适用于 Unix/Linux/Mac）或 make.bat（适用于 Windows）：

# 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

包管理

# 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

💡 使用示例

基本文件翻译

# 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")

批处理

# 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")

自定义内容类型

您可以向服务器请求特定的翻译提示：

# 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"
)

🎯 客户端大型语言模型（LLM）的优势

1. 灵活性客户可以使用任何大型语言模型（LLM）提供商或模型
2. 安全API密钥保留在客户端
3. 可扩展性服务器专注于文档处理
4. 定制化客户可以自定义翻译参数
5. 成本控制客户管理自己的大型语言模型（LLM）使用

📊 翻译质量特征

• 智能分块在拆分大文本时保留文档结构
• 格式保持保持标题、列表和强调内容
• 指标计算分析翻译质量及完整性
• 内容类型优化针对不同文本类型的专用提示

🧪 测试

运行测试

运用诗歌：

# 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

使用Make命令：

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

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

运行实例

测试客户端示例：

# Using Poetry
poetry run python examples/client_example.py

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

开发测试

# Run architecture tests
poetry run python test_architecture.py

# Test individual components
poetry run python test_components.py

🤝 贡献

开发环境设置

1. 为仓库创建分支（或：克隆仓库）
2. 克隆你的分支：

   git clone https://github.com/your-username/BookBridge-MCP.git
   cd BookBridge-MCP

1. 设置开发环境：

   # 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

开发工作流程

1. 创建一个特性分支： git checkout -b feature/your-feature
2. 做出你的更改
3. 进行质量检查：

   make check              # Unix/Linux/Mac
   make.bat check          # Windows

1. 为新功能添加测试
2. 提交您的更改： git commit -m "Add your feature"
3. 推送到你的叉（即你的GitHub仓库分支）： git push origin feature/your-feature
4. 提交拉取请求

代码质量

这个项目使用了：

• 黑色 用于代码格式化
• isort（注：这通常是一个代码格式化工具的名字，如Python的isort工具，用于排序和整理import语句，但直接翻译其英文名并无特定含义，因此此处保留原样） 用于进口分类
• flake8 用于代码检查（或代码风格检测）
• mypy（注：mypy 是一个用于静态类型检查的 Python 工具，直接翻译为“米皮”并无实际意义，此处保留原英文形式以指代该工具） 用于类型检查
• pytest（注：这是一个测试框架的名称，在中文中通常直接保留原名，不进行翻译） 用于测试
• pre-commit（在提交前） 用于自动化检查

在合并之前，所有检查都必须通过。

📄 许可证

此项目采用MIT许可证授权——详见LICENSE文件。

🔗 链接

• PyPI 包https://pypi.org/project/bookbridge-mcp/ 翻译为中文是：“https://pypi.org 上的 bookbridge-mcp 项目”
• GitHub 仓库https://github.com/Polly2014/BookBridge-MCP-Server 翻译为中文是：“https://github.com/Polly2014/BookBridge-MCP-服务器（或：BookBridge-MCP服务器项目）”。不过，通常我们不会直接翻译网址，而是直接使用原网址或根据上下文给出简要说明。如果需要在中文语境下介绍这个网址，可以这样说：“这是GitHub上的一个项目链接：Polly2014的BookBridge-MCP服务器（或：BookBridge-MCP服务器项目）”
• 问题https://github.com/Polly2014/BookBridge-MCP-Server/issues 翻译为中文是：“https://github.com/Polly2014/BookBridge-MCP-Server的问题页面”。不过，通常在中文语境下，我们可能会更简洁地表述为“BookBridge-MCP-Server在GitHub上的问题追踪页面”或“BookBridge-MCP-Server的问题报告页面”，具体取决于上下文和表达习惯。但直接翻译原网址链接，就是“https://github.com/Polly2014/BookBridge-MCP-Server/issues（问题页面）”
• 讨论https://github.com/Polly2014/BookBridge-MCP-Server/discussions 的中文翻译是：“https://github.com/Polly2014/BookBridge-MCP-Server/讨论区”

🆘 支持

对于问题和疑问：

1. 检查一下 示例目录 用于使用模式
2. 审查/回顾 安装指南 详细的设置说明
3. 检查 MCP配置示例 对于不同的设置
4. 查看MCP服务器日志以进行调试
5. 打开一个 对于错误报告或功能请求

📚 文档

• 安装指南 - 详细的安装说明
• 快速入门 - 快速参考卡
• MCP配置示例 - 配置示例
• 更新日志 - 版本历史
• 出版指南 - 对于维护者

⭐ 表达你的支持

如果您觉得BookBridge-MCP很有帮助，请考虑：

• ⭐ 主演包括
• 📢 与可能受益的他人分享
• 🐛 报告问题或提出功能建议
• 🤝 贡献代码或文档

______________________________________________________________________

BookBridge-MCP跨越语言障碍，保留原意精髓。 高楼大厦📚