flexberry-markitdown-mcp CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Flexberry MarkItDown MCP Server — MCP-сервер для двунаправленной конвертации документов: любой формат → Markdown (через Microsoft MarkItDown) и Markdown → PDF (через Playwright/WeasyPrint). Транспорт — stdio. Python 3.10+.

Commands

# Install in development mode (all test/lint deps)
pip install -e ".[dev]"

# Install with both PDF backends
pip install -e ".[weasyprint]"
playwright install chromium

# Run all tests
pytest

# Run a single test file / class / function
pytest tests/test_converter.py
pytest tests/test_converter.py::TestMarkdownToHtml::test_table
pytest tests/test_server.py::TestServerTools::test_call_tool_convert_to_pdf_basic

# Lint
ruff check src/
ruff format --check src/

# Auto-fix lint and format
ruff check --fix src/
ruff format src/

# Run server locally (for MCP client testing)
python -m flexberry_markitdown_mcp.server

Architecture

Pipeline: Any → Markdown → PDF

The server exposes 5 MCP tools. Two core conversion pipelines:

convert_to_markdown — delegates entirely to MarkItDown.convert(). Result is saved to disk via atomic write (temp file + rename). Handles Unicode/Cyrillic filenames through NFC/NFD normalization (resolve_existing_file).

convert_to_pdf — three-step pipeline in converter.py:

1. markdown_to_html() — markdown-it-py (commonmark preset + table/strikethrough rules) + mdit-py-plugins (tasklists, frontmatter) + Pygments syntax highlighting
2. build_html_document() — wraps HTML body in a full document with GitHub-like CSS from styles.py
3. html_to_pdf_playwright() or html_to_pdf_weasyprint() — writes HTML to a temp file, loads via file:// URL, generates PDF

Key Module Boundaries

• server.py — MCP server setup, tool definitions, request routing. All tool handlers run blocking I/O via run_in_executor to avoid blocking the asyncio event loop. Logging goes to ~/.flexberry-markitdown-mcp/server.log (not stdout, since stdout is MCP transport).
• converter.py — Pure conversion logic (no MCP dependency). Top-level entry points: convert_md_to_pdf(text) and convert_md_file_to_pdf(path). Chromium auto-install mirrors vscode-markdown-pdf behavior (ensure_chromium).
• styles.py — DEFAULT_PDF_STYLES (GitHub-like CSS) and get_pygments_css() (auto-generated from Pygments formatter, cached).