-
security-
license-
qualityA minimal fastmcp demonstration server that provides a simple addition tool through the MCP protocol, supporting deployment via Docker with multiple transport modes.
Last updated -
2
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 settingsinfo://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 tokenDOCKERHUB_USERNAME- Docker Hub usernameDOCKERHUB_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
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
A demonstration MCP server built with FastMCP v2.0 that provides basic mathematical calculations and greeting functionality. Features Docker containerization, comprehensive testing, and CI/CD automation for learning MCP development patterns.
Related MCP Servers
- Asecurity-licenseAqualityA starter template for building MCP servers with FastMCP, providing testing, linting, formatting, and NPM publishing setup.Last updated -10MIT License
- Asecurity-licenseAqualityA FastMCP server for mathematical computations, including numerical and symbolic calculations with NumPy and SymPy integration, as well as data visualization through Matplotlib.Last updated -125MIT License
- Asecurity-licenseAqualityA 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