Awels MCP Server - PDF Processing Tool

A Model Context Protocol (MCP) server that provides PDF processing capabilities using docling. This server exposes a single tool to convert PDF files to Markdown format with optional image extraction, designed to run in isolated environments to avoid permission issues.

Project Structure

awels-mcp/
├── src/
│   └── awels_mcp/
│       ├── pdf_processor/     # PDF processing functionality
│       │   └── __init__.py    # PDFProcessor implementation
│       ├── __init__.py        # Package initialization
│       ├── run_server.py      # Server entry point
│       └── server.py          # MCP server implementation
├── tests/                     # Test files
│   ├── artifacts/             # Test artifacts (PDFs, outputs)
│   │   ├── test_output_md/    # Generated markdown files
│   │   ├── test_output_images/# Extracted images
│   │   └── test_pdfs/         # Sample PDFs for testing
│   ├── test_client.py         # Test MCP client
│   ├── test_pdf_processor.py  # Unit tests for PDF processing
│   └── test_server.py         # Server tests
├── .gitignore
├── INSTALL.md                 # Installation instructions
├── LICENSE
├── PLAN.md
├── README.md                  # This file
├── pyproject.toml             # Project metadata and dependencies
└── requirements.txt           # Development dependencies

Features

• PDF to Markdown Conversion: Convert PDF files to clean Markdown format using docling
• Image Extraction: Extract images from PDFs (page images, tables, figures)
• Batch Processing: Process multiple PDF files in a directory (with recursive search)
• Structured Output: Returns detailed JSON results with file metadata and processing statistics
• Isolated Execution: Designed to run with uvx --isolated to prevent permission issues
• Error Handling: Graceful handling of permission errors and processing failures

Installation

See INSTALL.md for detailed installation instructions using uv.

Quick Start

1. Install the package in development mode:

uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -e .

2. Run the tests to verify the installation:

pytest tests/

3. Start the MCP server:

python -m src.awels_mcp.run_server

4. In a separate terminal, run the test client:

python tests/test_client.py

Running Tests

The test suite includes:

• Unit tests for the PDF processor
• Integration tests for the MCP server
• End-to-end tests with the client

To run all tests:

pytest tests/

Test artifacts (generated markdown and images) are saved in the tests/artifacts/ directory.

Development

Project Structure

• src/awels_mcp/: Main package source code
  • pdf_processor/: PDF processing functionality
  • server.py: MCP server implementation
  • run_server.py: Entry point for the MCP server

Adding New Features