253 lines
6.3 KiB
Markdown
253 lines
6.3 KiB
Markdown
# Vultr DNS MCP
|
|
|
|
A comprehensive Model Context Protocol (MCP) server for managing Vultr DNS records through natural language interfaces.
|
|
|
|
[](https://www.python.org/downloads/)
|
|
[](https://opensource.org/licenses/MIT)
|
|
[](https://modelcontextprotocol.io/)
|
|
|
|
## Features
|
|
|
|
- **Complete MCP Server**: Full Model Context Protocol implementation with 12 tools and 3 resources
|
|
- **Comprehensive DNS Management**: Support for all major record types (A, AAAA, CNAME, MX, TXT, NS, SRV)
|
|
- **Intelligent Validation**: Pre-creation validation with helpful suggestions and warnings
|
|
- **Configuration Analysis**: DNS setup analysis with security recommendations
|
|
- **CLI Interface**: Complete command-line tool for direct DNS operations
|
|
- **High-Level Client**: Convenient Python API for common operations
|
|
- **Modern Development**: Fast development workflow with uv support
|
|
|
|
## Quick Start
|
|
|
|
### Installation
|
|
|
|
```bash
|
|
# Using uv (recommended - fast and modern)
|
|
uv add vultr-dns-mcp
|
|
|
|
# Or using pip
|
|
pip install vultr-dns-mcp
|
|
```
|
|
|
|
### Basic Usage
|
|
|
|
```bash
|
|
# Set your Vultr API key
|
|
export VULTR_API_KEY="your-api-key"
|
|
|
|
# List domains
|
|
vultr-dns-mcp domains list
|
|
|
|
# List DNS records
|
|
vultr-dns-mcp records list example.com
|
|
|
|
# Set up basic website DNS
|
|
vultr-dns-mcp setup-website example.com 192.168.1.100
|
|
|
|
# Run as MCP server
|
|
uv run python -m vultr_dns_mcp.server
|
|
```
|
|
|
|
### Python API
|
|
|
|
```python
|
|
import asyncio
|
|
from vultr_dns_mcp import VultrDNSClient
|
|
|
|
async def main():
|
|
client = VultrDNSClient("your-api-key")
|
|
|
|
# List domains
|
|
domains = await client.domains()
|
|
|
|
# Add DNS records
|
|
await client.add_a_record("example.com", "www", "192.168.1.100")
|
|
await client.add_mx_record("example.com", "@", "mail.example.com", 10)
|
|
|
|
# Get domain summary
|
|
summary = await client.get_domain_summary("example.com")
|
|
print(f"Domain has {summary['total_records']} records")
|
|
|
|
asyncio.run(main())
|
|
```
|
|
|
|
### MCP Integration
|
|
|
|
This package provides a complete MCP server that can be integrated with MCP-compatible clients:
|
|
|
|
```python
|
|
from vultr_dns_mcp import create_mcp_server, run_server
|
|
|
|
# Create server
|
|
server = create_mcp_server("your-api-key")
|
|
|
|
# Run server
|
|
await run_server("your-api-key")
|
|
```
|
|
|
|
## Development
|
|
|
|
### Prerequisites
|
|
|
|
- Python 3.10+
|
|
- [uv](https://docs.astral.sh/uv/) (recommended) or pip
|
|
- Vultr API key
|
|
|
|
### Setup with uv (Recommended)
|
|
|
|
```bash
|
|
# Clone the repository
|
|
git clone https://github.com/rsp2k/vultr-dns-mcp.git
|
|
cd vultr-dns-mcp
|
|
|
|
# Install dependencies
|
|
uv sync --extra dev
|
|
|
|
# Run tests
|
|
uv run pytest
|
|
|
|
# Run comprehensive test suite
|
|
uv run python run_tests.py --all-checks
|
|
|
|
# Format code
|
|
uv run black src tests
|
|
uv run isort src tests
|
|
|
|
# Type checking
|
|
uv run mypy src
|
|
```
|
|
|
|
### Setup with pip (Traditional)
|
|
|
|
```bash
|
|
# Create virtual environment
|
|
python -m venv .venv
|
|
source .venv/bin/activate # On Windows: .venv\Scripts\activate
|
|
|
|
# Install in development mode
|
|
pip install -e .[dev]
|
|
|
|
# Run tests
|
|
pytest
|
|
|
|
# Run comprehensive test suite
|
|
python run_tests.py --all-checks
|
|
```
|
|
|
|
## MCP Tools Available
|
|
|
|
| Tool | Description |
|
|
|------|-------------|
|
|
| `list_dns_domains` | List all DNS domains |
|
|
| `get_dns_domain` | Get domain details |
|
|
| `create_dns_domain` | Create new domain |
|
|
| `delete_dns_domain` | Delete domain and all records |
|
|
| `list_dns_records` | List records for a domain |
|
|
| `get_dns_record` | Get specific record details |
|
|
| `create_dns_record` | Create new DNS record |
|
|
| `update_dns_record` | Update existing record |
|
|
| `delete_dns_record` | Delete DNS record |
|
|
| `validate_dns_record` | Validate record before creation |
|
|
| `analyze_dns_records` | Analyze domain configuration |
|
|
|
|
## CLI Commands
|
|
|
|
```bash
|
|
# Domain management
|
|
vultr-dns-mcp domains list
|
|
vultr-dns-mcp domains info example.com
|
|
vultr-dns-mcp domains create newdomain.com 192.168.1.100
|
|
|
|
# Record management
|
|
vultr-dns-mcp records list example.com
|
|
vultr-dns-mcp records add example.com A www 192.168.1.100
|
|
vultr-dns-mcp records delete example.com record-id
|
|
|
|
# Setup utilities
|
|
vultr-dns-mcp setup-website example.com 192.168.1.100
|
|
vultr-dns-mcp setup-email example.com mail.example.com
|
|
|
|
# Start MCP server
|
|
vultr-dns-mcp server
|
|
```
|
|
|
|
## Testing
|
|
|
|
This project follows FastMCP testing best practices with comprehensive test coverage:
|
|
|
|
```bash
|
|
# Run all tests (uv)
|
|
uv run pytest
|
|
|
|
# Run specific test categories
|
|
uv run pytest -m unit # Unit tests
|
|
uv run pytest -m integration # Integration tests
|
|
uv run pytest -m mcp # MCP-specific tests
|
|
|
|
# With coverage
|
|
uv run pytest --cov=vultr_dns_mcp --cov-report=html
|
|
|
|
# Full validation suite
|
|
uv run python run_tests.py --all-checks
|
|
```
|
|
|
|
## Contributing
|
|
|
|
1. Fork the repository
|
|
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
|
|
3. Make your changes
|
|
4. Run the test suite (`uv run python run_tests.py --all-checks`)
|
|
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
|
|
|
|
## Error Handling
|
|
|
|
The package provides specific exception types for better error handling:
|
|
|
|
```python
|
|
from vultr_dns_mcp import (
|
|
VultrAPIError,
|
|
VultrAuthError,
|
|
VultrRateLimitError,
|
|
VultrResourceNotFoundError,
|
|
VultrValidationError
|
|
)
|
|
|
|
try:
|
|
await client.get_domain("example.com")
|
|
except VultrAuthError:
|
|
print("Invalid API key or insufficient permissions")
|
|
except VultrResourceNotFoundError:
|
|
print("Domain not found")
|
|
except VultrRateLimitError:
|
|
print("Rate limit exceeded, please try again later")
|
|
except VultrAPIError as e:
|
|
print(f"API error {e.status_code}: {e.message}")
|
|
```
|
|
|
|
## Configuration
|
|
|
|
Set your Vultr API key via environment variable:
|
|
|
|
```bash
|
|
export VULTR_API_KEY="your-vultr-api-key"
|
|
```
|
|
|
|
Or pass directly to the client:
|
|
|
|
```python
|
|
client = VultrDNSClient("your-api-key")
|
|
server = create_mcp_server("your-api-key")
|
|
```
|
|
|
|
## License
|
|
|
|
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
|
|
|
|
## Links
|
|
|
|
- [GitHub Repository](https://github.com/rsp2k/vultr-dns-mcp)
|
|
- [PyPI Package](https://pypi.org/project/vultr-dns-mcp/)
|
|
- [Vultr API Documentation](https://www.vultr.com/api/)
|
|
- [Model Context Protocol](https://modelcontextprotocol.io/)
|
|
- [uv Package Manager](https://docs.astral.sh/uv/) |