OITVOIP MCP Server

🎯 Production-Ready NetSapiens Integration
Comprehensive MCP server providing AI agents with full access to NetSapiens VoIP platform

A Model Context Protocol (MCP) server that provides AI agents with seamless access to the NetSapiens VoIP platform. This server enables AI applications to interact with NetSapiens functionality including user management, call detail records, and system information.

⚡ Features

👥 User Management: Search users, get details, devices, answer rules, greetings, and voicemails
📞 Phone Number Management: List and manage phone numbers across domains
🎯 Call Center Operations: Manage call queues, agents, login/logout, and statistics
📊 Call Analytics: Access CDR records, agent statistics, and call patterns
🏢 Domain Administration: Complete domain management and configuration
🤖 Auto Attendant: Configure and manage automated attendants
🎵 Media Management: Handle greetings, voicemail, and music on hold
💰 Billing Integration: Access billing information and usage data
🔧 Real-time Operations: Live access to NetSapiens platform data
⚡ Error Handling: Robust error handling with detailed logging
🛡️ Rate Limiting: Built-in rate limiting for API protection
📝 TypeScript: Full TypeScript support with comprehensive type safety

🏗️ Architecture

oitvoip-mcp-server/
├── src/
│   ├── index.ts              # Main MCP server implementation
│   └── netsapiens-client.ts  # NetSapiens API client
├── types/
│   └── config.ts             # TypeScript type definitions
├── docs/                     # Documentation
├── build/                    # Compiled JavaScript output
├── package.json              # Project dependencies
├── tsconfig.json             # TypeScript configuration
└── README.md                 # This file

🚀 Quick Start

Prerequisites

Node.js 18.0.0 or higher
npm or yarn package manager
NetSapiens API credentials

Installation

Option 1: From npm (Recommended)

npm install -g oitvoip-mcp-server

Option 2: From Source

Clone the repository

git clone https://github.com/OITApps/oitvoip-mcp-server.git
cd oitvoip-mcp-server

Install dependencies
```
npm install
```
Build the project
```
npm run build
```
Configure in your MCP client

Add the server to your MCP client configuration with your NetSapiens credentials (see MCP Client Setup section below)

Development Mode

For development with hot reloading:

npm run dev

🔧 Configuration

This MCP server is configured entirely through your MCP client's configuration file. No separate .env file is needed - all configuration is passed through environment variables in the MCP client config.

Required Configuration

NETSAPIENS_API_URL: Your NetSapiens API endpoint (usually https://api.ucaasnetwork.com)
NETSAPIENS_API_TOKEN: Your NetSapiens API token

Optional Configuration

DEBUG: Set to true to enable debug logging (default: false)
NETSAPIENS_TIMEOUT: API request timeout in milliseconds (default: 30000)

🔌 MCP Client Setup

OpenCode

For OpenCode, add the MCP server to your configuration file at ~/.opencode/mcp.json:

If installed via npm:

{
  "mcpServers": {
    "oitvoip": {
      "command": "oitvoip-mcp-server",
      "env": {
        "NETSAPIENS_API_URL": "https://api.ucaasnetwork.com",
        "NETSAPIENS_API_TOKEN": "your_api_token_here"
      }
    }
  }
}

If installed from source:

{
  "mcpServers": {
    "oitvoip": {
      "command": "node",
      "args": ["/path/to/oitvoip-mcp-server/build/index.js"],
      "env": {
        "NETSAPIENS_API_URL": "https://api.ucaasnetwork.com",
        "NETSAPIENS_API_TOKEN": "your_api_token_here"
      }
    }
  }
}

Claude Desktop

For Claude Desktop, add the server to your configuration file:

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

If installed via npm:

{
  "mcpServers": {
    "oitvoip": {
      "command": "oitvoip-mcp-server",
      "env": {
        "NETSAPIENS_API_URL": "https://api.ucaasnetwork.com",
        "NETSAPIENS_API_TOKEN": "your_api_token_here"
      }
    }
  }
}

If installed from source:

{
  "mcpServers": {
    "oitvoip": {
      "command": "node",
      "args": ["/path/to/oitvoip-mcp-server/build/index.js"],
      "env": {
        "NETSAPIENS_API_URL": "https://api.ucaasnetwork.com",
        "NETSAPIENS_API_TOKEN": "your_api_token_here"
      }
    }
  }
}

Cursor

For Cursor, add the server to your MCP configuration file at ~/.cursor/mcp.json:

If installed via npm:

{
  "mcpServers": {
    "oitvoip": {
      "command": "oitvoip-mcp-server",
      "env": {
        "NETSAPIENS_API_URL": "https://api.ucaasnetwork.com",
        "NETSAPIENS_API_TOKEN": "your_api_token_here"
      }
    }
  }
}

If installed from source:

{
  "mcpServers": {
    "oitvoip": {
      "command": "node",
      "args": ["/path/to/oitvoip-mcp-server/build/index.js"],
      "env": {
        "NETSAPIENS_API_URL": "https://api.ucaasnetwork.com",
        "NETSAPIENS_API_TOKEN": "your_api_token_here"
      }
    }
  }
}

Configuration Notes

Replace /path/to/oitvoip-mcp-server with the actual path to your installation
Replace your_api_token_here with your actual NetSapiens API token
All configuration is handled through the MCP client - no separate .env file is needed
After configuration, restart your MCP client to load the server

🛠️ Available Tools (23 Total)

👥 User Management

1. Search Users

Search for users in the NetSapiens system by username.

{
  "name": "search_users",
  "arguments": {
    "query": "john.doe",
    "domain": "company.com",
    "limit": 20
  }
}

2. Get User Details

Retrieve detailed information about a specific user.

{
  "name": "get_user",
  "arguments": {
    "userId": "john.doe",
    "domain": "company.com"
  }
}

3. Get User Devices

Get devices assigned to a specific user.

{
  "name": "get_user_devices",
  "arguments": {
    "userId": "john.doe",
    "domain": "company.com"
  }
}

📞 Phone Number Management

4. Get Phone Numbers

Get phone numbers for a domain.

{
  "name": "get_phone_numbers",
  "arguments": {
    "domain": "company.com",
    "limit": 50
  }
}

5. Get Phone Number Details

Get details of a specific phone number.

{
  "name": "get_phone_number",
  "arguments": {
    "domain": "company.com",
    "phoneNumber": "+15551234567"
  }
}

🏢 Domain Management

6. Get Domains

Get list of domains in the NetSapiens system.

{
  "name": "get_domains",
  "arguments": {}
}

7. Get Domain Details

Get detailed information about a specific domain.

{
  "name": "get_domain",
  "arguments": {
    "domain": "company.com"
  }
}

🎯 Call Center Management

8. Get Call Queues

Get call queues for a domain.

{
  "name": "get_call_queues",
  "arguments": {
    "domain": "company.com"
  }
}

9. Get Call Queue Details

Get details of a specific call queue.

{
  "name": "get_call_queue",
  "arguments": {
    "domain": "company.com",
    "queueId": "sales-queue"
  }
}

10. Get Call Queue Agents

Get agents assigned to a call queue.

{
  "name": "get_call_queue_agents",
  "arguments": {
    "domain": "company.com",
    "queueId": "sales-queue"
  }
}

11. Get Agents

Get agents for a domain.

{
  "name": "get_agents",
  "arguments": {
    "domain": "company.com"
  }
}

12. Login Agent

{
  "name": "login_agent",
  "arguments": {
    "domain": "company.com",
    "queueId": "sales-queue",
    "agentId": "agent001"
  }
}

13. Logout Agent

Logout an agent from a call queue.

{
  "name": "logout_agent",
  "arguments": {
    "domain": "company.com",
    "queueId": "sales-queue",
    "agentId": "agent001"
  }
}

📊 Call Analytics

14. Get CDR Records

Retrieve call detail records with optional filtering.

{
  "name": "get_cdr_records",
  "arguments": {
    "startDate": "2024-01-01",
    "endDate": "2024-01-31",
    "user": "john.doe",
    "domain": "company.com",
    "limit": 100
  }
}

15. Get Agent Statistics

Get agent statistics for a domain.

{
  "name": "get_agent_statistics",
  "arguments": {
    "domain": "company.com",
    "agentId": "agent001"
  }
}

🤖 Auto Attendant

16. Get Auto Attendants

Get auto attendants for a domain.

{
  "name": "get_auto_attendants",
  "arguments": {
    "domain": "company.com"
  }
}

📋 Answer Rules

17. Get User Answer Rules

Get answer rules for a user.

{
  "name": "get_user_answer_rules",
  "arguments": {
    "userId": "john.doe",
    "domain": "company.com"
  }
}

18. Get User Answer Rule

Get specific answer rule for a user.

{
  "name": "get_user_answer_rule",
  "arguments": {
    "userId": "john.doe",
    "domain": "company.com",
    "timeframe": "business"
  }
}

🎵 Media Management

19. Get User Greetings

Get greetings for a user.

{
  "name": "get_user_greetings",
  "arguments": {
    "userId": "john.doe",
    "domain": "company.com"
  }
}

20. Get User Voicemails

Get voicemails for a user.

{
  "name": "get_user_voicemails",
  "arguments": {
    "userId": "john.doe",
    "domain": "company.com"
  }
}

21. Get Music on Hold

Get music on hold files for a domain.

{
  "name": "get_music_on_hold",
  "arguments": {
    "domain": "company.com"
  }
}

💰 Billing

22. Get Billing

Get billing information for a domain.

{
  "name": "get_billing",
  "arguments": {
    "domain": "company.com"
  }
}

🔧 System

23. Test Connection

Test connectivity to the NetSapiens API.

{
  "name": "test_connection",
  "arguments": {}
}

📝 API Examples

Searching for Users

// Search for users with "john" in a specific domain
const result = await mcp.callTool('search_users', {
  query: 'john',
  domain: 'company.com',
  limit: 10
});

Getting User Details

// Get detailed information about a specific user
const result = await mcp.callTool('get_user', {
  userId: 'john.doe',
  domain: 'company.com'
});

Getting Call Records

// Get call records for a specific user in the last month
const result = await mcp.callTool('get_cdr_records', {
  startDate: '2024-01-01',
  endDate: '2024-01-31',
  user: 'john.doe',
  domain: 'company.com'
});

Getting User Devices

// Get devices assigned to a user
const result = await mcp.callTool('get_user_devices', {
  userId: 'john.doe',
  domain: 'company.com'
});

🏃‍♂️ Development

Available Scripts

npm run build - Compile TypeScript to JavaScript
npm run dev - Run in development mode with hot reloading
npm start - Run the compiled server
npm run watch - Watch mode for development
npm run clean - Clean build directory

Project Structure

src/
├── index.ts                 # Main server entry point
├── netsapiens-client.ts     # NetSapiens API client
└── tools/                   # Individual tool implementations

types/
├── config.ts               # Configuration types
└── netsapiens.ts           # NetSapiens API types

Adding New Tools

Define the tool in the ListToolsRequestSchema handler
Add a handler method in the CallToolRequestSchema handler
Implement the tool logic in the NetSapiens client
Update type definitions as needed

🔒 Security

🔐 MCP Security Best Practices

API Tokens: Configure your NetSapiens API tokens securely in your MCP client configuration
Token Security: Use strong API tokens and rotate them regularly
Access Control: Ensure API tokens have minimal required permissions
Rate Limiting: Built-in rate limiting prevents API abuse
Error Handling: Secure error logging without exposing sensitive data
Input Validation: All inputs are validated before processing

🚨 Security Guidelines

Secure MCP Configuration: Store your MCP client configuration files securely
Strong API Tokens: Use secure NetSapiens API tokens and rotate regularly
Monitor Access: Check NetSapiens access logs for unauthorized usage
Regular Audits: Run npm audit regularly for dependency vulnerabilities
Keep Updated: Maintain latest versions for security patches
HTTPS Only: All API communications use secure HTTPS connections
Environment Isolation: Use different tokens for development/production environments

🐛 Troubleshooting

Common Issues

Connection Failed
- Verify your API URL and token in .env
- Check network connectivity to NetSapiens server
- Ensure API token has proper permissions
Build Errors
- Run npm run clean and rebuild
- Check TypeScript configuration
- Verify all dependencies are installed
Tool Not Found
- Ensure the tool name matches exactly
- Check the tool is properly registered in ListToolsRequestSchema

Debug Mode

Enable debug logging by setting DEBUG=true in your .env file:

DEBUG=true

📚 Documentation

🤝 Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🏢 About OITVOIP

OITVOIP provides comprehensive VoIP solutions powered by the NetSapiens platform. This MCP server enables seamless integration between AI applications and our VoIP infrastructure.

Built with ❤️ by the OITVOIP team

From frontend finesse to backend brilliance - we stack it all! ⭐

OITVOIP MCP Server

⚡ Features

🏗️ Architecture

🚀 Quick Start

Prerequisites

Installation

Option 1: From npm (Recommended)

Option 2: From Source

Development Mode

🔧 Configuration

Required Configuration

Optional Configuration

🔌 MCP Client Setup

OpenCode

Claude Desktop

Cursor

Configuration Notes

🛠️ Available Tools (23 Total)

👥 User Management

1. Search Users

2. Get User Details

3. Get User Devices

📞 Phone Number Management

4. Get Phone Numbers

5. Get Phone Number Details

🏢 Domain Management

6. Get Domains

7. Get Domain Details

🎯 Call Center Management

8. Get Call Queues

9. Get Call Queue Details

10. Get Call Queue Agents

11. Get Agents

12. Login Agent

13. Logout Agent

📊 Call Analytics

14. Get CDR Records

15. Get Agent Statistics

🤖 Auto Attendant

16. Get Auto Attendants

📋 Answer Rules

17. Get User Answer Rules

18. Get User Answer Rule

🎵 Media Management

19. Get User Greetings

20. Get User Voicemails

21. Get Music on Hold

💰 Billing

22. Get Billing

🔧 System

23. Test Connection

📝 API Examples

Searching for Users

Getting User Details

Getting Call Records

Getting User Devices

🏃‍♂️ Development

Available Scripts

Project Structure

Adding New Tools

🔒 Security

🔐 MCP Security Best Practices

🚨 Security Guidelines

🐛 Troubleshooting

Common Issues

Debug Mode

📚 Documentation

🤝 Contributing

📄 License

🏢 About OITVOIP

Install Package (if required)

Cursor configuration (mcp.json)