# MCP Simple Example

A Model Context Protocol (MCP) server that provides network diagnostic tools (ping, traceroute) as AI-accessible tools. Works with any MCP-compatible client 

## Overview

This project creates an MCP server that exposes network diagnostic commands as tools that can be called by any MCP-compatible AI assistant. The AI assistant (powered by Ollama with llama3.1:8b) can use these tools to diagnose network issues, check host connectivity, trace network paths

### What is MCP?

The Model Context Protocol (MCP) is an open standard developed by Anthropic for connecting AI assistants to external tools and data sources. Instead of hardcoding tool implementations in every AI client, MCP allows:

- **Standardized Tool Interface**: Tools are defined once and work with any MCP client
- **Secure Execution**: Tools run in isolation, reducing security risks
- **Easy Integration**: MCP clients can discover and use tools dynamically
- **Language Agnostic**: Servers can be written in any language (Python, TypeScript, Go, etc.)


### Components

1. **mcp_server.py**: The main MCP server implementation
   - Implements the MCP protocol over stdio
   - Defines two tools: `network-ping`, `network-traceroute`
   - Handles tool execution and response formatting

2. **mcp_client.py**: Interactive CLI test client
   - Allows manual testing of all tools
   - Useful for debugging without an AI assistant

### Tool Definitions

| Tool | Purpose | Key Parameters |
|------|---------|-----------------|
| `network-ping` | Test host reachability and latency | `host`, `count` |
| `network-traceroute` | Trace network path to host | `host`, `max_hops`, `timeout` |

## Prerequisites

### System Requirements

- **Python**: 3.10 or higher
- **uv**: Package manager (install from https://github.com/astral-sh/uv)

### Required System Tools

The server uses the following system commands (must be installed on your system):

| Command | Purpose | Install (Debian/Ubuntu) | Install (macOS) |
|---------|---------|-------------------------|-----------------|
| `ping` | ICMP echo requests | `apt install iputils-ping` | Built-in |
| `traceroute` | Network path tracing | `apt install traceroute` | Built-in |

### Ollama Setup (for AI Integration)

To use with an AI assistant:

1. Install Ollama: https://ollama.ai
2. Pull the model: `ollama pull llama3.1:8b`
3. Start Ollama: `ollama serve`

## Installation

### Step 1: Clone or Navigate to the Project

```bash
cd /path/to/simple_mcp_example
```

### Step 2: Install Dependencies with uv

```bash
# Install all dependencies using uv
uv sync

# Or install the MCP package directly
uv add mcp python-dotenv
```

### Step 3: Verify Installation

```bash
# Check that uv created the virtual environment
ls -la .venv

# Verify Python can see the packages
uv run python -c "import mcp; print('MCP installed')"
```

### Step 4: Install System Tools (if needed)

```bash
# Debian/Ubuntu
sudo apt update
sudo apt install iputils-ping traceroute 

```

## Usage

### Direct Server Execution

Start the server directly (outputs to stderr):

```bash
uv run python mcp_server.py
```

### Interactive Test Client

The easiest way to test the server:

```bash
# Run the interactive test client
uv run python mcp_client.py
```

You can then type commands like:
```
> ping google.com
> traceroute cloudflare.com
> quit
```

## Configuration

### Environment Variables

The server doesn't require environment variables, but you can add them to `pyproject.toml` if needed:

```toml
[tool.mcp-server.env]
# DEBUG=true
```

### Customizing Tool Behavior

Edit `mcp_server.py` to customize:

#### Add New Tools
Add new `Tool` definitions and handlers in `mcp_server.py`.

## API Reference

### Tool: network-ping

Test connectivity and measure latency to a host.

**Parameters:**
| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `host` | string | Yes | - | Hostname or IP address |
| `count` | integer | No | 4 | Number of packets |

**Example Request:**
```json
{
  "method": "tools/call",
  "params": {
    "name": "network-ping",
    "arguments": {
      "host": "google.com",
      "count": 4
    }
  }
}
```

**Example Response:**
```
# Ping Results for google.com

## Command Output
PING google.com (142.250.80.46): 56 data bytes
64 bytes from 142.250.80.46: icmp_seq=0 ttl=117 time=10.123 ms
64 bytes from 142.250.80.46: icmp_seq=1 ttl=117 time=10.456 ms
...

## Summary
✓ 0% packet loss - Host is fully reachable
Latency (RTT): min=10.1ms, avg=10.3ms, max=10.5ms
```

### Tool: network-traceroute

Trace the network path to a destination host.

**Parameters:**
| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `host` | string | Yes | - | Hostname or IP address |
| `max_hops` | integer | No | 30 | Maximum hops to trace |
| `timeout` | integer | No | 5 | Seconds to wait per hop |

**Example Request:**
```json
{
  "method": "tools/call",
  "params": {
    "name": "network-traceroute",
    "arguments": {
      "host": "cloudflare.com",
      "max_hops": 15
    }
  }
}
```

## Troubleshooting

### "ping command not found"

**Solution**: Install ping utilities
```bash
# Debian/Ubuntu
sudo apt install iputils-ping

# macOS
# ping is built-in
```

### "Server timed out" or "Connection failed"

**Possible causes:**
1. Server is taking too long to start
2. Network issues between client and server
3. Host is unreachable

**Solutions:**
```bash
# Check server starts correctly
uv run python mcp_server.py

```

## License

MIT License - Feel free to use, modify, and distribute.