markdown-mcp

Gal-Gilor/markdown-mcp

3.3

If you are the rightful owner of markdown-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

A Model Context Protocol (MCP) server designed to intelligently process and split Markdown documents while maintaining their structural integrity.

Tools
1
Resources
0
Prompts
0

Python Code style: black Ask DeepWiki

Markdown MCP Server

Learn MCP Development by Example šŸ“š
A complete, production-ready Model Context Protocol (MCP) server that demonstrates best practices for building intelligent document processing tools.

šŸŽÆ What is this?

This is a Model Context Protocol (MCP) server that intelligently splits Markdown documents into hierarchical sections while preserving parent-child relationships and sibling connections. Built with FastMCP and FastAPI, it serves as both a useful tool and an educational resource for developers learning to create their own MCP servers.

Why MCP?

The Model Context Protocol enables AI assistants to access external tools and data sources securely and efficiently. This server demonstrates how to:

  • Build MCP-compliant tools that AI models can use
  • Handle structured document processing
  • Maintain relationships in hierarchical data
  • Integrate with modern Python web frameworks

Features

Core Functionality

  • Hierarchical Splitting: Maintains header relationships (H1 → H2 → H3...)
  • Sibling Detection: Identifies headers at the same level for navigation
  • Code-Aware Processing: Ignores # comments in fenced code blocks
  • Rich Metadata: Includes parent references, sibling lists, and optional token counts

Technical Stack

  • MCP Compliant: Full Model Context Protocol interface support
  • FastAPI Powered: High-performance async server with automatic OpenAPI docs
  • Well Tested: Core splitting functionality covered with pytest
  • Type Safety: Complete type hints with Pydantic models
  • Docker Ready: Containerized deployment support

Requirements

  • Python >=3.12, <3.13

Quick Start

This project uses Poetry for dependency management. To get started:

git clone https://github.com/Gal-Gilor/markdown-mcp.git
cd markdown-mcp
python -m venv .venv && source .venv/bin/activate
poetry install
python src/main.py

Usage

To run the MCP server (if the environment is activated):

python src/main.py

If the environment is not activated, you can run using Poetry:

poetry run python src/main.py
  • The server will start on http://0.0.0.0:8080.

  • The MCP server is mounted at /server.

  • The MCP server is accessible at /server/mcp.

  • Available tools:

    • split_text(text: str) -> list[Section]: Splits the input Markdown text into a list of Section objects.

      {
          "section_header": "Getting Started",
          "section_text": "Welcome to the guide...",
          "header_level": 2,
          "metadata": {
              "parents": {"h1": "Introduction"},
              "siblings": ["Advanced Topics", "FAQ"]
          }
      }
      

      Example Request:

      curl -X POST http://localhost:8080/server/mcp/tools/call \
      -H "Content-Type: application/json" \
      -H "Accept: application/json, text/event-stream" \
      -d '{
          "jsonrpc": "2.0",
          "id": 1,
          "method": "tools/call",
          "params": {
          "name": "split_text",
          "arguments": {
              "text": "# Header 1\n\nSome content here.\n\n## Header 2\n\nMore content."
          }
          }
      }'
      

Architecture Overview

Project Structure

src/
ā”œā”€ā”€ main.py          # FastAPI app and MCP server setup
ā”œā”€ā”€ models.py        # Pydantic data models
└── splitter.py      # Core splitting logic

tests/
ā”œā”€ā”€ conftest.py      # Test fixtures
└── test_splitter.py # Splitter functionality tests

Key Components

  • FastMCP Integration: Uses @mcp.tool decorator to expose functions as MCP tools
  • Pydantic Models: Type-safe data structures with validation
  • Hierarchical Processing: Two-pass algorithm for building document structure
  • Code Block Protection: Regex-based approach to ignore comments in code

How It Works

  1. Code Block Processing: Protects # comments in fenced code blocks
  2. Header Detection: Uses regex pattern ^(#+)\s+(.+)$ to find headers
  3. Hierarchy Building: Maintains parent-child relationships using a stack
  4. Sibling Detection: Groups headers at same level with same parent
  5. Section Creation: Converts hierarchical structure to flat list of sections

Development

Setup

python -m venv .venv && source .venv/bin/activate
poetry install

Commands

  • make lint: Run ruff for code formatting and linting
  • make test: Run pytest test suite
  • python src/main.py: Start the development server

Testing

# Run all tests
poetry run pytest

# Run with verbose output
poetry run pytest -v

# Run specific test file
poetry run pytest tests/test_splitter.py