Skip to main content
Glama
nykznykz

Example MCP Server

by nykznykz
OverviewSchemaRelated ServersScoreDiscussions
Python
Hybrid

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

Related MCP server: Fast MCP Local

Quick Start

Prerequisites

  • Python 3.10+

  • uv for dependency management

  • Docker (optional, for containerization)

Installation

  1. Clone the repository:

git clone <repository-url>
cd nikolas-mcp

  1. Install dependencies using uv:

uv sync

  1. Run the server:

uv run python -m mcp_server.main

Using Docker

  1. Build the Docker image:

docker build -t mcp-server .

  1. Run the container:

docker run -p 8000:8000 mcp-server

  1. 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:

  1. Base stage: Sets up Python and system dependencies

  2. Dependencies stage: Installs Python packages with uv

  3. Runtime stage: Copies application code and runs the server

Health Checks

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

Contributing

  1. Fork the repository

  2. Create a feature branch (git checkout -b feature/amazing-feature)

  3. Make your changes

  4. Run tests and ensure they pass

  5. Commit your changes (git commit -m 'Add amazing feature')

  6. Push to the branch (git push origin feature/amazing-feature)

  7. 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:

  1. Check the Issues page for existing problems

  2. Create a new issue with detailed information

  3. Refer to the FastMCP documentation for FastMCP-specific questions

Available Tools

2 tools
calculateA

Evaluate a mathematical expression safely.

Args: expression: A mathematical expression to evaluate (e.g., "2 + 2", "10 * 5")

Returns: The result of the calculation as a string

ParametersJSON Schema
NameRequiredDescriptionDefault
expressionYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It discloses the key behavioral trait of 'safely' evaluating expressions, which suggests error handling or security considerations. However, it doesn't detail specific safety mechanisms, rate limits, or authentication needs.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is appropriately sized and front-loaded: the first sentence states the core purpose, followed by clear sections for Args and Returns. Every sentence adds value without redundancy, making it efficient and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's low complexity, no annotations, and the presence of an output schema (which covers return values), the description is mostly complete. It explains the purpose, parameter, and return behavior, though it could add more on safety specifics or error cases.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema description coverage is 0%, so the description must compensate fully. It adds significant meaning beyond the schema by explaining that 'expression' is a mathematical expression and providing concrete examples ('2 + 2', '10 * 5'), which clarifies the expected format and usage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose with a specific verb ('evaluate') and resource ('mathematical expression'), plus the qualifier 'safely' distinguishes it from generic calculation tools. It explicitly tells what the tool does without restating the name.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage through the example expressions provided, but doesn't explicitly state when to use this tool versus alternatives. With only one sibling tool ('greet') that's unrelated, there's no need for sibling differentiation, but no explicit guidance on context or exclusions is given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

greetB

Generate a friendly greeting message.

Args: name: The name of the person to greet

Returns: A personalized greeting message

ParametersJSON Schema
NameRequiredDescriptionDefault
nameYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool generates a greeting and returns a message, but doesn't describe any behavioral traits such as rate limits, error handling, or side effects. For a tool with zero annotation coverage, this is a significant gap in transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is appropriately sized and front-loaded: it starts with the core purpose in the first sentence, followed by clear sections for arguments and returns. Every sentence earns its place without waste, making it efficient and well-structured for quick understanding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's low complexity (one parameter, simple output) and the presence of an output schema (which handles return values), the description is complete enough. It covers the purpose, parameter meaning, and return type, though it lacks behavioral details. For a straightforward greeting tool, this is largely sufficient, but minor gaps prevent a perfect score.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema description coverage is 0%, but the description compensates by explaining the parameter 'name' as 'The name of the person to greet.' This adds meaning beyond the schema, which only specifies the type. However, with only one parameter and no complex details, the description provides adequate but minimal semantic context, aligning with the baseline for this simple case.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Generate a friendly greeting message.' It specifies the verb ('generate') and resource ('greeting message'), making it easy to understand what the tool does. However, it doesn't explicitly differentiate from its sibling tool 'calculate', which is a different function, so it doesn't reach the highest score.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention any context, prerequisites, or exclusions for usage. The only implied usage is for generating greetings, but this is basic and lacks explicit when/when-not instructions or named alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.6/5.0
Disambiguation5/5

The two tools have completely distinct purposes: 'calculate' handles mathematical expressions, while 'greet' generates personalized greetings. There is no overlap in functionality, making it impossible to confuse them.

Naming Consistency5/5

Both tool names follow a simple verb-only pattern ('calculate', 'greet'), which is consistent and predictable. There are no mixed conventions or deviations in naming style.

Tool Count2/5

With only 2 tools, the server feels thin and under-scoped for a general-purpose 'Example MCP Server'. This minimal set lacks the depth needed to handle a coherent domain or typical workflows effectively.

Completeness2/5

The server's purpose is unclear from the tools provided, but the surface is severely incomplete for any meaningful domain. There are obvious gaps, such as missing related operations (e.g., no other utilities or extended functionality), which will limit agent capabilities.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • Calculator MCP Server

    surajkumar0203
    F
    license
    Not graded
    quality
    D
    maintenance
    A simple MCP server that provides basic calculator functionality for performing mathematical operations. Built with FastMCP and demonstrates fundamental MCP server implementation patterns.

  • Fast MCP Local

    karthik78180
    A
    license
    Not graded
    quality
    D
    maintenance
    A minimal FastMCP server implementation that provides basic mathematical and greeting tools. Enables users to perform simple operations like adding numbers and greeting people by name through a lightweight MCP interface.
    MIT

  • MCP Server Basic

    rupesh-github01
    F
    license
    Not graded
    quality
    D
    maintenance
    A basic MCP server example that provides simple arithmetic tools (addition and subtraction) and personalized greeting resources. Serves as a foundation for learning MCP server implementation and development.

Appeared in Searches

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/nykznykz/mcp_example'

If you have feedback or need assistance with the MCP directory API, please join our Discord server