# 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:**
```json
Input:
{
  "name": "Alice"
}

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

### 2. **farewell(name)**
A polite goodbye tool that bids farewell to users.

**Example:**
```json
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:**
```json
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:**
```json
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**
   ```bash
   git clone <your-repo-url>
   cd utility-mcp-server
   ```

2. **Install dependencies**
   ```bash
   pip install -r requirements.txt
   ```

3. **Verify installation**
   ```bash
   python -c "import mcp; print('MCP installed successfully')"
   ```

---

## How to Run

### Start the MCP Server

**Option 1: Direct Python execution**
```bash
python hello_server.py
```

**Option 2: Using MCP Inspector (Recommended for testing)**
```bash
npx @modelcontextprotocol/inspector mcp-config.json
```

**Option 3: Using Claude Desktop**
Add the following to your Claude Desktop config:
```json
{
  "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:

```bash
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**
   ```bash
   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:

```bash
# 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**