bagasta/mcp-server

FastMCP Server

Production-ready Model Context Protocol server built on top of FastMCP. It exposes a set of demo tools (calculator, web search, web fetch) and ships with a Playground UI for interactive testing.

Features

• 🚀 Powered by FastMCP's high-level MCP abstractions
• 🔧 Decorator-based tool registration with automatic schema generation
• 🧪 Comprehensive pytest suite with in-memory FastMCP client tests
• 🖥️ Web playground for exercising tools without writing a client
• 🧾 PDF generation from HTML/Markdown templates with pluggable rendering engines
• ⚙️ Environment-driven configuration for tool toggles and timeouts

Quick Start

1. Install dependencies

   pip install -r requirements.txt
   

2. Configure environment

   cp .env.example .env
   # Edit .env to suit your environment
   

3. Run the MCP server (choose either command)

   # Using Python directly
   python -m src.server
   
   # Or via the FastMCP CLI (adds uvicorn/stdio helpers)
   fastmcp run src/server.py
   

4. Launch the Playground UI (optional)

   python start_playground.py
   # Open http://localhost:8080
   

LangChain SSE Verification

export MCP_BEARER_TOKEN=jango
fastmcp run src/server.py --transport sse --host 0.0.0.0 --port 8080

In another terminal:

# Stream the MCP handshake and keep-alive frames
curl -N -H "Authorization: Bearer jango" http://localhost:8080/mcp/stream | head

# Invoke the calculator tool over HTTP
curl -X POST http://localhost:8080/tools/calculator/call \
  -H "Authorization: Bearer jango" \
  -H "Content-Type: application/json" \
  -d '{"arguments":{"expression":"6*7"}}'

The SSE stream should emit data: {...} frames for the initialize result, the tools/list payload, and periodic ping messages. The calculator call should return JSON containing "result": "42".

Adding New Tools

Tools are plain Python functions decorated with @mcp.tool. Schemas are inferred from type hints and default values.

# src/server.py
from fastmcp import Context
from src.server import mcp

@mcp.tool(name="greet", description="Return a friendly greeting")
def greet(name: str, excited: bool = False) -> str:
    message = f"Hello, {name}!"
    return message.upper() if excited else message

Set MCP_ENABLED_TOOLS_CONFIG in .env to control which tools are registered at import time.

PDF Generation Tool

The pdf.generate tool renders PDF documents from HTML or Markdown templates:

• Provide a template string and optional variables (dict or JSON string) for templating via Jinja2.
• Pick content_type="markdown" to auto-convert Markdown into HTML before rendering.
• Choose a rendering engine with the engine parameter:
  • weasyprint (default) — install with pip install weasyprint and ensure Cairo/Pango system libraries are available.
  • wkhtmltopdf — install with pip install pdfkit and the wkhtmltopdf binary on your PATH.
• Set output_format="base64" to receive the PDF bytes inline, or "path" with output_path to write to disk (defaults to playground/generated_pdfs/).

Markdown support relies on the markdown package (pip install markdown). If an engine dependency is missing, the tool returns a helpful error message instead of failing silently.

Testing

pytest tests/

Documentation

• how-to-use.md — end-to-end usage guide
• docs/ — extended documentation on configuration, deployment, testing, and the playground