MCP Document Processor

by arifazim
GPL 3.0

Integrations

  • Used for API communication between the frontend and backend, enabling efficient HTTP requests for document processing workflows.

  • Integrates with the UI for data visualization of document statistics, providing graphical representation of document processing metrics.

  • Powers the REST interface for the document processing system, enabling API-based interactions with the document processing capabilities.

MCP Document Processor

An intelligent document processing system that uses the Model Context Protocol (MCP) to extract, analyze, and route business documents automatically.

Project Overview

This project demonstrates how to use MCP to solve a real business challenge: automating document processing workflows. The system can:

  • Classify incoming documents (invoices, contracts, emails)
  • Extract relevant information using ML models
  • Process documents according to their type Maintain context throughout the processing pipeline Expose functionality through a REST API

Key MCP Components

  • Context Objects: Central to MCP, these objects (implemented in MCPContext) carry information between processing steps and maintain the document's state.
  • Memory System: Stores context objects between processing steps, with pluggable backends.
  • Protocols: Defines clear interfaces for processors and models, ensuring modularity.
  • Router: Intelligently routes documents to specialized processors based on content.

Business Value

This solution addresses several business challenges:

  • Reduced Manual Processing: Automates extraction of data from documents
  • Consistency: Ensures consistent processing across document types
  • Auditability: Maintains processing history and confidence scores
  • Scalability: Modular design allows adding new document types easily

Technical Highlights

  • Uses BERT-based models for classification and entity extraction
  • T5 model for document summarization
  • FastAPI for REST interface
  • Pluggable architecture for easy extension
  • Comprehensive logging and error handling
  • React based UI for better user experience

Overview

The MCP Document Processor is designed to solve the common business challenge of processing various types of documents (invoices, contracts, emails, etc.) in a consistent and automated way. It utilizes the Model Context Protocol framework to manage information flow between different components of the system.

Key Features

  • Document Classification: Automatically identifies document types
  • Information Extraction: Extracts key information from documents
  • Document Routing: Routes documents to the appropriate processors
  • Context Management: Maintains context throughout the processing pipeline
  • API Interface: Provides a RESTful API for integration with other systems

Architecture

The system is built around the Model Context Protocol (MCP), which provides:

  1. Context Objects: Carry information across processing steps
    # Example of MCPContext usage context = MCPContext( document_id=document_id, raw_text=text, metadata=metadata ) # Adding extracted data with confidence scores context.add_extracted_data("invoice_number", "INV-12345", confidence=0.95) # Tracking processing history context.add_to_history( processor_name="InvoiceProcessor", status="completed", details={"processing_time": "0.5s"} )
  2. Memory System: Stores context objects between API calls
    # Storing context in memory memory.store(document_id, context) # Retrieving context from memory context = memory.retrieve(document_id)
  3. Protocols: Define interfaces for processors and models
    # Processor protocol example class Processor(Protocol): @abstractmethod def process(self, context: MCPContext) -> MCPContext: """Process the document and update the context.""" pass @abstractmethod def can_handle(self, context: MCPContext) -> bool: """Determine if this processor can handle the given document.""" pass
  4. Router: Routes documents to appropriate specialized processors
    # Router usage example processor = processor_router.route(context) if processor: processed_context = processor.process(context)

MCP Flow Diagram

Document Upload → MCPContext Creation → Memory Storage → Document Processing → Router Selection → Specialized Processor → Entity Extraction → Context Update → Memory Storage → API Response

MCP Implementation Details

The Model Context Protocol implementation in this project offers several key advantages:

1. Stateful Processing with Context Persistence

The MCPContext class maintains state throughout the document processing lifecycle:

# Context is created during document upload @router.post("/documents/upload") async def upload_document(file: UploadFile, memory: MemoryInterface): # Create a context context = MCPContext( document_id=document_id, raw_text=text, metadata=metadata ) # Store in memory for later retrieval memory.store(document_id, context)

2. Pluggable Memory System

The memory system is designed to be pluggable, allowing different storage backends:

# Factory function in memory.py def get_memory_store(memory_type: str = "in_memory", **kwargs) -> MemoryInterface: if memory_type == "in_memory": return InMemoryStorage(default_ttl=kwargs.get("ttl", 3600)) # Additional implementations can be added here

3. Confidence Tracking

MCP tracks confidence scores for all extracted data, enabling better decision-making:

# In entity_extractor.py entity_data = { "text": text[current_entity["start"]:current_entity["end"]], "start": current_entity["start"], "end": current_entity["end"], "confidence": avg_confidence }

4. Processing History

Each processing step is recorded in the context's history, providing auditability:

# In router.py context.add_to_history( processor_name=processor.__class__.__name__, status="completed" )

5. Intelligent Document Routing

The ProcessorRouter determines the appropriate processor for each document:

# In router.py def route(self, context: MCPContext) -> Optional[Processor]: for processor in self.processors: if processor.can_handle(context): return processor return None

6. Extensibility

Adding new document types is straightforward by implementing the Processor protocol:

# Example of adding a new processor class NewDocumentProcessor(BaseProcessor): def can_handle(self, context: MCPContext) -> bool: # Logic to determine if this processor can handle the document pass def process(self, context: MCPContext) -> MCPContext: # Document processing logic pass

Document Processors

The system includes specialized processors for different document types:

  • Invoice Processor: Extracts vendor, customer, line items, totals, etc.
  • Contract Processor: Extracts parties, key dates, terms, etc.
  • Email Processor: Extracts sender, recipients, subject, body, etc.

Machine Learning Models

Several ML models are used for different tasks:

  • Document Classifier: BERT-based model for document type classification
  • Entity Extractor: Named Entity Recognition model for extracting key information
  • Summarizer: T5-based model for generating document summaries

User Interface

The MCP Document Processor includes a modern React-based user interface that provides an intuitive way to interact with the document processing system. The UI is built with Material-UI and offers the following features:

UI Features

  • Dashboard: Overview of processed documents with statistics and quick access to document details
  • Document Upload: Drag-and-drop interface for uploading new documents
  • Document Processing: Step-by-step workflow for processing documents
  • Document Viewer: Detailed view of processed documents with extracted information
  • Processing History: Timeline view of all processing steps for auditability

UI Architecture

The frontend is built with:

  • React: For building the user interface components
  • Material-UI: For consistent, responsive design
  • React Router: For navigation between different views
  • Axios: For API communication with the backend
  • Chart.js: For data visualization of document statistics

UI-Backend Integration

The frontend communicates with the backend through a RESTful API, with the following main endpoints:

  • GET /api/documents: Retrieve all documents
  • POST /api/documents/upload: Upload a new document
  • POST /api/documents/{document_id}/process: Process a document
  • GET /api/documents/{document_id}: Get document details
  • DELETE /api/documents/{document_id}: Delete a document

Complete System Architecture

The MCP Document Processor follows a layered architecture that integrates the frontend, API layer, processing components, and machine learning models:

┌─────────────────────────────────────────────────────────────────────────┐ │ Frontend Layer │ │ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │ │ │ Dashboard │ │ Upload │ │ Document Viewer │ │ │ └─────────────┘ └─────────────┘ └─────────────────────────┘ │ │ │ │ │ │ └──────────┼───────────────────┼─────────────────────────┼────────────────┘ │ │ │ │ │ │ ▼ ▼ ▼ ┌─────────────────────────────────────────────────────────────────────────┐ │ API Layer │ │ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │ │ │ Document │ │ Document │ │ Document │ │ │ │ Upload API │ │ Process API │ │ Retrieval API │ │ │ └─────────────┘ └─────────────┘ └─────────────────────────┘ │ │ │ │ │ │ └──────────┼───────────────────┼─────────────────────────┼────────────────┘ │ │ │ │ │ │ ▼ ▼ ▼ ┌─────────────────────────────────────────────────────────────────────────┐ │ MCP Core Components │ │ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │ │ │ MCPContext │◄────►│ Memory │◄────►│ Processor Router │ │ │ └─────────────┘ └─────────────┘ └─────────────────────────┘ │ │ │ │ │ └──────────┼────────────────────────────────────────────┼─────────────────┘ │ │ │ │ ▼ ▼ ┌─────────────────────────────────────────────────────────────────────────┐ │ Document Processors │ │ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │ │ │ Invoice │ │ Contract │ │ Email │ │ │ │ Processor │ │ Processor │ │ Processor │ │ │ └─────────────┘ └─────────────┘ └─────────────────────────┘ │ │ │ │ │ │ └──────────┼───────────────────┼─────────────────────────┼────────────────┘ │ │ │ │ │ │ ▼ ▼ ▼ ┌─────────────────────────────────────────────────────────────────────────┐ │ ML Models Layer │ │ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │ │ │ Document │ │ Entity │ │ Summarizer │ │ │ │ Classifier │ │ Extractor │ │ │ │ │ └─────────────┘ └─────────────┘ └─────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────────┘

Complete Workflow

The document processing workflow involves multiple steps across the system components:

  1. Document Upload:
    • User uploads a document through the UI
    • Frontend sends the document to the backend API
    • Backend creates an MCPContext object with document metadata
    • Context is stored in the Memory system
  2. Document Classification:
    • User initiates processing through the UI
    • Backend retrieves the document context from Memory
    • Document Classifier model determines document type
    • Context is updated with document type information
  3. Document Processing:
    • Processor Router selects the appropriate processor based on document type
    • Selected processor (Invoice, Contract, or Email) processes the document
    • Processor uses Entity Extractor to identify key information
    • Extracted data is added to the context with confidence scores
  4. Result Retrieval:
    • Updated context is stored back in Memory
    • UI retrieves and displays the processed document information
    • User can view extracted data, confidence scores, and processing history
  5. Audit and Review:
    • All processing steps are recorded in the context's processing history
    • UI provides visualization of confidence scores for extracted data
    • User can review the document text alongside extracted information

Getting Started

Prerequisites

  • Python 3.8+
  • Node.js 14+ and npm (for the frontend)
  • Dependencies listed in requirements.txt

Installation and Setup

Backend Setup
  1. Clone the repository
    git clone https://github.com/yourusername/mcp_document_processor.git cd mcp_document_processor
  2. Create and activate a virtual environment
    python -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate
  3. Install backend dependencies
    pip install -r requirements.txt
  4. Create a data directory for document storage (if it doesn't exist)
    mkdir -p data
Frontend Setup
  1. Navigate to the frontend directory
    cd frontend
  2. Install frontend dependencies
    npm install

Running the Application

Start the Backend Server
  1. From the root directory of the project (with virtual environment activated):
    python app.py
    This will start the FastAPI server on http://localhost:8000.
  2. You can access the API documentation at http://localhost:8000/docs
Start the Frontend Development Server
  1. Open a new terminal window/tab
  2. Navigate to the frontend directory:
    cd /path/to/mcp_document_processor/frontend
  3. Start the React development server:
    npm start
    This will start the frontend on http://localhost:3000.

Using the Application

  1. Open your browser and navigate to http://localhost:3000
  2. Use the sidebar navigation to:
    • View the dashboard
    • Upload new documents
    • Process and view document details
Example Workflow
  1. Upload a Document:
    • Click on "Upload Document" in the sidebar
    • Drag and drop a document (PDF, image, or text file)
    • Click "Upload Document" button
  2. Process the Document:
    • After successful upload, click "Process Document"
    • Wait for processing to complete
  3. View Results:
    • View extracted data, confidence scores, and processing history
    • Navigate to the Dashboard to see all processed documents

API Usage

You can also interact directly with the API:

  • GET /api/documents: Retrieve all documents
  • POST /api/documents/upload: Upload a new document
  • POST /api/documents/{document_id}/process: Process a document
  • GET /api/documents/{document_id}: Get document details
  • DELETE /api/documents/{document_id}: Delete a document

Extending the System

Adding a New Document Processor

  1. Create a new processor class that inherits from BaseProcessor
  2. Implement the can_handle and process methods
  3. Add the processor to the router in api/routes.py

Adding a New Model

  1. Create a new model class that implements the appropriate protocol
  2. Add configuration in config/config.yaml
  3. Integrate the model with the relevant processor

License

MIT License

Related MCP Servers

  • -
    security
    A
    license
    -
    quality
    A Model Context Protocol (MCP) server that enables semantic search and retrieval of documentation using a vector database (Qdrant). This server allows you to add documentation from URLs or local files and then search through them using natural language queries.
    Last updated -
    14
    74
    JavaScript
    Apache 2.0
    • Apple
  • -
    security
    A
    license
    -
    quality
    A tool for Model Context Protocol (MCP) that allows you to analyze web content and add it to your knowledge base, storing content as Markdown files for easy viewing with tools like Obsidian.
    Last updated -
    6
    Python
    MIT License
  • -
    security
    A
    license
    -
    quality
    A server that provides document processing capabilities using the Model Context Protocol, allowing conversion of documents to markdown, extraction of tables, and processing of document images.
    Last updated -
    6
    Python
    MIT License
    • Linux
    • Apple
  • A
    security
    A
    license
    A
    quality
    A Model Context Protocol (MCP) server that provides tools for reading Excel (xlsx) files, enabling extraction of data from entire workbooks or specific sheets with results returned in structured JSON format.
    Last updated -
    3
    2
    Python
    Apache 2.0
    • Linux
    • Apple

View all related MCP servers

ID: 3bjbgpxsfc