mcp-server-docx by ndu-bioinfo - MCP Server

MCP Server for DOCX Files

An MCP (Model Context Protocol) server for reading, writing, and managing DOCX documents.

Prerequisites

Install uv (Required)

This project uses uv for fast Python package management. Install it first:

macOS/Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Alternative methods:

# Via pip
pip install uv

# Via Homebrew (macOS)
brew install uv

# Via WinGet (Windows)
winget install --id=astral-sh.uv

Verify installation:

uv --version

Note: If uv command is not found after installation, you may need to restart your terminal or add it to your PATH. The installer typically places uv in ~/.local/bin/ on Linux/macOS.

Quick Start

Clone the repository:

git clone <repository-url>
cd mcp-server-docx

Install uv (if you haven't already - see Prerequisites section below)

Set up the environment:

# Development environment (recommended)
uv sync --all-extras

Generate MCP configuration:
```
uv run src/generate_mcp_config.py
```
Copy the output to your MCP client configuration file
Start using the DOCX tools in your MCP client!

Installation

Environment Setup with uv (Recommended)

# Development environment (includes test dependencies)
uv sync --all-extras

# Production environment only  
uv sync --no-dev

# Fresh install (clean slate)
rm -rf .venv && uv sync --all-extras

Manual Installation

pip install -e .

Usage

Run as an MCP server:

uv run mcp-server-docx

Generate MCP Configuration

After setting up your development environment, generate the configuration for your system:

# 1. Make sure you have the development environment ready
uv sync --all-extras

# 2. Generate configuration with paths specific to your system
uv run src/generate_mcp_config.py

# 3. Copy the JSON output to your MCP client configuration file
# For Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
# For Claude Desktop: %APPDATA%\Claude\claude_desktop_config.json (Windows)
# For Cursor: Follow Cursor's MCP setup documentation

Example output:

{
  "mcpServers": {
    "mcp-server-docx": {
      "command": "/your/path/to/mcp-server-docx/.venv/bin/mcp",
      "args": ["run", "/your/path/to/mcp-server-docx/main.py"],
      "env": {
        "PYTHONPATH": "/your/path/to/mcp-server-docx"
      }
    }
  }
}

Note: The generated paths will be specific to where you cloned this repository on your system.

Available Tools

The server provides 3 essential tools for DOCX document manipulation:

Document Operations

read_docx - Read complete document (content and comments)
add_comment_by_search_docx - Add comments to paragraphs containing specific text
add_paragraph_docx - Add paragraphs to existing DOCX files or create new ones

Each tool supports comprehensive error handling and returns structured responses with success/failure status.

Testing

With uv (Recommended)

# Run tests (automatically uses project environment)
uv run pytest tests/ -v -o addopts=""

# Run linting
uv run ruff check src/ tests/ main.py

# Fix linting issues automatically  
uv run ruff check --fix src/ tests/ main.py

# Format code
uv run ruff format src/ tests/ main.py

Note: Make sure you have the development environment set up first: uv sync --all-extras

Manual Testing

# Install test dependencies and run tests
pip install -e ".[test]"
pytest

Development

The project uses a pure uv workflow for all development tasks:

# Environment Management
rm -rf .venv build/ dist/ *.egg-info   # Clean environment
uv sync --no-dev                       # Production install
uv sync --all-extras                   # Development install

# Development Tasks
uv run pytest tests/                   # Run tests
uv run ruff check src/ tests/ main.py  # Check code style
uv run ruff format src/ tests/ main.py # Format code
uv pip list                            # Show dependencies

# Configuration
uv run src/generate_mcp_config.py      # Generate MCP config

# Environment Info
uv --version                           # Check uv version
uv pip list                            # Show installed packages

Key Commands Summary

Task	Command
🏗️ Setup dev env	`uv sync --all-extras`
🏭 Setup prod env	`uv sync --no-dev`
🧪 Run tests	`uv run pytest tests/`
🔍 Check code	`uv run ruff check .`
✨ Format code	`uv run ruff format .`
⚙️ Generate config	`uv run src/generate_mcp_config.py`
🧹 Clean up	`rm -rf .venv build/ dist/ *.egg-info`

Troubleshooting

Common Issues

1. uv command not found

# Check if uv is installed
which uv
ls ~/.local/bin/uv

# If installed but not in PATH, use full path
~/.local/bin/uv --version

# Or add to PATH (add to ~/.bashrc or ~/.zshrc)
export PATH="$HOME/.local/bin:$PATH"

2. Permission errors during installation

# Use --user flag if needed
pip install --user uv

3. Virtual environment issues

# Clean start if environment is corrupted
rm -rf .venv
uv sync --all-extras

4. Linting errors

# Auto-fix most linting issues
uv run ruff check --fix src/ tests/ main.py

# Format code to fix style issues
uv run ruff format src/ tests/ main.py

5. MCP configuration issues

# Make sure you've set up the environment first
uv sync --all-extras

# Regenerate configuration for your system
uv run src/generate_mcp_config.py

# Check that the generated paths are correct for your system
ls .venv/bin/mcp  # Should exist after uv sync

6. MCP server not found in client

Ensure you copied the complete JSON configuration
Check that the file paths in the configuration exist on your system
Restart your MCP client after adding the configuration
Verify the .venv directory exists in your cloned repository