MCP Server with FastMCP v2.0

A Model Control Protocol (MCP) server implementation using FastMCP v2.0, featuring Docker containerization, comprehensive testing, and CI/CD automation.

Features

🚀 Built with FastMCP v2.0
🐳 Docker containerization with multi-stage builds
📦 Modern Python packaging with uv
🧪 Comprehensive test suite with pytest
🔄 GitHub Actions CI/CD pipeline
🛡️ Security scanning and dependency management
📊 Code coverage reporting
🔧 Automated code formatting and linting

Quick Start

Prerequisites

Python 3.10+
uv for dependency management
Docker (optional, for containerization)

Installation

Clone the repository:

git clone <repository-url> cd nikolas-mcp

Install dependencies using uv:

uv sync

Run the server:

uv run python -m mcp_server.main

Using Docker

Build the Docker image:

docker build -t mcp-server .

Run the container:

docker run -p 8000:8000 mcp-server

Or use docker-compose:

docker-compose up

Available Tools

The MCP server provides the following tools:

`calculate`

Evaluates mathematical expressions safely.

Parameters:

expression (string): Mathematical expression to evaluate

Example:

{ "tool": "calculate", "arguments": { "expression": "2 + 3 * 4" } }

`greet`

Generates friendly greeting messages.

Parameters:

name (string): Name of the person to greet

Example:

{ "tool": "greet", "arguments": { "name": "World" } }

Resources

config://settings - Server configuration settings
info://server - General server information

Prompts

help - Display help information about available capabilities

Development

Setup Development Environment

# Install development dependencies uv sync --dev # Install pre-commit hooks uv run pre-commit install

Running Tests

# Run all tests uv run pytest # Run tests with coverage uv run pytest --cov=src --cov-report=html # Run specific test file uv run pytest tests/test_main.py -v

Code Quality

# Format code uv run ruff format . # Lint code uv run ruff check . # Type checking uv run mypy src/

Project Structure

nikolas-mcp/ ├── src/ │ └── mcp_server/ │ ├── __init__.py │ ├── main.py # Main server implementation │ └── server.py # Server utilities and config ├── tests/ │ ├── __init__.py │ ├── conftest.py # Pytest configuration │ ├── test_main.py # Main functionality tests │ ├── test_server.py # Server utilities tests │ └── test_integration.py # Integration tests ├── .github/ │ └── workflows/ │ ├── ci.yml # CI/CD pipeline │ └── dependabot.yml # Dependabot auto-merge ├── Dockerfile ├── docker-compose.yml ├── pyproject.toml # Project configuration └── README.md

CI/CD Pipeline

The project includes a comprehensive GitHub Actions pipeline:

Lint and Format: Runs ruff for code formatting and linting
Test Suite: Runs tests across multiple Python versions and OS platforms
Security Scan: Performs security vulnerability scanning
Docker Build: Builds and tests Docker images
Auto-publish: Publishes to PyPI and Docker Hub on release

Required Secrets

For full CI/CD functionality, configure these GitHub secrets:

PYPI_API_TOKEN - PyPI authentication token
DOCKERHUB_USERNAME - Docker Hub username
DOCKERHUB_TOKEN - Docker Hub access token

Configuration

Environment Variables

LOG_LEVEL - Logging level (default: INFO)
PYTHONPATH - Python path for module resolution

Server Configuration

The server can be configured via the ServerConfig class in src/mcp_server/server.py:

config = ServerConfig() config.max_connections = 200 config.timeout = 60

Docker Configuration

Multi-stage Build

The Dockerfile uses multi-stage builds for optimized image size:

Base stage: Sets up Python and system dependencies
Dependencies stage: Installs Python packages with uv
Runtime stage: Copies application code and runs the server

Health Checks

The container includes health checks to ensure the server is running correctly.

Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes
Run tests and ensure they pass
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

If you encounter any issues or have questions:

Check the Issues page for existing problems
Create a new issue with detailed information
Refer to the FastMCP documentation for FastMCP-specific questions

Deploy Server

A

security – no known vulnerabilities

F

license - not found

A

quality - confirmed to work

How are these scores calculated?

Related Resources

GitHub Repository

Need Help?

Report Issue

Tools

Related MCP Servers

MCP Demo Server
OmniMCP-AI
-
security
F
license
-
quality
A minimal fastmcp demonstration server that provides a simple addition tool through the MCP protocol, supporting deployment via Docker with multiple transport modes.
Last updated -
3
FastMCP Boilerplate
CrypticSplicer
A
security
A
license
A
quality
A starter template for building MCP servers with FastMCP, providing testing, linting, formatting, and NPM publishing setup.
Last updated -
1
2
MIT License
Fermat MCP
abhiphile
A
security
A
license
A
quality
A FastMCP server for mathematical computations, including numerical and symbolic calculations with NumPy and SymPy integration, as well as data visualization through Matplotlib.
Last updated -
12
7
MIT License
MCP Boilerplate Server
shazaaly
A
security
F
license
A
quality
A basic MCP server template built with FastMCP that provides simple tools for greeting users, performing math operations, and managing user information. Serves as a starting point for building custom MCP servers with essential functionality examples.
Last updated -
4

View all related MCP servers

Example MCP Server