# docling-project/docling-mcp architecture

> Architecture diagram of the GitHub repository docling-project/docling-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/docling-project/docling-mcp
- Repository: https://github.com/docling-project/docling-mcp

## Overview

##### Project Type and Purpose
- The project is a document processing backend service. It leverages the Docling-MCP library to provide tools for document conversion and generation. Its purpose is to convert PDFs to structured DoclingDocument formats, generate documents via tool invocations, and optimize performance through caching.
- The README mentions integration with external systems (e.g., Claude Desktop) and use cases like conversion commands and document generation workflows.

##### File Structure
- The top-level directories include:
- .github: Contains CI/CD workflows, configuration templates, and release scripts (indicating automated testing, static analysis, and deployment pipelines).
- clients: Hosts test scripts (e.g., test_llama_stack.py) which act as sample client interactions.
- docling_mcp: The core module folder that holds the service’s functional components.
▪ Modules include:
- server.py: Likely the entry point for launching the service.
- docling_cache.py: Manages local document caching.
- docling_settings.py: Handles configuration.
- logger.py: Implements logging.
- shared.py: Contains shared utilities.
- tools (with conversion.py and generation.py): Implements the transformation and generation tools.
- docs: Provides integration guides (like the Claude Desktop configuration example) and contributing guidelines.
- tests: Contains testing scripts to validate system functionality.
- The presence of configuration (pyproject.toml, ruff.toml, .pre-commit-config.yaml) and CI files confirms adherence to best practices and a mature development workflow.

##### Key Architectural Components (to be reflected
- Service Backend (Docling MCP Service):
- Server Module: Exposes the application’s endpoints (likely via command-line or an internal API) to accept commands for conversion and generation.
- Tools Modules:
▪ Conversion Tools: Exposed via conversion.py to transform PDFs into structured JSON format.
▪ Generation Tools: Exposed via generation.py to build new DoclingDocuments iteratively.
- Caching Module: docling_cache.py which provides improved performance management by caching parsed documents.
- Settings Component: docling_settings.py that loads and manages configuration details.
- Logging Component: logger.py for debugging and operational monitoring.
- Clients:
- Test scripts and potentially integrated systems such as clients/test_llama_stack.py.
- External integrations (e.g., Claude Desktop) configured via the provided JSON file in docs/integrations.
- External Integrations & Protocol:
- The MCP (Message Control Protocol) serves as the communication protocol for tool integration with third-party clients.
- Infrastructure:
- While the system is primarily a backend service, CI/CD workflows (in .github/workflows) indicate automated testing, building, and publishing pipelines (e.g., via PyPI).

##### Relationships and Data Flows
- Client applications (test scripts, Claude Desktop, etc.) send requests to the Docling MCP server.
- The server (running from server.py) delegates tasks to the relevant tools (using conversion or generation modules) depending on the incoming command.
- The conversion and generation tools interact with the caching mechanism (docling_cache.py) to retrieve or store document data.
- The settings module (docling_settings.py) loads configurations guiding the tool behavior.
- The logging module (logger.py) continuously records service events and errors.
- CI/CD components (GitHub workflows) help in building, testing and deploying the service.

##### Architectural Patterns and Design Principles
- Service-oriented architecture: The service is clearly separated into distinct components (server, tools, cache, settings, logging) that interact through well-defined interfaces.
- Modularity: The tools and other utilities are encapsulated in separate sub-modules, enhancing maintainability and potential extensibility.
- Integration through a protocol (MCP) emphasizes a decoupled design where clients can interact with the service over standardized commands.
- Automated testing and deployment workflows reinforce continuous integration and delivery.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Components
    Clients["Client Applications"]:::client
    Integration["Claude Desktop Integration"]:::external
    CICD["CI/CD Pipelines"]:::infrastructure

    %% Internal Service Components
    subgraph "Docling MCP Service"
        DMS["Docling MCP Server"]:::service
        CT["Conversion Tools"]:::tools
        GT["Generation Tools"]:::tools
        CC["Caching Component"]:::cache
        DS["Settings Component"]:::settings
        LG["Logging Component"]:::logging
    end

    %% Relationships and Data Flows
    Clients -->|"sends_request"| DMS
    Integration -->|"provides_config"| DMS
    DMS -->|"executes"| CT
    DMS -->|"executes"| GT
    DMS -->|"utilizes"| CC
    DMS -->|"loads"| DS
    DMS -->|"records_logs"| LG
    CICD -->|"automates_build_test_deploy"| DMS

    %% Click Events
    click DMS "https://github.com/docling-project/docling-mcp/blob/main/docling_mcp/server.py"
    click CT "https://github.com/docling-project/docling-mcp/blob/main/docling_mcp/tools/conversion.py"
    click GT "https://github.com/docling-project/docling-mcp/blob/main/docling_mcp/tools/generation.py"
    click CC "https://github.com/docling-project/docling-mcp/blob/main/docling_mcp/docling_cache.py"
    click DS "https://github.com/docling-project/docling-mcp/blob/main/docling_mcp/docling_settings.py"
    click LG "https://github.com/docling-project/docling-mcp/blob/main/docling_mcp/logger.py"
    click Clients "https://github.com/docling-project/docling-mcp/blob/main/clients/test_llama_stack.py"
    click CICD "https://github.com/docling-project/docling-mcp/tree/main/.github/workflows"
    click Integration "https://github.com/docling-project/docling-mcp/blob/main/docs/integrations/claude_desktop_config.json"

    %% Styles
    classDef service fill:#f9c,stroke:#333,stroke-width:2px;
    classDef tools fill:#bbf,stroke:#333,stroke-width:2px;
    classDef cache fill:#afa,stroke:#333,stroke-width:2px;
    classDef settings fill:#ffa,stroke:#333,stroke-width:2px;
    classDef logging fill:#fcc,stroke:#333,stroke-width:2px;
    classDef client fill:#cfc,stroke:#333,stroke-width:2px;
    classDef external fill:#fcf,stroke:#333,stroke-width:2px;
    classDef infrastructure fill:#ddd,stroke:#333,stroke-width:2px;
```
