🚀 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 devices

• get_host - Get specific device details

• search_hosts - Search devices by criteria

Virtual Machine Management

• list_vms - List all VMs

• get_vm - Get specific VM details

• list_vm_interfaces - List VM interfaces

IP Address Management

• list_ips - List all IP addresses

• get_ip - Get specific IP details

• search_ips - Search IP addresses

VLAN Management

• list_vlans - List all VLANs

• get_vlan - Get specific VLAN details

• list_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

1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Add tests for new functionality

5. Ensure all tests pass

6. 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