# DevContainer Setup for NetBox MCP Server
This repository includes a comprehensive devcontainer configuration that works with GitHub Codespaces, VS Code, and any IDE that supports devcontainers.
## 🚀 Quick Start
### GitHub Codespaces
1. Click the "Code" button on GitHub
2. Select "Codespaces" → "Create codespace on main"
3. Wait for the environment to set up (~2-3 minutes)
4. Start coding immediately!
### VS Code with Dev Containers
1. Install the "Dev Containers" extension
2. Open this repository in VS Code
3. Click "Reopen in Container" when prompted
4. Wait for the environment to set up
### Other IDEs
Any IDE that supports devcontainers (like JetBrains IDEs with the devcontainer plugin) will work with this configuration.
## 🛠️ What's Included
### Development Environment
- **Python 3.12** with all development tools
- **VS Code** with pre-configured Python extensions
- **Docker & Docker Compose** for local services
- **Git** with proper configuration
- **GitHub CLI** for repository management
### Mock Services
- **Mock NetBox API** server (port 8000)
- **Mock HashiCorp Vault** server (port 8200)
- **PostgreSQL** database (port 5432) with state confidence schema
- **Redis** cache (port 6379) for optional caching
### Development Tools
- **Pre-commit hooks** for code quality
- **Comprehensive test suite** with multiple test categories
- **Code formatting** (Black, isort)
- **Linting** (Flake8, MyPy)
- **Security scanning** (Bandit, Safety)
- **Performance testing** tools
## 📊 Test Results
The devcontainer includes a streamlined test suite that achieves:
- ✅ **100% Test Success Rate**: 129 passed, 1 skipped, 0 failed
- ✅ **Tool Discovery**: All MCP tools discovered correctly
- ✅ **Tool Execution**: 100% success rate for tool calls
- ✅ **Error Handling**: Proper error responses for invalid inputs
- ✅ **Performance**: Optimized response times and concurrent execution
- ✅ **No External Dependencies**: All tests use mocks
## 🎯 Available Commands
### Development Services
```bash
# Start all development services
./scripts/start-dev-services.sh # Linux/Mac
scripts/start-dev-services.bat # Windows
# Stop all development services
./scripts/stop-dev-services.sh # Linux/Mac
scripts/stop-dev-services.bat # Windows
```
### Testing
```bash
# Run comprehensive test suite
./scripts/test-mcp-server.sh # Linux/Mac
scripts/test-mcp-server.bat # Windows
# Run specific test categories
pytest -m unit # Unit tests
pytest -m performance # Performance tests
pytest -m error_handling # Error handling tests
pytest -m edge_cases # Edge case tests
# Run with coverage
pytest --cov=src --cov-report=html
```
### Code Quality
```bash
# Format code
black src/ tests/
isort src/ tests/
# Lint code
flake8 src/ tests/
mypy src/
# Security scan
bandit -r src/
safety check
```
## 🌐 Service URLs
| Service | Local URL | Codespace URL |
|---------|-----------|---------------|
| NetBox Mock | http://localhost:8000 | https://your-codespace-8000.app.github.dev |
| Vault Mock | http://localhost:8200 | https://your-codespace-8200.app.github.dev |
| PostgreSQL | localhost:5432 | localhost:5432 |
| Redis | localhost:6379 | localhost:6379 |
## ⚙️ Environment Variables
The devcontainer automatically sets these environment variables:
```bash
# MCP Server Configuration
MCP_SERVER_LOG_LEVEL=DEBUG
MCP_SERVER_HOST=0.0.0.0
MCP_SERVER_PORT=8080
# NetBox Configuration
NETBOX_URL=http://localhost:8000 # or Codespace URL
NETBOX_TOKEN=dev-token
# Vault Configuration
VAULT_ADDR=http://localhost:8200 # or Codespace URL
VAULT_TOKEN=dev-token
VAULT_PATH=secret/netbox/jit-tokens
# PostgreSQL Configuration
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_DB=mcp_state
POSTGRES_USER=mcp_user
POSTGRES_PASSWORD=mcp_password
POSTGRES_SSLMODE=prefer
# Development Flags
DEBUG=true
DEVELOPMENT=true
TESTING=true
```
## 📚 Learning Resources
This devcontainer setup is perfect for learning MCP development:
- **Comprehensive Documentation**: See `docs/TESTING.md` for detailed testing guidance
- **Example Code**: Check `examples/` for practical examples
- **Test Patterns**: Study the test files for best practices
- **Mock Services**: Learn how to work with external APIs using mocks
## 🔧 Customization
### Adding New Tools
1. Create tool handlers in `src/tools/`
2. Register tools in `src/server.py`
3. Add tests in `tests/`
4. Update documentation
### Modifying Services
Edit `docker-compose.dev.yml` to customize the mock services or add new ones.
### Environment Variables
Modify `.devcontainer/devcontainer.json` to add or change environment variables.
## 🐛 Troubleshooting
### Services Not Starting
```bash
# Check service status
docker-compose -f docker-compose.dev.yml ps
# View logs
docker-compose -f docker-compose.dev.yml logs
# Restart services
docker-compose -f docker-compose.dev.yml restart
```
### Database Issues
```bash
# Check PostgreSQL status
docker-compose -f docker-compose.dev.yml exec postgres pg_isready -U mcp_user -d mcp_state
# Connect to database
docker-compose -f docker-compose.dev.yml exec postgres psql -U mcp_user -d mcp_state
```
### Test Failures
```bash
# Run tests with verbose output
pytest tests/ -v --tb=short
# Run specific test
pytest tests/test_unit_tools.py::TestHostTools::test_list_hosts_success -v
```
### Port Conflicts
If you have port conflicts, modify the ports in `docker-compose.dev.yml` and update the environment variables accordingly.
## 🎉 Success!
Your devcontainer is now ready for MCP development! The environment includes everything needed to:
- ✅ Develop MCP servers
- ✅ Test with mock services
- ✅ Learn best practices
- ✅ Contribute to the project
- ✅ Teach others about MCP
Happy coding! 🚀
