Utility MCP Server

A beginner-friendly Model Context Protocol (MCP) server that provides essential utility tools for AI-powered applications. This project demonstrates how to build a functional MCP server that can be integrated with AI assistants like Claude Desktop.

What is MCP?

The Model Context Protocol (MCP) is an open protocol that enables AI assistants to securely interact with external tools, data sources, and APIs. Think of MCP as a universal language that allows AI models to request and receive information in a structured way. This project implements an MCP server that exposes utility tools which AI assistants can call to perform useful tasks.

---

Features

1. greet(name)

A friendly greeting tool that welcomes users by name.

Example:

Input:
{
  "name": "Alice"
}

Output:
"Hello, Alice! Welcome to MCP!"

2. farewell(name)

A polite goodbye tool that bids farewell to users.

Example:

Input:
{
  "name": "Bob"
}

Output:
"Goodbye, Bob! See you soon!"

3. add_numbers(a, b)

A mathematical tool that adds two integers and returns a formatted result.

Example:

Input:
{
  "a": 15,
  "b": 20
}

Output:
"The sum of 15 and 20 is 35."

4. get_current_date()

A utility tool that returns today's date in a human-readable format.

Example:

Input:
{}

Output:
"08 July 2026"

---

Project Structure

utility-mcp-server/
│
├── hello_server.py          # Main MCP server implementation
├── test_client.py            # Test client for server validation
├── mcp-config.json           # MCP server configuration file
├── requirements.txt          # Python dependencies
├── simple_test.py           # Message format demonstration
├── simple_mcp_test.py       # Direct server testing script
└── README.md                # Project documentation

---

Technologies Used

• Python - Core programming language for server implementation
• Model Context Protocol (MCP) - Open protocol for AI-tool communication
• VS Code - Recommended IDE for development and debugging
• JSON-RPC 2.0 - Remote procedure call protocol for client-server communication

---

Architecture

The project follows a client-server architecture using the MCP protocol:

┌─────────────┐
│    User     │
└──────┬──────┘
       │ Request
       ↓
┌─────────────────┐
│  MCP Client     │
│  (Claude Desktop│
│   or Inspector) │
└───────┬─────────┘
        │ JSON-RPC Message
        ↓
┌─────────────────┐
│   MCP Server    │
│  (hello_server) │
└───────┬─────────┘
        │ Tool Call
        ↓
┌─────────────────┐
│  Tool Handler   │
│  - greet()      │
│  - farewell()   │
│  - add_numbers()│
│  - get_current_ │
│    date()       │
└───────┬─────────┘
        │ Result
        ↓
┌─────────────────┐
│  Response       │
│  (Formatted     │
│   Text Content) │
└─────────────────┘

Message Flow:

1. User makes a request via an AI assistant
2. Client sends a JSON-RPC request to the MCP server
3. Server processes the request and routes it to the appropriate tool
4. Tool executes the logic and returns a result
5. Response is sent back through the chain to the user

---

Installation

Prerequisites

• Python 3.10 or higher
• pip (Python package manager)
• Git (for cloning the repository)

Step-by-Step Setup

1. Clone the repository

   git clone <your-repo-url>
   cd utility-mcp-server
   

2. Install dependencies

   pip install -r requirements.txt
   

3. Verify installation

   python -c "import mcp; print('MCP installed successfully')"
   

---

How to Run

Start the MCP Server

Option 1: Direct Python execution

python hello_server.py

Option 2: Using MCP Inspector (Recommended for testing)

npx @modelcontextprotocol/inspector mcp-config.json

Option 3: Using Claude Desktop Add the following to your Claude Desktop config:

{
  "mcpServers": {
    "utility-server": {
      "command": "python",
      "args": ["path/to/hello_server.py"]
    }
  }
}

Verify Server is Running

The server will start in stdio mode and listen for JSON-RPC messages. If using MCP Inspector, a web interface will open at http://localhost:6277.

---

Testing

Method 1: Using test_client.py

The included test client automatically validates all server functionality:

python test_client.py

Expected Output:

>>> Starting MCP Server Test Client

[Test 1] Initializing connection...
   Initialized: 2024-11-05

[Test 2] Listing available tools...
   Found 4 tools:
   - greet: Say hello to someone
   - farewell: Say goodbye to someone
   - add_numbers: Add two numbers together
   - get_current_date: Get today's date in a formatted string

[Test 3] Calling 'greet' with name='Alice'...
   Response: Hello, Alice! Welcome to MCP!

[Test 4] Calling 'farewell' with name='Bob'...
   Response: Goodbye, Bob! See you soon!

[SUCCESS] All tests completed!

Method 2: Using MCP Inspector

1. Start the Inspector

   npx @modelcontextprotocol/inspector mcp-config.json
   

2. Open the web interface at the shown URL (usually http://localhost:6277)

3. Test individual tools:

   • Click on any tool in the sidebar
   • Enter required parameters
   • Click "Call Tool"
   • View the response in the output panel

Method 3: Manual JSON-RPC Testing

Test specific tools directly via command line:

# Test add_numbers
(echo '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}},"id":1}' && echo '{"jsonrpc":"2.0","method":"notifications/initialized","params":{}}' && echo '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"add_numbers","arguments":{"a":15,"b":20}},"id":2}') | python hello_server.py

# Test get_current_date
(echo '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}},"id":1}' && echo '{"jsonrpc":"2.0","method":"notifications/initialized","params":{}}' && echo '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"get_current_date","arguments":{}},"id":2}') | python hello_server.py

---

Learning Outcomes

Building this project helped me master several important concepts:

Technical Skills

• MCP Protocol Understanding: Learned how the Model Context Protocol enables AI assistants to interact with external tools through standardized JSON-RPC messages
• Async Programming: Gained experience with Python's asyncio and asynchronous server architecture
• API Design: Understood how to design clean, intuitive tool interfaces with proper input validation and response formatting
• JSON-RPC Implementation: Learned to implement the JSON-RPC 2.0 protocol for client-server communication

Architecture Concepts

• Client-Server Model: Understanding of how clients and servers communicate via message passing
• Tool Abstraction: How to expose functionality as callable tools with standardized interfaces
• Error Handling: Proper error handling and graceful degradation in distributed systems
• Configuration Management: Using JSON configuration files for server setup and deployment

Development Practices

• Testing Methodologies: Writing test clients and using inspector tools for validation
• Documentation Skills: Creating comprehensive README files and inline code comments
• Debugging Techniques: Using MCP Inspector and command-line testing for troubleshooting
• Project Organization: Structuring code files logically for maintainability

---

Future Improvements

1. Enhanced Tool Set

Add more utility tools such as:

• calculate_percentage(numerator, denominator) - Calculate percentages
• format_currency(amount, currency_code) - Format monetary values
• validate_email(email_address) - Email validation
• generate_random_password(length, complexity) - Secure password generation

2. Error Handling & Validation

• Implement robust input validation for all tools
• Add comprehensive error messages with troubleshooting guidance
• Include type checking and range validation for numeric inputs
• Add logging for debugging and monitoring

3. Configuration Options

• Make date format configurable in get_current_date()
• Add language/locale support for internationalization
• Allow customization of greeting and farewell messages
• Support for custom number formatting in add_numbers()

4. Performance Optimization

• Implement caching for frequently called operations
• Add connection pooling for multiple client requests
• Optimize message parsing and serialization
• Add metrics collection for performance monitoring

5. Integration Features

• Add support for environment variables for configuration
• Implement authentication and authorization for production use
• Create a REST API wrapper for web service deployment
• Add webhook support for event-driven functionality

---

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For beginners, this is a great project to:

• Learn MCP protocol implementation
• Practice async Python programming
• Understand client-server architectures
• Improve documentation and testing skills

---

License

This project is open source and available under the MIT License.

---

Acknowledgments

• Model Context Protocol (MCP) by Anthropic
• MCP Python SDK for providing the server framework
• Claude Desktop team for the reference implementation

---

Built with ❤️ for the MCP community