FastAPI-MCP built from scratch

v0.1.0 - Custom MCP Server Foundation 🎓

Release Date: November 6, 2025

📝 Overview

First stable release of the Lecture MCP Server - a FastAPI-based implementation of the Model Context Protocol (MCP) built from scratch to deeply understand the protocol specification. This release establishes the foundational architecture for processing lecture materials from PDFs into structured, AI-ready content.

✨ What's Included

🏗️ Core Architecture

• Custom MCP Protocol Implementation: Built from scratch following the MCP specification
  • REST-based API endpoints for tool discovery and execution
  • Pydantic models for request/response validation
  • Custom tool registry system with dynamic tool loading

🛠️ MCP Tool Infrastructure

Tool Registry System (app/services/mcp_registry.py):

• Dynamic tool discovery and registration
• Tool schema validation and documentation
• Async tool execution with error handling
• Tool metadata management (versioning, parameters, descriptions)

Base Tool Framework (app/mcp_tools/base.py):

• Abstract base class for all MCP tools
• Standardized tool interface (schema definition + execution)
• Built-in parameter validation
• Support for multiple parameter types (string, file, object, array, etc.)

📦 Implemented Tools

1. PDF to Text (pdf_to_text)

   • Extract text from PDF files with intelligent chunking
   • Base64 PDF input support
   • Configurable chunk size and overlap
   • Returns structured chunks with metadata

2. Text to Markdown (text_to_markdown)

   • Convert plain text to well-formatted Markdown
   • LaTeX formula preservation ($...$ and $$...$$)
   • Heading detection and hierarchy
   • List and code block formatting

🌐 REST API

MCP Endpoints (/api/mcp/*):

• GET /api/mcp/tools - Discover all available tools
• GET /api/mcp/tools/{tool_name} - Get specific tool schema
• POST /api/mcp/tools/execute - Execute a tool with parameters
• GET /api/mcp/health - Service health check

Features:

• OpenAPI/Swagger documentation (/api/docs)
• ReDoc alternative documentation (/api/redoc)
• Comprehensive error handling with HTTP status codes
• Request/response logging
• Execution time tracking

🔧 Configuration & Settings

• Environment-based configuration (.env support)
• Gemini API integration for AI features
• Configurable logging levels
• CORS support for web clients
• Hot reload for development

📚 Project Structure

lecture-mcp-server/
├── app/
│   ├── api/              # API routes and endpoints
│   │   └── mcp.py        # MCP protocol endpoints
│   ├── core/             # Core configuration
│   │   └── config.py     # Settings and environment
│   ├── mcp_tools/        # MCP tool implementations
│   │   ├── base.py       # Base tool class
│   │   ├── pdf_to_text.py
│   │   ├── text_to_markdown.py
│   │   └── filter_content.py
│   ├── models/           # Pydantic models
│   │   └── mcp.py        # MCP protocol models
│   ├── services/         # Business logic
│   │   └── mcp_registry.py
│   └── utils/            # Utilities
│       ├── chunker.py    # Text chunking
│       └── gemini_client.py
├── tests/                # Test suite
└── docs/                 # Documentation

🎯 Learning Outcomes

This release represents a ground-up implementation of the MCP protocol to achieve:

✅ Deep Protocol Understanding: Built custom implementation following MCP spec
✅ Tool Architecture Design: Created extensible tool registry and base classes
✅ FastAPI Integration: REST API with proper async handling
✅ Type Safety: Full Pydantic validation for all models
✅ Error Handling: Comprehensive exception handling and logging

🔜 What's Next (v0.2.0)

The next release will migrate to the official MCP Python SDK while preserving all custom tool implementations:

• Replace custom protocol handler with mcp.server.Server
• Adopt mcp.types for standard compliance
• Add stdio/SSE transport support
• Maintain backward compatibility with REST API
• Focus on tool implementation rather than protocol details

🚀 Getting Started

Installation

# Clone repository
git clone https://github.com/yourusername/lecture-mcp-server
cd lecture-mcp-server

# Install dependencies with uv
uv sync

# Configure environment
cp .env.example .env
# Add your GEMINI_API_KEY to .env

# Run server
uv run python run.py

Quick Test

# Check server health
curl http://localhost:8000/api/health

# Discover tools
curl http://localhost:8000/api/mcp/tools

# Execute PDF to Text tool
curl -X POST http://localhost:8000/api/mcp/tools/execute \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "pdf_to_text",
    "parameters": {
      "file_data": "base64_encoded_pdf_here"
    }
  }'

API Documentation

Visit http://localhost:8000/api/docs for interactive Swagger UI

📖 Documentation

• Installation Guide
• API Reference
• MCP Protocol Spec

🐛 Known Limitations

• HTTP-only: No stdio/SSE transport yet (coming in v0.2.0)
• Custom Format: Not yet compatible with standard MCP clients like Google ADK (will be fixed in v0.2.0)
• Single Server: No clustering or load balancing support