What is Markdown Mcp

markdown-mcp is a Model Context Protocol (MCP) server that intelligently splits Markdown documents into hierarchical sections while preserving parent-child relationships and sibling connections.

Use cases

Use cases for markdown-mcp include splitting complex Markdown documents into manageable sections for better readability, generating structured data from Markdown for APIs, and enhancing Markdown editing tools with intelligent section handling.

How to use

To use markdown-mcp, clone the repository, set up a Python virtual environment, install dependencies using Poetry, and run the server with the command ‘python src/main.py’. The server will be accessible at ‘http://0.0.0.0:8080’.

Key features

Key features include hierarchical splitting of Markdown headers, sibling detection for headers at the same level, code-aware processing that ignores comments in code blocks, compliance with the Model Context Protocol, and high performance powered by FastAPI.

Where to use

markdown-mcp can be used in various fields such as documentation generation, content management systems, educational platforms, and any application that requires structured handling of Markdown documents.

Markdown MCP

A Model Context Protocol (MCP) server that intelligently splits Markdown documents into hierarchical sections while preserving parent-child relationships and sibling connections.

Features

• Hierarchical splitting: Maintains header relationships (H1 → H2 → H3…).
• Sibling detection: Identifies headers at the same level.
• Code-aware: Ignores # comments in code blocks.
• MCP compliant: Standard Model Context Protocol interface.
• FastAPI powered: High-performance async server.

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:

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."
        }
        }
    }'
    

Development

This project includes a Makefile to simplify common development tasks.

• make lint: Run ruff to check for linting issues.
• make test: Run tests using pytest.

Running Tests

This project uses pytest for testing. To run the tests:

poetry run pytest

Alternatively, you can use the Makefile:

make test