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

🚀 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.

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
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