Basemcpserver

🚀 Base Server Docker Image

This base image is specifically designed for running MCP servers, supporting communication via HTTP and standard input/output (stdin/stdout). It's implemented in Python, based on the Starlette framework and Uvicorn server.

✨ Features

• Two communication modes:
  • HTTP/SSE: Enables Server-Sent Events (SSE) communication via the HTTP protocol.
  • Standard Input/Output (_stdio): Allows direct communication through stdin and stdout.
• Automated API documentation and interactive testing: Generates API documentation automatically and provides an interactive testing interface.

Core Components

• Starlette: A lightweight ASGI framework for handling HTTP requests.
• Uvicorn: An ASGI server for running Starlette applications.
• Python native I/O: Used for the standard input/output mode.

🚀 Quick Start

Running Examples

Using Docker

1. Pull the image:

   docker pull yourusername/base-mcp-server:latest
   

2. Run the container in HTTP mode:

   docker run -p 7501:7501 yourusername/base-mcp-server:latest
   

3. Or run it in standard input/output mode:

   docker run --rm -it yourusername/base-mcp-server:latest stdio
   

Using the build script

./build.sh build

Example Project Structure

your-project/
├── requirements.txt                 # Project dependencies
├── Dockerfile                       # Docker file
├── config.py                        # Configuration file
└── your_server.py                   # Server implementation

📦 Installation

Installation Steps

1. Pull the image:

   docker pull yourusername/base-mcp-server:latest
   

2. Run the container in HTTP mode:

   docker run -p 7501:7501 yourusername/base-mcp-server:latest
   

3. Or run it in standard input/output mode:

   docker run --rm -it yourusername/base-mcp-server:latest stdio
   

Configuration

Environment Variables

• HOST: The interface to bind to, default is 0.0.0.0.
• PORT: The port to listen on, default is 7501.
• API_KEY: Required for authentication.
• SERVER_NAME: The unique identifier for the server.

Configuration Methods

1. Using command-line environment variables

docker run -p 7501:7501 \
  -e API_KEY=your_api_key \
  -e SERVER_NAME=your-mcp-server \
  yourusername/your-mcp-server:latest

2. Using an environment file

Create a .env file:

API_KEY=your_api_key
SERVER_NAME=your-mcp-server
HOST=0.0.0.0
PORT=7501

Run the container with the environment file:

docker run -p 7501:7501 --env-file .env yourusername/your-mcp-server:latest

3. Using Docker Secrets

Configure the secret:

docker secret create api_key your_api_key

Reference the secret when running the container:

docker run -p 7501:7501 -e API_KEY=$(docker secret inspect --format='{{.Data}}' api_key) yourusername/your-mcp-server:latest

💻 Usage Examples

Basic Usage

You can run the server using Docker or the build script as shown in the quick start section.

Advanced Usage

Extending Server Functionality

You can easily extend the server functionality by inheriting the BaseMCPServer class:

from base_mcp_server import BaseMCPServer

class MyMCPServer(BaseMCPServer):
    def __init__(self, config):
        super().__init__(config)
        # Add custom initialization code

Automated Documentation Generation

After starting the server, visit http://localhost:7501/docs to view the automated API documentation.

Interactive Testing Interface

After starting the server, visit http://localhost:7501/test for interactive testing.

🔧 Technical Details

The server uses the Starlette framework and Uvicorn server to handle HTTP requests and run the application. It supports two communication modes: HTTP/SSE and standard input/output. By inheriting the BaseMCPServer class, users can easily extend the server's functionality.

📄 License

This project is licensed under the MIT License.
Copyright (c) 2024, Your Name.

⚠️ Important Note

Sensitive information such as API keys should not be passed directly via environment variables. It's recommended to use Docker Secrets. Also, by default, the container binds to all interfaces (HOST=0.0.0.0), so make sure appropriate network security policies are set in the production environment.