MCP Server Tools

A simple Model Context Protocol (MCP) server that provides datetime and calculator tools. Built with FastMCP for easy development and deployment.

🏗️ Architecture

The project follows a layered architecture pattern:

mcp_server_tools/
├── main.py                    # Entry point (Presentation Layer)
├── src/                       # Implementation folder
│   ├── tools/                 # MCP interface layer
│   │   ├── datetime_tool.py   # DateTime MCP tools
│   │   └── calculator_tool.py # Calculator MCP tools
│   ├── services/              # Business logic layer
│   │   ├── datetime_service.py # DateTime business logic
│   │   └── calculator_service.py # Calculator business logic
│   ├── server_manager.py      # Server execution management
│   └── logger_config.py       # Centralized logging
├── Dockerfile                 # Multi-stage Docker build
├── docker-compose.yml         # Development and production services
├── pyproject.toml            # Project configuration
└── .env                      # Environment variables (create from env.example)

Layer Responsibilities:

• Presentation Layer (main.py): MCP server setup and tool registration
• Tools Layer (src/tools/): MCP interface functions that handle protocol communication
• Services Layer (src/services/): Pure business logic, independent of MCP
• Server Management (src/server_manager.py): Development and production server execution

🚀 Quick Start

Prerequisites

• Python 3.12+
• uv package manager
• Docker and Docker Compose (for containerized deployment)

Local Development

1. Clone and setup:

   git clone <repository-url>
   cd mcp_server_tools
   cp env.example .env
   uv sync --dev
   

2. Development mode (stdio):

   uv run mcp dev main.py
   

   This starts the MCP Inspector for visual testing.

3. Production mode (SSE):

   uv run python main.py
   

   This starts the server with SSE transport on 0.0.0.0:8050.

Docker Deployment

1. Development:

   docker-compose --profile dev up
   

2. Production:

   docker-compose --profile prod up
   

🛠️ Available Tools

DateTime Tools

• datetime_tool(format: str = "iso"): Get current datetime

  • format="iso": ISO 8601 format (e.g., "2025-01-08T22:30:00.123456")
  • format="formatted": Human-readable format (e.g., "2025-01-08 22:30:00")

• timestamp_tool(): Get current timestamp as string

Calculator Tools

• calculator_tool(expression: str): Evaluate mathematical expressions

  • Examples: "2 + 3", "10 * 5", "100 / 4", "2 ** 8"

• operation_tool(a: float, b: float, operation: str): Perform operations on two numbers

  • Operations: +, -, *, /, **, %

• operations_list_tool(): List all supported mathematical operations

⚙️ Configuration

Environment variables (configure in .env file):

HOST=0.0.0.0              # Server host
PORT=8050                  # Server port
DEV_MODE=false             # Development mode
LOG_LEVEL=INFO             # Logging level
SERVER_NAME=mcp-server-tools # Server name

🔧 Development

Code Quality

# Format code
uv run ruff format .

# Lint code
uv run ruff check .

# Run tests
uv run pytest

Project Structure Benefits

• Separation of Concerns: Each layer has a specific responsibility
• Testability: Business logic is isolated and easily testable
• Maintainability: Clear organization makes code easier to understand
• Reusability: Services can be used outside of MCP context
• Scalability: Easy to add new tools and services

Adding New Tools

1. Create service in src/services/ (business logic)
2. Create tool in src/tools/ (MCP interface)
3. Register tool in main.py with @mcp.tool() decorator

🐳 Docker

Multi-stage Build

• Builder stage: Installs dependencies
• Production stage: Optimized for production
• Development stage: Includes development tools

Docker Compose Services

• mcp-server-dev: Development with volume mounts
• mcp-server-prod: Production with optimized image

📝 Logging

Structured logging with configurable levels:

• INFO: Application startup, tool execution
• DEBUG: Detailed operation information
• ERROR: Error conditions and exceptions

Logs are formatted and output to stdout for Docker compatibility.

🔒 Security

• Safe expression evaluation with restricted globals
• Input validation for all tools
• Non-root user in Docker containers
• Environment variable configuration

📚 Resources

• Model Context Protocol
• MCP Python SDK
• FastMCP Quickstart