# baronco/local-docs-mcp-tool architecture

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

- Interactive diagram: https://gitdiagram.com/baronco/local-docs-mcp-tool
- Repository: https://github.com/baronco/local-docs-mcp-tool

## Overview

##### Project type and purpose
- This is a backend-only MCP (Model Context Protocol) server written in Python.
- Its job is to expose three main operations—list_documents, load_documents, and load_scanned_document—over the MCP protocol so that an MCP client (e.g., Claude Desktop) can navigate and process a local document directory, convert files to markdown, run OCR on scanned PDFs, and enforce token limits.

##### File structure
- Top-level scripts:
- server.py – the MCP server entrypoint
- main.py – (alternative or helper entry point)
- Configuration/build:
- pyproject.toml, uv.lock – declare dependencies and lock versions
- .env – environment variables (POPPLER_PATH)
- Source folder:
- src/instructions.md – embedded assistant instructions for prompt generation
- Utility modules (in utils/):
- path_files.py – document discovery
- markitdown.py – document → markdown conversion (using “markitdown” lib)
- ocr.py – wrap tesseract/pdf2image for scanned PDFs
- max_tokens.py – token‐budget enforcement (via tiktoken)
- prompts.py – build/format MCP request and response templates

##### Extract architectural insights from the README
- The server is launched via UV CLI (“uv run server.py <directory> <max_tokens>”).
- Clients call the MCP methods over stdin/stdout, receiving structured JSON with metadata, token counts, content, timings.
- External dependencies: Poppler (for PDF→image), Tesseract OCR, markitdown library, OpenCV, pdf2image, pytesseract, python-dotenv.
- Operating context: Windows only, local file system as “data store”; no traditional database.

a. Main components to show:
1) MCP Client (e.g., Claude Desktop)
2) UV CLI Launcher – starts the Python process
3) Python MCP Server (server.py)
– Command/argument parser
– MCP framework handler
4) Business-logic layer (utils modules)
– Document discovery (path_files.py)
– Conversion (markitdown.py)
– OCR (ocr.py)
– Token management (max_tokens.py)
– Prompt assembly (prompts.py)
5) External libraries/runtime
– markitdown, mcp framework, pdf2image, pytesseract, OpenCV, tiktoken, python-dotenv
6) External binaries
– Poppler executables
– Tesseract OCR engine
7) Local file system
– Document directory (user-supplied)
– .env configuration file

b. Relationships & data‐flow
- MCP Client → UV CLI (start) → Python Server
- Server parses CLI args → initializes MCP endpoints
- Client issues MCP method calls (stdin) → Server invokes corresponding utils function
- Utilities read from file system or call external binaries → return raw text or markdown
- max_tokens enforces truncation → prompts formats response → Server writes JSON to stdout → Client

c. Architectural patterns & design principles
- Layered separation: CLI & protocol handling | business logic | filesystem & external integration
- Single responsibility per util module
- Externalizing configuration via .env (dotenv)
- Dependency injection via CLI args (document path, token limit)

d. Key technologies & frameworks
- Python 3.13
- UV package manager (CLI launcher)
- mcp framework – handles MCP protocol
- markitdown – document conversion
- pdf2image + poppler – PDF → image
- pytesseract + Tesseract – image → text
- tiktoken – token counting
- python-dotenv – environment configuration

##### Don’t over-complicate
- Logical component once; don’t drill into lines of code.
- Every util module’s responsibility at a high level.
- It’s immediately clear how a request enters the system, how/where it’s processed, and how the response is returned.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client and Launcher
    Client["MCP Client\n(Claude)"]:::client
    CLI["UV CLI Launcher"]:::client
    Client -->|"start"| CLI

    %% Config & Metadata
    subgraph "Config & Metadata"
        DependencyDecl["pyproject.toml"]:::fs
        DependencyLock["uv.lock"]:::fs
        Instructions["src/instructions.md"]:::fs
        README["README.md"]:::fs
    end
    CLI -->|uses| DependencyDecl
    CLI -->|uses| DependencyLock
    CLI -->|references| Instructions
    CLI -->|references| README

    %% Python Server and Components
    subgraph "Python MCP Server"
        PythonServer["server.py\n(Entrypoint)"]:::core
        ArgParser["CLI Parser"]:::core
        MCPHandler["MCP Framework Handler"]:::core
        subgraph "Business Logic"
            PathFiles["path_files.py"]:::core
            Markitdown["markitdown.py"]:::core
            OCR["ocr.py"]:::core
            MaxTokens["max_tokens.py"]:::core
            Prompts["prompts.py"]:::core
        end
    end

    CLI -->|"launch"| PythonServer
    PythonServer --> ArgParser
    ArgParser --> MCPHandler

    MCPHandler --> PathFiles
    MCPHandler --> Markitdown
    MCPHandler --> OCR
    MCPHandler --> MaxTokens
    MCPHandler --> Prompts

    %% External Libraries & Binaries
    subgraph "External Libraries & Binaries"
        MarkitdownLib["markitdown lib"]:::external
        MCPFramework["mcp framework"]:::external
        PDF2Image["pdf2image"]:::external
        OpenCV["OpenCV"]:::external
        PyTesseract["pytesseract"]:::external
        Tiktoken["tiktoken"]:::external
        DotEnvLib["python-dotenv"]:::external
        PopplerBin["Poppler exes"]:::external
        TesseractBin["Tesseract OCR engine"]:::external
    end

    Markitdown -->|uses| MarkitdownLib
    MCPHandler -->|via| MCPFramework
    OCR -->|uses| PDF2Image
    OCR -->|uses| OpenCV
    OCR -->|uses| PyTesseract
    OCR -->|calls| PopplerBin
    OCR -->|calls| TesseractBin
    MaxTokens -->|uses| Tiktoken
    PythonServer -->|loads| DotEnvLib

    %% File System
    FS["User Document Directory"]:::fs
    EnvConfig[".env"]:::fs

    PathFiles -->|reads| FS
    Markitdown -->|reads/writes| FS
    OCR -->|reads/writes| FS
    PythonServer -->|loads| EnvConfig

    %% Alternative Entrypoint
    MainEntrypoint["main.py"]:::core
    CLI -->|alt entrypoint| MainEntrypoint

    classDef client fill:#ADD8E6,stroke:#000
    classDef core fill:#98FB98,stroke:#000
    classDef external fill:#FFA500,stroke:#000
    classDef fs fill:#D3D3D3,stroke:#000

    %% Click Events
    click PythonServer "https://github.com/baronco/local-docs-mcp-tool/blob/master/server.py"
    click MainEntrypoint "https://github.com/baronco/local-docs-mcp-tool/blob/master/main.py"
    click EnvConfig "https://github.com/baronco/local-docs-mcp-tool/blob/master/.env"
    click DependencyDecl "https://github.com/baronco/local-docs-mcp-tool/blob/master/pyproject.toml"
    click DependencyLock "https://github.com/baronco/local-docs-mcp-tool/blob/master/uv.lock"
    click Instructions "https://github.com/baronco/local-docs-mcp-tool/blob/master/src/instructions.md"
    click README "https://github.com/baronco/local-docs-mcp-tool/blob/master/README.md"
    click PathFiles "https://github.com/baronco/local-docs-mcp-tool/blob/master/utils/path_files.py"
    click Markitdown "https://github.com/baronco/local-docs-mcp-tool/blob/master/utils/markitdown.py"
    click OCR "https://github.com/baronco/local-docs-mcp-tool/blob/master/utils/ocr.py"
    click MaxTokens "https://github.com/baronco/local-docs-mcp-tool/blob/master/utils/max_tokens.py"
    click Prompts "https://github.com/baronco/local-docs-mcp-tool/blob/master/utils/prompts.py"
```
