How baronco/local-docs-mcp-tool works
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.