MCP-OPENAPI-DOCX

Enterprise-grade document editing and management server supporting MCP (Model Context Protocol) and OpenAPI protocols for DOCX documents.

🌟 Features

• Complete DOCX Support: Full support for reading, writing, and editing Microsoft Word documents
• MCP Protocol: Implements the Model Context Protocol for AI-powered document operations
• RESTful API: Comprehensive OpenAPI-compliant REST API with Swagger documentation
• Async Architecture: Built with FastAPI and async/await for high performance
• Document Processing: Paragraphs, tables, lists, images, styles, and more
• Version Control: Track document versions and compare changes
• Template Management: Create and manage document templates
• Export Options: Export to PDF, HTML, Markdown, and plain text
• Comments & Revisions: Add comments and track changes
• Security: Document encryption, password protection, and permissions
• Background Tasks: Celery integration for long-running operations
• Containerized: Docker and Kubernetes ready

📋 Table of Contents

• Installation
• Quick Start
• API Documentation
• MCP Protocol
• Configuration
• Development
• Testing
• Deployment
• Contributing
• License

🚀 Installation

Prerequisites

• Python 3.10 or higher
• Docker and Docker Compose (optional)
• PostgreSQL (optional, SQLite available for development)
• Redis (for Celery tasks)

Using pip and venv (Recommended)

# Clone the repository
git clone https://github.com/Fu-Jie/MCP-OPENAPI-DOCX.git
cd MCP-OPENAPI-DOCX

# Create virtual environment
python -m venv venv

# Activate virtual environment
# On Linux/macOS:
source venv/bin/activate
# On Windows (Command Prompt):
venv\Scripts\activate.bat
# On Windows (PowerShell):
venv\Scripts\Activate.ps1

# Upgrade pip
pip install --upgrade pip

# Install dependencies
pip install -r requirements.txt

# Copy environment configuration
cp .env.example .env

# Run the application
python main.py

Using Docker

# Clone the repository
git clone https://github.com/Fu-Jie/MCP-OPENAPI-DOCX.git
cd MCP-OPENAPI-DOCX

# Start with Docker Compose
docker-compose up -d

# View logs
docker-compose logs -f api

🏃 Quick Start

Start the API Server

# Method 1: Using main.py (Recommended)
python main.py

# Method 2: Using uvicorn directly
python -m uvicorn src.api.main:app --reload --port 8000

# Production mode with multiple workers
python -m uvicorn src.api.main:app --host 0.0.0.0 --port 8000 --workers 4

Access the API

• API Documentation: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc
• OpenAPI Schema: http://localhost:8000/openapi.json

Start the MCP Server

# Run MCP server (for AI integrations)
python main.py --mcp

📖 API Documentation

The API provides comprehensive endpoints for document management:

Core Endpoints

Endpoint	Method	Description
/api/v1/documents	GET	List all documents
/api/v1/documents	POST	Create a new document
/api/v1/documents/{id}	GET	Get document details
/api/v1/documents/{id}	PUT	Update document
/api/v1/documents/{id}	DELETE	Delete document

Text Operations

Endpoint	Method	Description
/api/v1/text/{doc_id}/paragraphs	GET	List paragraphs
/api/v1/text/{doc_id}/paragraphs	POST	Add paragraph
/api/v1/text/{doc_id}/paragraphs/{idx}	PUT	Update paragraph
/api/v1/text/{doc_id}/format	POST	Apply formatting

Table Operations

Endpoint	Method	Description
/api/v1/tables/{doc_id}	GET	List tables
/api/v1/tables/{doc_id}	POST	Create table
/api/v1/tables/{doc_id}/{idx}/cell	PUT	Update cell
/api/v1/tables/{doc_id}/{idx}/row	POST	Add row

See the full API Documentation for complete details.

🔌 MCP Protocol

This server implements the Model Context Protocol for AI integrations:

Available Tools

• create_document - Create a new DOCX document
• open_document - Open an existing document
• add_paragraph - Add a paragraph to a document
• add_table - Add a table to a document
• format_text - Apply text formatting
• search_replace - Search and replace text
• export_document - Export to various formats
• And 80+ more tools...

Example Usage

# Using MCP client
async with MCPClient("http://localhost:8000/mcp") as client:
    result = await client.call_tool(
        "create_document",
        {"name": "My Document"}
    )

See the MCP Protocol Guide for detailed usage.

⚙️ Configuration

Configuration is managed through environment variables. Copy .env.example to .env:

cp .env.example .env

Key Configuration Options

Variable	Description	Default
DATABASE_URL	Database connection URL	sqlite+aiosqlite:///./docx_db.sqlite
REDIS_URL	Redis connection URL	redis://localhost:6379/0
SECRET_KEY	JWT secret key	(required in production)
DEBUG	Enable debug mode	false
ENVIRONMENT	Environment name	development
UPLOAD_DIR	Upload directory	./uploads
MAX_UPLOAD_SIZE	Max upload size (bytes)	104857600

See .env.example for all available options.

🛠️ Development

Project Structure

mcp-openapi-docx/
├── src/
│   ├── api/            # FastAPI application
│   │   ├── routes/     # API endpoints
│   │   └── dependencies.py
│   ├── core/           # Core configuration
│   ├── database/       # Database setup
│   ├── handlers/       # DOCX file handlers
│   ├── mcp/            # MCP server
│   ├── middleware/     # HTTP middleware
│   ├── models/         # Data models
│   ├── services/       # Business logic
│   ├── tasks/          # Celery tasks
│   └── utils/          # Utility functions
├── tests/              # Test suite
├── docs/               # Documentation
├── alembic/            # Database migrations
├── kubernetes/         # K8s configurations
└── scripts/            # Utility scripts

Running Locally

# Activate virtual environment
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dev dependencies
pip install -r requirements.txt

# Run linting
ruff check src/
black --check src/
isort --check-only src/

# Run type checking
mypy src/

# Start development server
python main.py
# Or with auto-reload:
python -m uvicorn src.api.main:app --reload

Database Migrations

# Create a new migration
alembic revision --autogenerate -m "description"

# Apply migrations
alembic upgrade head

# Rollback
alembic downgrade -1

🧪 Testing

# Run all tests
pytest

# Run with coverage
pytest --cov=src --cov-report=html

# Run specific test file
pytest tests/unit/handlers/test_document_handler.py

# Run integration tests
pytest tests/integration/ -v

🚢 Deployment

Docker Compose (Recommended for Development)

docker-compose up -d

Kubernetes

# Apply configurations
kubectl apply -f kubernetes/

# Check status
kubectl get pods -n docx

Manual Deployment

# Build the image
docker build -t mcp-openapi-docx:latest .

# Run the container
docker run -p 8000:8000 mcp-openapi-docx:latest

See the Deployment Guide for production recommendations.

🤝 Contributing

Contributions are welcome! Please read our contributing guidelines before submitting a pull request.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

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

📞 Support

• Documentation: docs/
• Issues: GitHub Issues
• Discussions: GitHub Discussions

---

Made with ❤️ for the document automation community