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. split_text

    Splits the input Markdown text into a list of Section objects.

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