# SIPp MCP Server

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js Version](https://img.shields.io/badge/node-%3E%3D16-brightgreen)](https://nodejs.org/)
[![MCP](https://img.shields.io/badge/MCP-Compatible-blue)](https://modelcontextprotocol.io/)

A Model Context Protocol (MCP) server for interacting with SIPp, the SIP protocol testing tool.

> **Use SIPp testing capabilities directly from Claude Desktop, VS Code, or any MCP-compatible client!**

## Quick Start

### Install from npm

```bash
npm install -g sipp-mcp-server
```

### Or install from source

```bash
# Clone the repository
git clone https://github.com/randybritsch/sipp-mcp-server.git
cd sipp-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

# Test with MCP Inspector
npx @modelcontextprotocol/inspector node build/index.js
```

Then configure in [Claude Desktop](#setup-with-claude-desktop) or [VS Code](#setup-with-vs-code).

## Features

This MCP server provides tools to:

- **Run SIPp Scenarios**: Execute SIPp tests in UAC (client) or UAS (server) mode
- **Create Custom Scenarios**: Generate custom XML scenario files for testing
- **Get Statistics**: Parse and display SIPp test statistics
- **Check Version**: Verify SIPp installation and version

## Prerequisites

- Node.js 16 or higher
- SIPp installed and available in your PATH
  - Download from: https://github.com/SIPp/sipp
  - Or install via package manager:
    - Ubuntu/Debian: `sudo apt-get install sipp`
    - macOS: `brew install sipp`
    - Windows: Download binary from releases

## Installation

If installed globally via npm, the server is automatically available as `sipp-mcp-server`.

If installed from source, use `npm link` to make it globally available, or reference the full path to `build/index.js` in your configuration.

## Setup Instructions

### Setup with Claude Desktop

Follow these steps to integrate the SIPp MCP server with Claude Desktop:

#### Step 1: Locate the Claude Desktop Configuration File

Open your Claude Desktop configuration file:

**Windows**:
```powershell
# Open in notepad
notepad %APPDATA%\Claude\claude_desktop_config.json

# Or open in VS Code
code %APPDATA%\Claude\claude_desktop_config.json
```

**macOS**:
```bash
# Open in default editor
open ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Or open in VS Code
code ~/Library/Application\ Support/Claude/claude_desktop_config.json
```

#### Step 2: Add the SIPp MCP Server Configuration

Add the following configuration to your `claude_desktop_config.json` file:

**Using global npm installation (recommended)**:
```json
{
  "mcpServers": {
    "sipp": {
      "command": "sipp-mcp-server"
    }
  }
}
```

**Or using local installation**:

**Windows**:
```json
{
  "mcpServers": {
    "sipp": {
      "command": "node",
      "args": ["C:\\Users\\YOUR_USERNAME\\sipp-mcp-server\\build\\index.js"]
    }
  }
}
```

**macOS/Linux**:
```json
{
  "mcpServers": {
    "sipp": {
      "command": "node",
      "args": ["/absolute/path/to/sipp-mcp-server/build/index.js"]
    }
  }
}
```

**Important**: 
- If using local installation, replace `YOUR_USERNAME` or the path with your actual absolute path
- On Windows, use double backslashes (`\\`) in the JSON file
- If you have other MCP servers, add the `sipp` entry to the existing `mcpServers` object

#### Step 3: Restart Claude Desktop

1. Completely quit Claude Desktop (not just close the window)
2. Relaunch Claude Desktop
3. The SIPp MCP server will start automatically

#### Step 4: Verify the Connection

1. Look for the MCP icon (🔌) in the bottom-right corner of the Claude chat input
2. Click the icon to see available tools
3. You should see the SIPp tools: `run_sipp_scenario`, `create_sipp_scenario`, `get_sipp_statistics`, and `check_sipp_version`

#### Step 5: Test the Server

Try asking Claude:
```
Check if SIPp is installed on my system
```

Claude should use the `check_sipp_version` tool to verify your SIPp installation.

#### Troubleshooting Claude Desktop

**Server not appearing:**
- Check that Node.js is installed: `node --version`
- Verify the path in your config file is correct and absolute
- Check Claude Desktop logs:
  - **Windows**: `%APPDATA%\Claude\logs`
  - **macOS**: `~/Library/Logs/Claude`

**Permission errors:**
- Ensure the build/index.js file exists
- Run `npm run build` again if needed

---

### Setup with VS Code

The SIPp MCP server can be used with VS Code through GitHub Copilot's agent mode.

#### Step 1: Ensure Prerequisites

1. Install the [GitHub Copilot extension](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot)
2. Ensure you have Copilot access with agent mode enabled
3. Make sure the project is built: `npm run build`

#### Step 2: Configure MCP in VS Code

**Using global npm installation (recommended):**

Create `.vscode/mcp.json` in your workspace:

```json
{
  "mcpServers": {
    "sipp": {
      "command": "sipp-mcp-server"
    }
  }
}
```

**Or using local installation:**

The MCP configuration file is already created at `.vscode/mcp.json`:

```json
{
  "mcpServers": {
    "sipp": {
      "command": "node",
      "args": ["c:\\Users\\randy.britsch\\sipp-mcp-server\\build\\index.js"]
    }
  }
}
```

**Update the path** if your project is in a different location:

1. Open `.vscode/mcp.json`
2. Update the path in the `args` array to match your project location
3. Use double backslashes on Windows: `c:\\Users\\...`

#### Step 3: Alternative - User or Workspace Settings

You can also configure MCP servers in VS Code settings:

**Option A: Workspace Settings** (recommended for project-specific servers)

1. Open VS Code Command Palette (`Ctrl+Shift+P` or `Cmd+Shift+P`)
2. Type "Preferences: Open Workspace Settings (JSON)"
3. Add the MCP configuration:

```json
{
  "mcp.servers": {
    "sipp": {
      "command": "node",
      "args": ["${workspaceFolder}/build/index.js"]
    }
  }
}
```

**Option B: User Settings** (for global access)

1. Open VS Code Command Palette (`Ctrl+Shift+P` or `Cmd+Shift+P`)
2. Type "Preferences: Open User Settings (JSON)"
3. Add the MCP configuration with absolute paths

#### Step 4: Enable and Use MCP Tools in Copilot

1. Open GitHub Copilot Chat panel (`Ctrl+Alt+I` or `Cmd+Alt+I`)
2. Start agent mode by typing `@workspace` or using the agent selector
3. The SIPp MCP tools will be available to the agent

#### Step 5: Test the Integration

In the Copilot Chat panel, try:
```
Use the SIPp tools to check if SIPp is installed
```

Or:
```
Create a basic SIPp scenario file named test.xml
```

#### Step 6: Using MCP Tools in Copilot Sessions

You can reference MCP tools in your conversations:

- **Check SIPp version**: "Check if SIPp is installed"
- **Create scenarios**: "Create a register scenario for testing SIP registration"
- **Run tests**: "Run a SIPp UAC test with 10 calls to 192.168.1.100"
- **Get statistics**: "Show me the statistics from sipp_output.csv"

#### Troubleshooting VS Code

**MCP tools not appearing:**
1. Verify the `.vscode/mcp.json` path is correct
2. Reload VS Code window (`Ctrl+Shift+P` → "Developer: Reload Window")
3. Check the Output panel (`View` → `Output`) and select "MCP" from the dropdown

**Build issues:**
```bash
# Rebuild the project
npm run build

# Verify the output file exists
ls build/index.js  # macOS/Linux
dir build\index.js  # Windows
```

**Node.js not found:**
- Ensure Node.js is in your PATH
- Restart VS Code after installing Node.js
- Use absolute path to node: `"command": "C:\\Program Files\\nodejs\\node.exe"`

---

### Testing with MCP Inspector

For development and debugging, use the MCP Inspector:

```bash
npx @modelcontextprotocol/inspector node build/index.js
```

This opens a web interface where you can:
- View all available tools
- Test tool inputs and outputs
- See real-time request/response logs
- Debug tool behavior

## Available Tools

### 1. run_sipp_scenario

Execute a SIPp scenario for SIP protocol testing.

**Parameters:**
- `mode`: "uac" (client) or "uas" (server)
- `remoteHost`: Remote host IP (required for UAC mode)
- `remotePort`: Remote port (default: 5060)
- `localPort`: Local port to bind to
- `scenarioFile`: Path to custom XML scenario file
- `callCount`: Number of calls to make
- `callRate`: Call rate in calls per second
- `duration`: Maximum test duration in seconds
- `transport`: "udp", "tcp", or "tls"
- `timeout`: Global timeout in seconds

**Example:**
```
Run a UAC scenario with 10 calls to 192.168.1.100:5060
```

### 2. create_sipp_scenario

Create a custom SIPp XML scenario file.

**Parameters:**
- `filename`: Name of the scenario file
- `scenarioType`: "basic_call", "register", or "custom"
- `customXml`: Custom XML content (for custom type)

**Example:**
```
Create a basic call scenario named test.xml
```

### 3. get_sipp_statistics

Parse and display statistics from SIPp CSV output files.

**Parameters:**
- `csvFile`: Path to the SIPp statistics CSV file

### 4. check_sipp_version

Check if SIPp is installed and display version information.

## Development

```bash
# Install dependencies
npm install

# Build the project
npm run build

# Watch mode for development
npm run dev

# Test with MCP Inspector
npx @modelcontextprotocol/inspector node build/index.js
```

## Project Structure

```
sipp-mcp-server/
├── src/
│   └── index.ts          # Main server implementation
├── build/                # Compiled JavaScript output
├── package.json
├── tsconfig.json
└── README.md
```

## Example Usage

### Example 1: Check SIPp Installation

**Ask Claude or Copilot:**
```
Check if SIPp is installed and show me the version
```

**Expected behavior:**
- The `check_sipp_version` tool will be invoked
- You'll see SIPp version information or an error if not installed

---

### Example 2: Create a Basic Call Scenario

**Ask Claude or Copilot:**
```
Create a basic SIPp call scenario file named my_test.xml
```

**Expected behavior:**
- The `create_sipp_scenario` tool will be invoked
- A file named `my_test.xml` will be created with a basic UAC call flow
- The file contents will be displayed

---

### Example 3: Run a Simple UAC Test

**Ask Claude or Copilot:**
```
Run a SIPp UAC test with 5 calls to 192.168.1.100 at a rate of 1 call per second
```

**Expected behavior:**
- The `run_sipp_scenario` tool will be invoked with:
  - mode: "uac"
  - remoteHost: "192.168.1.100"
  - callCount: 5
  - callRate: 1
- SIPp will execute the test
- Results and statistics will be shown

---

### Example 4: Run a UAS (Server) Test

**Ask Claude or Copilot:**
```
Start SIPp in server mode on port 5060
```

**Expected behavior:**
- The `run_sipp_scenario` tool will be invoked with:
  - mode: "uas"
  - localPort: 5060
- SIPp will listen for incoming SIP calls

---

### Example 5: Create and Use a REGISTER Scenario

**Ask Claude or Copilot:**
```
Create a REGISTER scenario file named register_test.xml, then run it against 192.168.1.100 with 10 registrations
```

**Expected behavior:**
- First, `create_sipp_scenario` creates the file
- Then, `run_sipp_scenario` executes it
- You'll see the registration test results

---

### Example 6: Advanced Test with Custom Parameters

**Ask Claude or Copilot:**
```
Run a SIPp test against 10.0.0.50:5080 using TCP transport, with 100 calls at 10 calls per second, maximum duration of 60 seconds
```

**Expected behavior:**
- The `run_sipp_scenario` tool will be invoked with:
  - mode: "uac"
  - remoteHost: "10.0.0.50"
  - remotePort: 5080
  - transport: "tcp"
  - callCount: 100
  - callRate: 10
  - duration: 60

---

### Example 7: Analyze Test Results

**Ask Claude or Copilot:**
```
Show me the statistics from the last SIPp test in sipp_output.csv
```

**Expected behavior:**
- The `get_sipp_statistics` tool will be invoked
- CSV contents will be parsed and displayed
- You can ask follow-up questions about the results

## Troubleshooting

### SIPp not found

Make sure SIPp is installed and in your PATH:

```bash
sipp -v
```

If not installed, follow the installation instructions for your platform.

### Permission Issues

On Linux/macOS, you may need to run SIPp with appropriate permissions for binding to ports below 1024.

### Connection Issues

- Verify the remote host is reachable
- Check firewall settings
- Ensure the SIP port (default 5060) is not blocked
- Try using different transport protocols (UDP, TCP, TLS)

## Resources

- [SIPp Documentation](https://sipp.readthedocs.io/)
- [SIPp GitHub Repository](https://github.com/SIPp/sipp)
- [Model Context Protocol Documentation](https://modelcontextprotocol.io/)
- [MCP Servers Repository](https://github.com/modelcontextprotocol/servers)

## Contributing

Contributions are welcome! Here's how you can help:

### Reporting Issues

- Use the [GitHub issue tracker](https://github.com/randybritsch/sipp-mcp-server/issues)
- Check existing issues before creating a new one
- Include SIPp version, Node.js version, and OS details
- Provide clear steps to reproduce any bugs

### Submitting Pull Requests

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes
4. Run tests and build: `npm run build`
5. Commit your changes (`git commit -m 'Add amazing feature'`)
6. Push to the branch (`git push origin feature/amazing-feature`)
7. Open a Pull Request

### Development Guidelines

- Follow existing code style and TypeScript conventions
- Add appropriate error handling
- Update README.md if adding new features
- Test with MCP Inspector before submitting

## Community

- **Questions?** Open a [GitHub Discussion](https://github.com/randybritsch/sipp-mcp-server/discussions)
- **Bug Reports:** Use [GitHub Issues](https://github.com/randybritsch/sipp-mcp-server/issues)
- **MCP Community:** Join the [MCP Discord](https://discord.gg/modelcontextprotocol)

## Roadmap

- [ ] Add support for more SIPp scenario templates
- [ ] Implement real-time statistics monitoring
- [ ] Add SIPp pcap file analysis tools
- [ ] Support for distributed SIPp testing
- [ ] Web-based scenario editor

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Acknowledgments

- [SIPp Project](https://github.com/SIPp/sipp) - The excellent SIP testing tool
- [Model Context Protocol](https://modelcontextprotocol.io/) - The protocol specification
- [Anthropic](https://www.anthropic.com/) - For Claude and MCP support

---

**Made with ❤️ for the SIP testing community**