# perfsonar-mcp

MCP (Model Context Protocol) server for perfSONAR - Query measurements, discover testpoints, and schedule network tests.

## 🚀 Features

### Measurement Archive Queries
- Query historical measurements with filters
- Get throughput, latency, and packet loss data
- Access raw time-series data with summaries
- Discover available measurement types

### Lookup Service Integration  
- Find perfSONAR testpoints globally
- Search by location (city, country)
- Locate pScheduler services for testing

### Test Scheduling (pScheduler)
- Schedule throughput tests (iperf3)
- Schedule latency tests (owping)
- Schedule RTT tests (ping)
- Monitor test status and retrieve results

## 📦 Installation

```bash
pip install -e .
```

For development with additional tools:

```bash
pip install -e '.[dev]'
```

## ⚙️ Configuration

Required environment variable:

```bash
export PERFSONAR_HOST=perfsonar.example.com
```

Optional:

```bash
export LOOKUP_SERVICE_URL=https://lookup.perfsonar.net/lookup
export PSCHEDULER_URL=https://perfsonar.example.com/pscheduler
```

## 🏃 Usage

### Local (stdio transport)

Standard MCP stdio transport for local AI clients:

```bash
python -m perfsonar_mcp
# or
perfsonar-mcp
```

### Web Access (SSE/HTTP transport)

FastMCP enables web-accessible MCP server via SSE (Server-Sent Events) or HTTP:

```bash
# SSE transport (recommended for web)
export PERFSONAR_HOST=perfsonar.example.com
fastmcp run src/perfsonar_mcp/fastmcp_server.py --transport sse --host 0.0.0.0 --port 8000

# HTTP transport (alternative)
fastmcp run src/perfsonar_mcp/fastmcp_server.py --transport http --host 0.0.0.0 --port 8000

# Or use the convenience command
perfsonar-mcp-web
```

The server will be accessible at:
- SSE: `http://your-host:8000/sse`
- HTTP: `http://your-host:8000/mcp/`

### Docker

```bash
docker-compose up -d
```

### Kubernetes

```bash
helm install perfsonar-mcp ./helm/perfsonar-mcp \
  --set config.perfsonarHost=perfsonar.example.com
```

## 🤖 Claude Desktop Integration

Add to your `claude_desktop_config.json`:

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

```json
{
  "mcpServers": {
    "perfsonar": {
      "command": "python",
      "args": ["-m", "perfsonar_mcp"],
      "env": {
        "PERFSONAR_HOST": "your-perfsonar-host.example.com"
      }
    }
  }
}
```

For web-based access, use the SSE endpoint:

```json
{
  "mcpServers": {
    "perfsonar-web": {
      "url": "http://your-server:8000/sse",
      "transport": "sse"
    }
  }
}
```

## 🔧 Available Tools (13)

### Measurement Archive (6)
- `query_measurements` - Search measurements
- `get_throughput` - Throughput data
- `get_latency` - Latency data
- `get_packet_loss` - Packet loss data
- `get_measurement_data` - Raw time-series
- `get_available_event_types` - List types

### Lookup Service (2)
- `lookup_testpoints` - Find testpoints
- `find_pscheduler_services` - Find pScheduler

### pScheduler (5)
- `schedule_throughput_test` - Run throughput test
- `schedule_latency_test` - Run latency test
- `schedule_rtt_test` - Run RTT test
- `get_test_status` - Check status
- `get_test_result` - Get results

## 💡 Example Queries

Ask Claude:

> "Find perfSONAR testpoints in Europe"

> "Schedule a 30-second throughput test to host.example.com"

> "Get hourly throughput averages between host1 and host2 for the last week"

## 🏗️ Architecture

### Standard MCP (stdio)
```
AI Agent (Claude)
    ↓ MCP Protocol (stdio)
perfSONAR MCP Server (Python)
    ├── Measurement Archive Client
    ├── Lookup Service Client  
    └── pScheduler Client
        ↓
    perfSONAR Services
```

### Web-Accessible MCP (SSE/HTTP)
```
Web Clients / AI Agents
    ↓ HTTP/SSE
FastMCP Web Server (uvicorn)
    ↓ MCP Protocol
perfSONAR MCP Server (Python)
    ├── Measurement Archive Client
    ├── Lookup Service Client  
    └── pScheduler Client
        ↓
    perfSONAR Services
```

Both transports expose the same tools and capabilities. The web transport enables:
- Remote access from any HTTP client
- Multiple concurrent connections
- Integration with web-based AI applications
- RESTful API-like access patterns

## 🛠️ Development

### Logging

The server includes comprehensive logging for development and debugging. By default, logs are written to stderr at INFO level.

To enable DEBUG logging for more detailed output:

```python
import logging
logging.basicConfig(level=logging.DEBUG)
```

Or set the log level via environment variable:

```bash
export PYTHONLOGLEVEL=DEBUG
python -m perfsonar_mcp
```

Log output includes:
- Server initialization and configuration
- API requests and responses
- Tool invocations with arguments
- Error details with stack traces

### DevContainer

Open in VS Code → Reopen in Container

### Local Development

```bash
# Install with dev dependencies
pip install -e '.[dev]'

# Format code
black src/perfsonar_mcp/

# Lint code
ruff check src/perfsonar_mcp/

# Type check
mypy src/perfsonar_mcp/

# Run tests
pytest tests/
```

## 📚 Documentation

- [Deployment Guide](DEPLOYMENT.md)
- [Examples](EXAMPLES.md)
- [Contributing](CONTRIBUTING.md)

## 🌐 Resources

- [perfSONAR Docs](https://docs.perfsonar.net/)
- [MCP Protocol](https://modelcontextprotocol.io/)

## 📄 License

MIT