Calculator Tools Server

A containerized Model Context Protocol (MCP) server built with Python and FastMCP. This server provides practical utility tools for temperature conversion and percentage calculations through an HTTP-based interface.

Author: Yogesh Kadiya

Overview

This MCP server exposes multiple utility tools for common calculations and news fetching:

Available Tools

1. Celsius to Fahrenheit Converter

   • Function: convert_celsius_to_fahrenheit(celsius: float) -> str
   • Description: Converts temperature values from Celsius to Fahrenheit scale
   • Input: Temperature in degrees Celsius
   • Output: Formatted string with both Celsius and Fahrenheit values (2 decimal places)
   • Example: 120°C is equal to 248.00°F
   • Error Handling: Catches and reports conversion errors

2. Percentage Calculator

   • Function: calculate_percentage(part: float, total: float) -> str
   • Description: Calculates what percentage a given part represents of the total
   • Inputs:
     • part: The portion or subset value
     • total: The whole or 100% value
   • Output: Formatted string showing the percentage (2 decimal places)
   • Example: 25 is 50.00% of 50
   • Error Handling: Prevents division by zero errors

3. Latest News Fetcher

   • Function: get_latest_news(query: str = "technology", language: str = "en", max_results: int = 5) -> str
   • Description: Fetches the latest news articles based on a search query from NewsAPI
   • Inputs:
     • query: Search topic (e.g., "technology", "sports", "business", "python programming")
     • language: ISO 639-1 language code (default: "en" for English)
     • max_results: Maximum number of articles to return, 1-100 (default: 5)
   • Output: Formatted string containing article titles, descriptions, sources, publication dates, and URLs
   • Example: Returns top 5 articles about Python programming in English
   • Error Handling: Handles network timeouts, connection errors, and API errors gracefully

4. Top Headlines Fetcher

   • Function: get_top_headlines(country: str = "us", category: str = "general", max_results: int = 5) -> str
   • Description: Fetches top headlines for a specific country and category from NewsAPI
   • Inputs:
     • country: ISO 2-letter country code (e.g., "us", "uk", "in", "fr", "de", "ca")
     • category: News category - business, entertainment, general, health, science, sports, technology
     • max_results: Maximum number of articles to return, 1-100 (default: 5)
   • Output: Formatted string containing headline articles with details
   • Example: Returns top 5 technology headlines from the United States
   • Error Handling: Validates inputs and handles API errors

Additional Features

• Dynamic Greeting Resource: greeting://{name} - Provides personalized greetings
• Prompt Generation: Create greeting prompts in different styles (friendly, formal, casual)

News API Integration

The news fetching tools use NewsAPI.org (free tier) to provide real-time news data:

• API Endpoint: https://newsapi.org/v2/
• Free Tier: 100 requests per day
• Setup:
  1. Sign up for a free account at https://newsapi.org/
  2. Go to the API Keys section in your NewsAPI dashboard.
  3. Create a new API key if you don't already have one, or generate a replacement key when required.
  4. Set the environment variable for your runtime environment:
     • macOS/Linux: export NEWSAPI_KEY="your_api_key"
     • Windows PowerShell: $env:NEWSAPI_KEY = "your_api_key"
     • Docker: use -e NEWSAPI_KEY=your_api_key when running the container
  5. If no API key is set, the tools will use the default demo key with limited functionality.

Example Usage:

# Get latest technology news
get_latest_news("artificial intelligence", language="en", max_results=10)

# Get top headlines from the UK in sports category
get_top_headlines(country="uk", category="sports", max_results=5)

Project Structure

mcp-server/
├── server.py                    # Main FastMCP server with tool definitions
├── tools/
│   ├── __init__.py
│   ├── calculator.py            # Calculator tool implementations
│   └── server.py                # Flask application with socket handling
├── requirements.txt             # Python dependencies
├── Dockerfile                   # Container configuration
├── justfile                     # Local task runner commands
└── README.md                    # This file

Technologies Used

• FastMCP: FastAPI-based Model Context Protocol server framework
• Flask: Lightweight web framework for HTTP endpoints
• Python 3.11: Programming language and runtime
• Docker: Containerization for deployment
• uvicorn: ASGI server for HTTP transport
• Just: Simple task runner for project commands

Getting Started

Prerequisites

• Python 3.11 or higher
• Docker (optional, for containerized deployment)
• pip or uv package manager

Installation

1. Clone the Repository

   git clone https://github.com/yogeskk2/mcp-server.git
   cd mcp-server
   

2. Install Dependencies

   pip install -r requirements.txt
   

3. Set Environment Variables (Optional)

   export MCP_HOST=0.0.0.0
   export MCP_PORT=8000
   

Running the Server

Option 1: Direct Python Execution

python server.py

The server will start on http://localhost:8000 with streamable HTTP transport.

Option 2: Docker Container

1. Build the Docker Image

   docker build -t mcp-server .
   

2. Run the Container

   docker run -p 8000:8000 \
     -e MCP_HOST=0.0.0.0 \
     -e MCP_PORT=8000 \
     mcp-server
   

The server will be accessible at http://localhost:8000

Policy enforcement: None — OPA integration and policy rules have been removed from this repository.

Usage

Calling Tools

Once the server is running, you can invoke the tools via MCP client:

Example 1: Temperature Conversion

{
  "tool": "convert_celsius_to_fahrenheit",
  "arguments": {
    "celsius": 0
  }
}

Response: "0°C is equal to 32.00°F"

Example 2: Percentage Calculation

{
  "tool": "calculate_percentage",
  "arguments": {
    "part": 25,
    "total": 100
  }
}

Response: "25 is 25.00% of 100"

Server Endpoints

• Status Check: GET /status
  • Response: {"status": "MCP server is running"}
• Main MCP Handler: http://localhost:8000 (POST requests via streamable HTTP transport)

Configuration

Configuration settings are defined in tools/server.py:

HOST = '0.0.0.0'           # Server listening address
PORT = 5000                # Flask server port
DEBUG = True               # Debug mode

Environment Variables

• MCP_HOST: MCP server hostname (default: 0.0.0.0)
• MCP_PORT: MCP server port (default: 8000)

API Documentation

MCP Tools

Tool	Parameters	Returns	Purpose
convert_celsius_to_fahrenheit	celsius: float	str	Convert Celsius to Fahrenheit
calculate_percentage	part: float, total: float	str	Calculate percentage of part relative to total
store_news_article	title: str, url: str	str	Store a news article node in Neo4j
list_stored_articles	limit: int	str	List stored articles from Neo4j

Resources

Resource	Parameters	Purpose
greeting://{name}	name: str	Generate personalized greeting

Prompts

Prompt	Parameters	Purpose
greet_user	name: str, style: str	Create styled greeting prompts

Error Handling

Both calculation tools include robust error handling:

• Temperature Converter: Catches and reports conversion exceptions
• Percentage Calculator: Validates that total is not zero before calculation

Development

Project Layout

• Main Server: server.py - FastMCP server initialization and tool definitions
• Flask App: tools/server.py - Secondary HTTP server with socket handling
• Calculator Tools: tools/calculator.py - Calculator tool implementations

Adding New Tools

To add new tools to the MCP server, edit server.py and use the @mcp.tool() decorator:

@mcp.tool()
def your_tool(param1: str, param2: int) -> str:
    """Tool description"""
    # Implementation
    return result

Dependencies

See requirements.txt for a complete list. Key dependencies:

• mcp==1.27.1 - Model Context Protocol library
• Flask - Web framework
• uvicorn - ASGI server
• requests - HTTP client library
• numpy - Numerical computing
• pandas - Data manipulation
• flask-socketio - WebSocket support

Deployment

Docker Deployment

The project includes a Dockerfile for containerization. The image:

• Uses Python 3.11-slim as base
• Installs dependencies from requirements.txt
• Exposes port 8000
• Runs the MCP server on startup

Running Tests

To verify the server is working:

# After starting the server, in another terminal:
curl http://localhost:5000/status

Expected response:

{
  "status": "MCP server is running"
}

Troubleshooting

Issue	Solution
Port already in use	Change MCP_PORT environment variable or stop the service using the port
Dependencies missing	Run pip install -r requirements.txt
Docker build fails	Ensure Docker is running and python:3.11-slim image is available
Connection refused	Verify server is running and check MCP_HOST and MCP_PORT settings

Future Enhancements

• Add additional utility tools (unit conversions, calculations)
• Implement caching for frequently used calculations
• Add logging and monitoring capabilities
• Create a web dashboard for tool testing
• Add comprehensive unit tests

License

This project is provided as-is for educational and commercial use.

Author

Yogesh Kadiya

Support

For issues, questions, or suggestions, please refer to the project documentation or contact the author.

Dependencies

The required Python dependencies are listed in requirements.txt. Make sure to install them if you are running the server outside of Docker.

Contributing

If you would like to contribute to this project, please fork the repository and submit a pull request.

License

This project is licensed under the MIT License. See the LICENSE file for more details.