mcp-vultr/CLAUDE.md

Vultr DNS MCP Package

A Model Context Protocol (MCP) server for managing Vultr DNS domains and records through natural language interfaces.

Project Overview

This package provides both an MCP server and a standalone Python client for Vultr DNS management. It supports all major DNS record types (A, AAAA, CNAME, MX, TXT, NS, SRV) with validation, analysis, and batch operations.

Quick Start

Installation

# Using uv (recommended)
uv add vultr-dns-mcp

# Or using pip
pip install vultr-dns-mcp

Basic Usage

# CLI - requires VULTR_API_KEY environment variable
vultr-dns-mcp domains list
vultr-dns-mcp records list example.com

# As MCP server
uv run python -m vultr_dns_mcp.server --api-key YOUR_API_KEY

Development Setup

Dependencies

# Using uv (recommended)
uv sync --extra dev

# Or using pip
pip install -e .[dev]

Running Tests

# All tests (using uv - recommended)
uv run pytest

# Specific categories
uv run pytest -m unit
uv run pytest -m mcp
uv run pytest -m integration

# With coverage
uv run pytest --cov=vultr_dns_mcp --cov-report=html

# Comprehensive test runner
uv run python run_tests.py --all-checks

# Traditional approach (fallback)
pytest

Code Quality

# Using uv (recommended)
uv run black src tests
uv run isort src tests
uv run mypy src
uv run flake8 src tests

# Traditional approach
black src tests
isort src tests
mypy src
flake8 src tests

Build & Publishing

# Using uv (recommended)
uv build
uv run twine check dist/*
uv run twine upload --repository testpypi dist/*
uv run twine upload dist/*

# Traditional approach
python -m build
python -m twine check dist/*
python -m twine upload --repository testpypi dist/*
python -m twine upload dist/*

Test Structure

Following FastMCP testing best practices:

• tests/conftest.py - Test configuration and fixtures
• tests/test_mcp_server.py - MCP server functionality tests using in-memory pattern
• tests/test_client.py - VultrDNSClient tests
• tests/test_cli.py - CLI interface tests
• tests/test_vultr_server.py - Core VultrDNSServer tests
• tests/test_package_validation.py - Package integrity tests

Test Markers

• @pytest.mark.unit - Individual component testing
• @pytest.mark.integration - Component interaction testing
• @pytest.mark.mcp - MCP-specific functionality
• @pytest.mark.slow - Performance and timeout tests

Coverage Goals

• Overall: 80%+ (enforced)
• MCP Tools: 100% (critical functionality)
• API Client: 95%+ (core functionality)
• CLI Commands: 90%+ (user interface)

Project Structure

vultr-dns-mcp/
├── src/vultr_dns_mcp/
│   ├── client.py           # High-level DNS client
│   ├── server.py           # Core Vultr API client
│   ├── mcp_server.py       # MCP server implementation
│   └── cli.py              # Command-line interface
├── tests/                  # Comprehensive test suite
├── docs/                   # Documentation
└── pyproject.toml          # Project configuration

Key Features

MCP Tools (12 total)

• Domain management: list, create, delete, get details
• DNS record operations: CRUD for all record types
• Validation: Pre-creation validation with suggestions
• Analysis: Configuration analysis with security recommendations

MCP Resources

• Domain discovery endpoints
• DNS record resources
• Configuration capabilities

CLI Commands

• Domain operations: domains list|create|delete|get
• Record operations: records list|create|update|delete
• Setup utilities: setup website|email

Version History

Current: 1.0.1

• Fixed FastMCP server initialization
• Corrected MCP server creation for current FastMCP version
• Simplified initialization to use only name parameter

1.0.0 - Initial Release

• Complete MCP server implementation
• Python client library
• CLI interface
• Support for all DNS record types
• Validation and analysis features
• Comprehensive test suite

CI/CD Pipeline

GitHub Actions

• Multi-Python testing (3.8-3.12)
• Progressive test execution: validation → unit → integration → mcp
• Code quality gates: black, isort, flake8, mypy
• Security scanning: safety, bandit
• Package validation: build, install, test CLI

Quality Gates

1. All tests pass on all Python versions
2. Code coverage meets 80% threshold
3. Code quality checks pass
4. Security scans clean
5. Package builds and installs correctly

Publishing

Automated (Recommended)

1. Update version in pyproject.toml
2. Commit and push changes
3. Create and push version tag: git tag v1.0.2 && git push origin v1.0.2
4. Workflow automatically publishes to PyPI

Manual

Use the GitHub Actions "Publish to PyPI" workflow with manual trigger.

Development Guidelines

Testing

• Use FastMCP in-memory testing pattern for MCP functionality
• Mock external dependencies (Vultr API)
• Maintain high coverage on critical paths
• Follow pytest best practices

Code Style

• Black formatting
• isort import sorting
• Type hints with mypy
• Comprehensive docstrings
• Security best practices

Release Process

1. Update version in pyproject.toml
2. Update CHANGELOG.md
3. Run full test suite
4. Create git tag
5. Automated publishing via GitHub Actions

Troubleshooting

Common Issues

• ImportError: Run pip install -e . from repository root
• AsyncioError: Ensure asyncio_mode = "auto" in pyproject.toml
• MockError: Check that test fixtures are properly configured
• API Errors: Verify VULTR_API_KEY environment variable

Test Debugging

# Single test with verbose output (using uv)
uv run pytest tests/test_mcp_server.py::TestMCPTools::test_list_dns_domains_tool -vvv

# Check pytest configuration
uv run pytest --collect-only tests/

# Validate imports
uv run python -c "from vultr_dns_mcp.server import create_mcp_server"

# Traditional approach
pytest tests/test_mcp_server.py::TestMCPTools::test_list_dns_domains_tool -vvv
pytest --collect-only tests/
python -c "from vultr_dns_mcp.server import create_mcp_server"

Support & Documentation

• GitHub: https://github.com/rsp2k/vultr-dns-mcp
• PyPI: https://pypi.org/project/vultr-dns-mcp/
• Documentation: Complete API documentation and examples in package
• Issues: Use GitHub Issues for bug reports and feature requests