# FastMCP Server

Production-ready [Model Context Protocol](https://modelcontextprotocol.io) server built on top of [FastMCP](https://gofastmcp.com). 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**
   ```bash
   pip install -r requirements.txt
   ```

2. **Configure environment**
   ```bash
   cp .env.example .env
   # Edit .env to suit your environment
   ```

3. **Run the MCP server** (choose either command)
   ```bash
   # 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)
   ```bash
   python start_playground.py
   # Open http://localhost:8080
   ```

## LangChain SSE Verification

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

In another terminal:

```bash
# 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.

```python
# 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

```bash
pytest tests/
```

## Documentation

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