markdown-mcp
Provides a tool for splitting Markdown documents into hierarchical sections, preserving header nesting (H1 → H2 → H3), parent-child and sibling relationships, and per-section metadata such as parent references, character offsets/spans, and character counts, while ignoring '#' comments inside fenced code blocks.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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. 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. The project includes automated testing and deployment via GitHub Actions workflows.
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
Related MCP server: nodiom-mcp
Features
Core Functionality
Hierarchical Splitting: Maintains header relationships (H1 → H2 → H3...)
Sibling Navigation: Sections that share a
parent_idare siblingsCode-Aware Processing: Ignores
#comments in fenced code blocksRich Metadata: Includes parent references and character offsets into the input
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
CI/CD: Automated testing and deployment via GitHub Actions
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.pyUsage
To run the MCP server (if the environment is activated):
python src/main.pyIf the environment is not activated, you can run using Poetry:
poetry run python src/main.pyThe 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 Markdowntextinto a list ofSectionobjects.{ "header": "Getting Started", "content": "Install it.", "level": 2, "metadata": { "id": 1, "parent_id": 0, "parents": {"h1": "Introduction"}, "span": [25, 55], "char_count": 30 } }levelis0for text before the first header.metadata.idis the section's position in document order,parent_idis the id of the enclosing section (nullat the top level), andspanis the[start, end)character range of the section in the inputtext. Siblings are the sections that share the sameparent_id.Example Request:
curl -X POST http://localhost:8080/server/mcp/ \ -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
└── settings.py # Logging configuration
tests/
├── conftest.py # Test fixtures
└── test_splitter.py # split_text tool testsChunking is provided by the markdown-chunkify library; this server wraps it as an MCP tool and returns its Section model unchanged.
Key Components
FastMCP Integration: Uses
@mcp.tooldecorator to expose functions as MCP toolsmarkdown-chunkify: Splits Markdown into hierarchical sections and ignores
#comments in fenced code blocksCached Splitter: One immutable
MarkdownSplitterinstance is shared across requests
Development
Setup
python -m venv .venv && source .venv/bin/activate
poetry installCommands
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.pyCI/CD
The project includes GitHub Actions workflows for automated testing and deployment:
Execute Tests (
.github/workflows/execute_main_tests.yaml): Runs pytest test suite on push/PR to main branchDeploy to Cloud Run (
.github/workflows/deploy_main.yaml): Automatically deploys to Google Cloud Run on push to main branch
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
High-fidelity PDF to structured Markdown conversion and document field extraction.
PDF, Word, PowerPoint, Excel, HTML, EPUB to clean Markdown for LLMs/RAG; OCR for scans; chunks.
Converts PDF, scans, DOCX, XLSX and PPTX to Markdown with tables and page-aware RAG chunks.
Convert PDFs, Office docs, websites and audio into AI-ready Markdown, then search and ask your docs.
Related MCP Servers
- AlicenseAqualityCmaintenanceEnables AI assistants to navigate and query hierarchical documentation structures, supporting markdown files with YAML metadata and OpenAPI 3.x specifications. It features intelligent full-text search, metadata filtering, and a built-in web interface for both human and AI-driven documentation access.6MIT
- AlicenseAqualityCmaintenanceEnables AI agents to read, write, append, and delete content in Markdown files using structural selectors, without regex or string hacking.724 npm5MIT
- AlicenseNot gradedqualityBmaintenanceEnables vectorless RAG by letting LLM clients like Claude and Cursor parse documents, inspect outlines, and retrieve specific sections with heading breadcrumbs. Supports PDF, Word, HTML, and PowerPoint without LLM calls or heavy ML models.105 PyPI36AGPL 3.0
- FlicenseNot gradedqualityDmaintenanceTurns a directory of markdown documentation into searchable, citable tools for AI assistants, enabling targeted retrieval of specific sections with stable references.-