BookBridge-MCP
> 🎉 表示庆祝或喜悦的符号,中文中可直接用其图形表达,或译为“庆祝”、“喜悦”等词,具体根据语境而定。 现已在PyPI上发布! 只需一个简单命令即可安装:
>
>bash
> uvx bookbridge-mcp
>
>
> 或者直接从GitHub运行:
>
>bash
> uvx --from git+https://github.com/Polly2014/BookBridge-MCP-Server bookbridge-mcp
>
🌉 概述
✨ 主要特点
- 📦 可在 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上!**```bash
# Run directly from PyPI - simple and clean!
uvx bookbridge-mcp
更新您的MCP配置 (mcp.json):```json
{
"servers": {
"Book-Bridge-MCP": {
"command": "uvx",
"args": ["bookbridge-mcp"],
"type": "stdio"
}
}
}
**优点:**
- ✅ 已发布在PyPI - 稳定版本
- ✅ 无需安装
- ✅ 自动依赖管理
- ✅ 快速且可靠
- ✅ 简单的一行配置
______________________________________________________________________
### 方法2:直接从GitHub运行(最新代码)
**始终获取最新的开发版本:**```bash
# Run directly from GitHub
uvx --from git+https://github.com/Polly2014/BookBridge-MCP-Server bookbridge-mcp
更新您的MCP配置 (mcp.json):```json
{
"servers": {
"Book-Bridge-MCP": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/Polly2014/BookBridge-MCP-Server",
"bookbridge-mcp"
],
"type": "stdio"
}
}
}
**优点:**
- ✅ 始终拥有最新代码
- ✅ 无需本地安装
- ✅ 通过 uv 实现自动依赖管理
- ✅ 非常适合测试新功能
______________________________________________________________________
### 方法3:本地开发安装
#### 1. 安装依赖项```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. 测试环境```bash
Verify installation
poetry run python test_environment.py
Test MCP functionality
poetry run python test_simple.py
#### 3. 启动服务器```bash
# Start the MCP server
poetry run python start.py
4. 运行客户端示例```bash
Test with client example
poetry run python examples/client_example.py
#### 5. 开发命令```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)
📦 安装方法对比
| 方法 | 命令 | 使用场景 | 安装时间 |
|---|---|---|---|
| PyPI 🌟 | uvx bookbridge-mcp |
通用用途,生产 | ⚡ 最快 |
| GitHub | uvx --from git+https://... bookbridge-mcp |
最新功能,测试中 | ⚡ 快速 |
| 本地 | poetry install && poetry run ... |
开发、贡献 | 🐢 需要设置 |
方法4:传统pip安装(备选方案)
如果您更喜欢使用传统的 pip 安装方式:```bash
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:使用诗歌(推荐)```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
选项B:使用pip```bash
git clone https://github.com/your-repo/BookBridge-MCP.git
cd BookBridge-MCP
pip install -r requirements.txt
### 3. 启动MCP服务器
#### 运用诗歌:```bash
poetry run python start.py
# or
poetry run bookbridge-server
# or using make commands
make run # Unix/Linux/Mac
make.bat run # Windows
使用 pip:```bash
python start.py
服务器将启动,并在配置的端口上监听MCP连接。
### 3. 客户端集成
MCP服务器提供工具、资源和提示。您的客户端应用程序负责处理与大型语言模型(LLM)的交互:```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 服务器功能
工具
process_document- 在Word和Markdown格式之间转换文档list_documents- 列出并管理项目中的文档get_document_info- 获取特定文档的详细信息
资源
- 文档注册表 - 跟踪所有已处理的文件
- 项目文件 - 访问源文档和输出文档
提示
📁 项目结构```
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` 文件:```json
{
"servers": {
"Book-Bridge-MCP": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/Polly2014/BookBridge-MCP-Server",
"bookbridge-server"
],
"type": "stdio"
}
}
}
优点:
- ✅ 无需本地安装
- ✅ 始终运行GitHub上的最新版本
- ✅ 通过uv实现自动依赖管理
- ✅ 清晰简洁的配置
选项2:使用本地安装```json
{
"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)```json
{
"servers": {
"Book-Bridge-MCP": {
"command": "uvx",
"args": ["bookbridge-mcp"],
"type": "stdio"
}
}
}
服务器配置
编辑 config.env 自定义设置:```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
## 开发工作流程
### 使用诗歌(推荐)
诗歌提供了更佳的依赖管理和开发工作流程:```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
使用Make命令
为方便起见,请使用提供的 Makefile(适用于 Unix/Linux/Mac)或 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
### 包管理```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
💡 使用示例```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")
### 批处理```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")
自定义内容类型```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"
)
## 🎯 客户端大型语言模型(LLM)的优势
1. **灵活性**客户可以使用任何大型语言模型(LLM)提供商或模型
1. **安全**API密钥保留在客户端
1. **可扩展性**服务器专注于文档处理
1. **成本控制**客户管理自己的大型语言模型(LLM)使用
- **智能分块**在拆分大文本时保留文档结构
- **格式保持**保持标题、列表和强调内容
- **内容类型优化**针对不同文本类型的专用提示
## 🧪 测试
### 运行测试
运用诗歌:```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
使用Make命令:```bash
Unix/Linux/Mac
make test
make test-coverage
make quick-test
Windows
make.bat test
make.bat test-coverage
make.bat quick-test
### 运行实例
测试客户端示例:```bash
# Using Poetry
poetry run python examples/client_example.py
# Using Make
make client-example # Unix/Linux/Mac
make.bat client-example # Windows
开发测试```bash
Run architecture tests
poetry run python test_architecture.py
Test individual components
poetry run python test_components.py
## 🤝 贡献
### 开发环境设置
1. 为仓库创建分支(或:克隆仓库)
1. 克隆你的分支:```bash
git clone https://github.com/your-username/BookBridge-MCP.git
cd BookBridge-MCP
- 设置开发环境:```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
### 开发工作流程
1. 创建一个特性分支: `git checkout -b feature/your-feature`
1. 做出你的更改
1. 进行质量检查:```bash
make check # Unix/Linux/Mac
make.bat check # Windows
- 为新功能添加测试
- 提交您的更改:
git commit -m "Add your feature" - 推送到你的叉(即你的GitHub仓库分支):
git push origin feature/your-feature - 提交拉取请求
代码质量
这个项目使用了:
- 黑色 用于代码格式化
- flake8 用于代码检查(或代码风格检测)
- pre-commit(在提交前) 用于自动化检查
在合并之前,所有检查都必须通过。
📄 许可证
此项目采用MIT许可证授权——详见LICENSE文件。
🔗 链接
🆘 支持
对于问题和疑问:
- 检查一下 示例目录 用于使用模式
- 审查/回顾 安装指南 详细的设置说明
- 检查 MCP配置示例 对于不同的设置
- 查看MCP服务器日志以进行调试
- 打开一个 GitHub上的问题 对于错误报告或功能请求
📚 文档
- 安装指南 - 详细的安装说明
- 快速入门 - 快速参考卡
- MCP配置示例 - 配置示例
- 更新日志 - 版本历史
- 出版指南 - 对于维护者
⭐ 表达你的支持
如果您觉得BookBridge-MCP很有帮助,请考虑:
- ⭐ 主演包括 GitHub 仓库
- 📢 与可能受益的他人分享
- 🐛 报告问题或提出功能建议
- 🤝 贡献代码或文档
BookBridge-MCP跨越语言障碍,保留原意精髓。 高楼大厦📚
