Simple MCP Server Demo

A simple Model Context Protocol (MCP) server demo with 5 basic tools, demonstrating how to build an MCP service with functional programming principles.

Features

• 5 Simple Tools: Time, calculations, string operations, UUID generation, and tool listing
• Functional Style: Pure functions with dictionary-based dispatch
• 100% Test Coverage: Comprehensive unit tests
• Type Safe: Full type hints throughout
• Local Operations: No network calls, all operations are local

Installation

# Install dependencies
task install

Testing the Server

Using MCP Inspector (Recommended)

Test the MCP server interactively using the official MCP Inspector:

# Using task command
task inspect

# Or run directly
npx @modelcontextprotocol/inspector uv run simple-mcp-server

This will:

1. Start the MCP server
2. Open a web interface at http://localhost:5173
3. Allow you to test all tools interactively

Using Unit Tests

# Run all tests
task test

# Run with coverage report
task coverage

Usage with Claude Desktop

Add this server to your Claude Desktop configuration:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "simple-mcp-server": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/simple-mcp-server",
        "run",
        "simple-mcp-server"
      ]
    }
  }
}

Replace /absolute/path/to/simple-mcp-server with the actual path to this project.

Available Tools

1. get_current_time

Get the current time in various formats.

Parameters:

• format (optional): "iso", "unix", or "human" (default: "iso")
• timezone (optional): Timezone name like "America/New_York"

Examples:

ISO format (default): "2024-01-15T14:30:00+00:00"
Unix timestamp: "1705329000"
Human readable: "2024-01-15 14:30:00 UTC"
With timezone: "2024-01-15 09:30:00 EST"

2. calculate

Perform basic arithmetic operations.

Parameters:

• operation: "add", "subtract", "multiply", "divide", "power", or "modulo"
• a: First number
• b: Second number

Examples:

add(5, 3) = 8.0
subtract(10, 4) = 6.0
multiply(7, 6) = 42.0
divide(15, 3) = 5.0
power(2, 8) = 256.0
modulo(17, 5) = 2.0

3. string_transform

Transform strings in various ways.

Parameters:

• text: Input string
• operation: "uppercase", "lowercase", "reverse", "length", or "word_count"

Examples:

uppercase("hello") = "HELLO"
lowercase("WORLD") = "world"
reverse("hello") = "olleh"
length("hello world") = 11
word_count("hello world test") = 3

4. generate_uuid

Generate a UUID.

Parameters:

• version (optional): 1, 4, or 5 (default: 4)
• namespace (for v5): "dns", "url", "oid", or "x500"
• name (for v5): String to hash

Examples:

v1: "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
v4: "550e8400-e29b-41d4-a716-446655440000" (random)
v5: "886313e1-3b8a-5372-9b90-0c9aee199e5d" (deterministic)

5. list_operations

List all available tools with their descriptions.

Parameters: None

Returns: Formatted list of all tools and their parameters.

Development

Available Tasks

• task install - Install dependencies with uv
• task format - Format code with ruff
• task lint - Lint code with ruff
• task lint-fix - Lint and auto-fix issues
• task test - Run tests
• task coverage - Run tests with coverage report
• task dev - Run server in development mode
• task inspect - Test server with MCP Inspector (interactive)
• task check - Run all checks (format, lint, coverage)
• task clean - Clean build artifacts and cache

Development Workflow

1. Make code changes
2. Run task format to format code
3. Run task lint to check for issues
4. Run task test to run unit tests
5. Run task check to run all checks before committing

Project Structure

simple-mcp-server/
├── src/simple_mcp_server/
│   ├── server.py      # Main MCP server
│   ├── tools.py       # Pure tool functions
│   └── handlers.py    # MCP tool handlers
└── tests/
    ├── test_tools.py  # Unit tests
    └── test_server.py # Integration tests

Code Style

This project follows functional programming principles:

• Pure functions with no side effects
• 80% test coverage requirement

Requirements

• Python 3.14+
• uv (package manager)
• go-task (task runner)

License

MIT