Gal-Gilor/markdown-mcp
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.
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 Markdowntext
into a list ofSection
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
- Code Block Processing: Protects
#
comments in fenced code blocks - Header Detection: Uses regex pattern
^(#+)\s+(.+)$
to find headers - Hierarchy Building: Maintains parent-child relationships using a stack
- Sibling Detection: Groups headers at same level with same parent
- 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 lintingmake test
: Run pytest test suitepython 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