What is Lightspeed Mcp

lightspeed_mcp is an integration package that combines FastAPI and FastMCP, enabling dynamic, modular, and scalable workflows for Large Language Models (LLM) and Model Context Protocol (MCP). It features automatic discovery of tools, resources, and prompts.

Use cases

Use cases for lightspeed_mcp include building scalable web applications that utilize LLMs, creating dynamic APIs for image processing, and developing modular systems for resource management in AI projects.

How to use

To use lightspeed_mcp, place the ‘model_context_protocol’ directory at the root of your FastAPI application folder. This allows the MCP server to automatically detect and integrate with your FastAPI app, facilitating seamless operation.

Key features

Key features include integration of FastAPI with FastMCP, automatic discovery and registration of Python modules, type-checked and extensible design, and support for LLM, context, and image workflows.

Where to use

lightspeed_mcp can be used in various fields such as web development, machine learning, and artificial intelligence, particularly in applications requiring dynamic tool and resource management.

Model Context Protocol (MCP) Integration Guide

Overview

This package demonstrates a robust integration between FastAPI and FastMCP, enabling dynamic, modular, and scalable LLM/MCP workflows. It features automatic registration of tools, resources, and prompts for seamless extension.

Key Features

• FastAPI + FastMCP Integration:

  • Leverages FastMCP.from_fastapi() to expose all FastAPI endpoints as MCP resources/tools via OpenAPI.

• Automatic Discovery & Import:

  • All Python modules in tools/image/, prompts/image/, and resources/ are dynamically imported and registered with MCP at server startup.
  • No manual import maintenance required—just add new modules to the correct folders.

• Type-Checked, Extensible Design:

  • All tools, resources, and prompts use Python type hints for clarity and safety.
  • Modular structure supports rapid extension and testing.

• LLM/Context/Image Support:

  • Tools/resources can use Context for logging, progress, and LLM sampling.
  • Image support for image data workflows.

• Production-Ready

  • Containerized deployment with Docker
  • Async/await support for high concurrency

• ** Secure by Default**

• All communications are secured with SSL/TLS by default. Ensure SSL is enabled in your deployment configuration (e.g., via a reverse proxy like NGINX or an HTTPS-enabled API gateway).-

🚫 Blocked Routes
To protect sensitive internal APIs, the following route prefixes are explicitly excluded and inaccessible from the public-facing API:

/system

/service

/mcp_deny

Build and run

docker build -t mcp-server -f app/mcp_server/docker/Dockerfile .
docker run -d -p 8000:8000 --name mcp-server mcp-server

Directory Structure

mcp_server/
├── _docs/                     # Comprehensive documentation
│   ├── concepts/              # Core concepts and architecture
│   ├── examples/              # Usage examples
│   ├── quick-start/           # Getting started guides
│   └── sdk/                   # SDK reference
├── _tests/                    # Test suite
├── context/                   # Context management
│   └── _examples/             # Context usage examples
├── docker/                    # Docker deployment files
│   ├── Dockerfile             # Production Dockerfile
│   └── mcp-server-ssl.conf    # SSL configuration
├── prompts/                   # Prompt templates
│   └── _examples/             # Example prompts
├── resources/                 # MCP resources
│   └── _examples/             # Example resources
├── tools/                     # MCP tools
│   └── _examples/             # Example tools
└── server.py                  # Main MCP server entry point

Placement: Add to Root of Your App Folder

For MCP to automatically detect and integrate with your FastAPI application, you must place the model_context_protocol directory at the root of your FastAPI app folder (typically where your main FastAPI app module lives, e.g., app/).

• This ensures that server.py can correctly locate and import your FastAPI app (e.g., app.api.main:app).
• If you move the model_context_protocol folder, update the import paths in server.py accordingly.

Example Structure:

app/
├── api/
│   └── main.py    # <-- Your FastAPI app instance (app = FastAPI(...))
├── model_context_protocol/
│   ├── server.py
│   └── ...

Why?

• The MCP server relies on relative imports to dynamically integrate with your FastAPI app.
• Placing model_context_protocol at the app root ensures seamless OpenAPI and MCP integration.

Getting Started

1. Add this directory (model_context_protocol/) to the root of your FastAPI app folder.
   • This is required for automatic discovery and integration (see directory structure example above).
   • Your FastAPI app instance should be importable as app.api.main:app by default.
2. Install requirements:
   • Python 3.9+
   • fastapi, fastmcp, and all dependencies listed in your environment.
3. Run the MCP server:
   • Use python model_context_protocol/server.py or fastmcp run model_context_protocol/server.py.

How Integration Works

1. FastAPI + FastMCP

• server.py imports your FastAPI app and passes it to FastMCP.from_fastapi, exposing all FastAPI endpoints as MCP tools/resources.

2. Automatic Module Import

• At startup, server.py uses pkgutil and importlib to dynamically import all modules in:
  • tools/
  • prompts/
  • resources/
• This ensures that any MCP-decorated function (@mcp.tool, @mcp.resource, @mcp.prompt) in these modules is auto-registered with the MCP server.
• To add new functionality: just drop a .py file with MCP-decorated functions into the appropriate folder—no need to edit server.py.

3. Context, Image, and Advanced Features

• Tools/resources can use Context for:
  • Logging (ctx.info, ctx.error)
  • Progress reporting (ctx.report_progress)
  • LLM sampling (ctx.sample)
• Support for Image return types for image workflows.

Advanced Usage & Features

• For advanced features, integration patterns, and full reproducibility examples, see _docs/context_integration_examples.md.
• Highlights include:
  • LLM Sampling: Use await ctx.sample(...) in tools/resources to request completions from the client LLM.
  • Progress Reporting: Use await ctx.report_progress(current, total) for long-running tasks.
  • Multi-message Prompts: Return a list of UserMessage/AssistantMessage in prompt modules for richer LLM guidance.
  • Dynamic Resources & Pydantic Inputs: See _docs for examples on dynamic resource templates and complex tool schemas.
  • Server Composition/Proxy: See example modules for mounting or proxying other MCP servers.
  • Integration/E2E Testing: Full test scripts and usage instructions are documented in _docs.

Example: Adding a New Tool

1. Create a new file in tools/tool.py, e.g. resize_tool.py:

   from fastmcp import mcp
   
   @mcp.tool()
   def resize_image(image_path: str, width: int, height: int) -> str:
       """Resize an image and return the new file path."""
       # ... your logic here ...
       return new_path
   

2. Restart your MCP server. The new tool will be auto-registered and available to all MCP clients.

Contributing

• Follow DRY, SOLID, and clean code principles.
• Use type hints, write tests, and document your tools/resources.

Credits

• Inspired by The Pragmatic Programmer and The Clean Coder.
• Built by Ty the Programmer Ty The Programmer.

Requirements

• Python 3.9+
• fastapi, fastmcp, and dependencies installed in your environment.