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

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

CI/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 branch
• Deploy to Cloud Run (.github/workflows/deploy_main.yaml): Automatically deploys to Google Cloud Run on push to main branch