🚀 NetBox MCP Server v1.0
A robust and well-engineered Python MCP (Model Context Protocol) server for NetBox infrastructure access, designed for teaching newer programmers and production use.
🎯 Features
Core Functionality
- NetBox API Integration - Full access to devices, VMs, IP addresses, and VLANs
- HashiCorp Vault Integration - JIT token minting with AppRole authentication
- PostgreSQL State Confidence - Query module referencing muse certainty schema
- MCP Tools - Comprehensive toolset for infrastructure management
Advanced Capabilities
- Tiny LLM Testing - Simulated LLM for CI/CD environments
- Structured JSON Protocol - Clear communication between components
- Performance Optimizations - Connection pooling, caching, retry strategies
- LLM Optimization - Token estimation, response formatting, streaming
🧪 Test Suite
100% Test Success Rate - 129 passed, 1 skipped, 0 failed
Test Coverage
- ✅ Core MCP Server functionality
- ✅ Tiny LLM implementation
- ✅ Structured JSON protocol
- ✅ End-to-end workflows
- ✅ Performance optimizations
- ✅ Tool functionality (hosts, VMs, IPs, VLANs)
- ✅ Error handling and edge cases
🚀 Quick Start
Prerequisites
- Python 3.12+
- NetBox instance
- HashiCorp Vault
- PostgreSQL database
Installation
# Clone the repository
git clone https://github.com/fringemonkey/mcp-dc.git
cd mcp-dc
# Install dependencies
pip install -r requirements.txt
pip install -r requirements-dev.txt
# Run tests
python -m pytest tests/ -v
Configuration
Set up environment variables:
export NETBOX_URL="http://your-netbox-instance"
export VAULT_ADDR="http://your-vault-instance"
export VAULT_TOKEN="your-vault-token"
export POSTGRES_HOST="localhost"
export POSTGRES_DB="mcp_state"
export POSTGRES_USER="mcp_user"
export POSTGRES_PASSWORD="mcp_password"
🛠️ Development
Running Tests
# Run all tests
python -m pytest tests/ -v
# Run specific test categories
python -m pytest tests/ -m unit
python -m pytest tests/ -m integration
python -m pytest tests/ -m performance
# Run with coverage
python -m pytest tests/ --cov=src --cov-report=html
Code Quality
# Format code
black src/ tests/
isort src/ tests/
# Lint code
flake8 src/ tests/
mypy src/
# Security check
bandit -r src/
safety check
📁 Project Structure
mcp-dc/
├── src/ # Source code
│ ├── server.py # Main MCP server
│ ├── netbox_client.py # NetBox API client
│ ├── vault_client.py # Vault authentication
│ ├── state_confidence.py # PostgreSQL client
│ ├── tiny_llm.py # Tiny LLM for testing
│ ├── structured_protocol.py # JSON protocol
│ ├── llm_optimizer.py # LLM optimizations
│ └── tools/ # MCP tools
│ ├── hosts.py
│ ├── virtual_machines.py
│ ├── ip_addresses.py
│ └── vlans.py
├── tests/ # Test suite
│ ├── test_core_functionality.py
│ ├── test_simple_tools.py
│ ├── test_tiny_llm.py
│ ├── test_structured_protocol.py
│ ├── test_llm_optimization.py
│ └── test_simple_performance.py
├── examples/ # Example scripts
├── scripts/ # Utility scripts
├── .github/workflows/ # CI/CD pipelines
└── .devcontainer/ # Development container
🔧 MCP Tools
Host Management
list_hosts- List all devicesget_host- Get specific device detailssearch_hosts- Search devices by criteria
Virtual Machine Management
list_vms- List all VMsget_vm- Get specific VM detailslist_vm_interfaces- List VM interfaces
IP Address Management
list_ips- List all IP addressesget_ip- Get specific IP detailssearch_ips- Search IP addresses
VLAN Management
list_vlans- List all VLANsget_vlan- Get specific VLAN detailslist_vlan_ips- List IPs in VLAN
🎓 Educational Value
This project is designed to teach:
- MCP Protocol - Model Context Protocol implementation
- API Integration - NetBox, Vault, PostgreSQL integration
- Testing Strategies - Unit, integration, performance testing
- Code Quality - Linting, formatting, security practices
- CI/CD - GitHub Actions, automated testing
- Documentation - Comprehensive README and code comments
🚀 Performance
- Connection Pooling - Efficient HTTP connections
- Caching - TTL-based response caching
- Retry Strategies - Exponential backoff for failures
- Memory Efficiency - Optimized data structures
- Concurrent Operations - Async/await patterns
🔒 Security
- Vault Integration - Secure token management
- Input Validation - Parameter sanitization
- Error Handling - Secure error responses
- Security Scanning - Bandit and Safety checks
📊 Monitoring
- Metrics Collection - Performance and usage metrics
- Logging - Structured logging with levels
- Health Checks - Service availability monitoring
- State Confidence - Data reliability scoring
🤝 Contributing
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests for new functionality
- Ensure all tests pass
- Submit a pull request
📄 License
This project is licensed under the MIT License - see the LICENSE file for details.
🎉 Acknowledgments
- NetBox team for the excellent infrastructure management platform
- HashiCorp for Vault security solutions
- PostgreSQL community for the robust database
- MCP protocol contributors
Ready for production deployment! 🚀
Version 1.0 - Zero test failures, comprehensive functionality, production-ready