llm-automation-docs-and-remediation-engine/README_WEB.md

🌐 Sistema Web e MCP - Documentazione Datacenter

Sistema completo per pubblicazione web della documentazione datacenter con API REST e MCP Server per connessioni LLM alle infrastrutture.

📦 Componenti

1. FastAPI Documentation Server

• Porta: 8000
• Funzione: Serve documentazione MkDocs compilata + API REST
• Features:
  • Documentazione web responsive
  • API REST per accesso programmatico
  • Ottimizzazione per LLM
  • Search full-text
  • Statistics e metadata

2. MCP Server

• Porta: 8001
• Funzione: Model Context Protocol - Connessioni infrastruttura
• Features:
  • SSH execution
  • SNMP queries
  • API REST integration
  • VMware, Cisco, storage shortcuts
  • Audit logging

3. MkDocs Static Site

• Framework: Material for MkDocs
• Build: Automatico via CI/CD
• Features:
  • Responsive design
  • Dark mode
  • Search integrata
  • Git revision dates
  • Navigation ottimizzata

4. Nginx Reverse Proxy

• Porta: 80 (HTTP) → 443 (HTTPS)
• Funzione: SSL termination, caching, rate limiting
• Features:
  • HTTPS con TLS 1.2+
  • Gzip compression
  • Static file caching
  • Security headers

🚀 Quick Start

Prerequisiti

- Docker & Docker Compose
- Git
- Accesso management network

Setup Iniziale

1. Clone repository

git clone https://github.com/company/datacenter-docs.git
cd datacenter-docs

2. Configura credenziali

# Crea file MCP config
cp config/mcp_config.example.json config/mcp_config.json
# Edita con credenziali reali
vim config/mcp_config.json

# Crea .env per Docker
cat > .env << 'EOF'
VCENTER_PASSWORD=your_password
SWITCH_PASSWORD=your_password
STORAGE_API_KEY=your_api_key
EOF

3. Build e avvia servizi

# Build documentazione
./scripts/build-docs.sh

# Avvia con Docker Compose
docker-compose up -d

# Verifica health
curl http://localhost:8000/health
curl http://localhost:8001/methods

4. Accedi alla documentazione

http://localhost:8000/docs/
http://localhost:8000/api/docs  (API Swagger)
http://localhost:8001/docs      (MCP Swagger)

📁 Struttura File

datacenter-docs/
├── api/                          # FastAPI application
│   ├── main.py                  # Main FastAPI app
│   └── requirements-api.txt     # Python dependencies
├── mcp-server/                   # MCP Server
│   └── server.py                # MCP implementation
├── docs/                         # MkDocs source
│   ├── index.md                 # Homepage
│   ├── sections/                # Documentation sections
│   └── api/                     # API documentation
├── templates/                    # Template documentazione
├── nginx/                        # Nginx configuration
│   └── nginx.conf
├── scripts/                      # Utility scripts
│   ├── build-docs.sh
│   └── deploy.sh
├── .github/workflows/            # CI/CD pipelines
│   └── build-deploy.yml
├── config/                       # Configuration files
│   └── mcp_config.json
├── mkdocs.yml                    # MkDocs configuration
├── Dockerfile                    # Multi-stage Dockerfile
├── docker-compose.yml            # Docker Compose config
└── docker-entrypoint.sh         # Container entrypoint

🔄 Workflow Automazione

1. Generazione Documentazione

# LLM genera/aggiorna template
python3 main.py --section 01

# Commit su Git
git add templates/
git commit -m "docs: update infrastructure section"
git push origin main

2. CI/CD Pipeline

Push to main
  ↓
GitHub Actions triggered
  ↓
├─ Lint & Validate
├─ Build MkDocs
├─ Build Docker Image
├─ Security Scan
└─ Deploy to Production
  ↓
Documentation live!

3. Accesso Documentazione

User → Nginx → FastAPI → MkDocs Site
                      ↓
                   API REST
                      ↓
                LLM-optimized

🔌 API Usage

Python Client Example

import requests

# Get all sections
r = requests.get('http://localhost:8000/api/v1/sections')
sections = r.json()

for section in sections:
    print(f"{section['title']}: {section['token_estimate']} tokens")

# Get specific section
r = requests.get('http://localhost:8000/api/v1/sections/02_networking')
content = r.json()
print(content['content'])

# LLM-optimized content
r = requests.get('http://localhost:8000/api/v1/llm-optimized/02_networking')
llm_data = r.json()
print(f"Ready for LLM: {llm_data['token_count']} tokens")

cURL Examples

# Health check
curl http://localhost:8000/health

# Get summary
curl http://localhost:8000/api/v1/summary | jq

# Search
curl "http://localhost:8000/api/v1/search?q=vmware" | jq

# Get section as HTML
curl "http://localhost:8000/api/v1/sections/03_server_virtualizzazione?format=html"

🤖 MCP Usage

Python MCP Client

import asyncio
import requests

async def query_infrastructure():
    base_url = 'http://localhost:8001'
    
    # List available methods
    r = requests.get(f'{base_url}/methods')
    print(r.json())
    
    # Execute SSH command
    r = requests.post(f'{base_url}/execute/ssh', json={
        'connection_name': 'switch-core-01',
        'command': 'show version'
    })
    result = r.json()
    print(f"Output: {result['output']}")
    
    # SNMP query
    r = requests.post(f'{base_url}/execute/snmp/get', json={
        'connection_name': 'ups-01',
        'oid': '.1.3.6.1.2.1.33.1.2.1.0'
    })
    ups_status = r.json()
    print(f"UPS Status: {ups_status['output']}")

asyncio.run(query_infrastructure())

Available MCP Methods

• ssh_execute - Execute commands via SSH
• ssh_get_config - Get device configurations
• snmp_get - SNMP GET query
• snmp_walk - SNMP WALK query
• api_request - Generic API call
• vmware_get_vms - Get VMware VMs
• vmware_get_hosts - Get ESXi hosts
• cisco_get_interfaces - Cisco interface status
• ups_get_status - UPS status via SNMP

🔐 Security

Access Control

Documentation (port 8000):
  - Public read access (internal network)
  - API key for external access

MCP Server (port 8001):
  - Internal network only
  - No external exposure
  - Audit logging enabled
  - Read-only operations

Secrets Management

# Use environment variables
export VCENTER_PASSWORD="..."
export SWITCH_PASSWORD="..."

# Or use Docker secrets
docker secret create vcenter_pass vcenter_password.txt

# Or use HashiCorp Vault
vault kv get -field=password datacenter/vcenter

Network Security

# Firewall rules
# Allow: Management network → MCP Server
# Allow: Internal network → Documentation
# Deny: External → MCP Server
# Allow: External → Documentation (with auth)

📊 Monitoring

Health Checks

# FastAPI health
curl http://localhost:8000/health

# MCP health
curl http://localhost:8001/methods

# Docker health
docker ps
docker-compose ps

Logs

# Application logs
docker-compose logs -f docs-server

# Nginx logs
docker-compose logs -f nginx

# Specific service
docker-compose logs -f docs-server | grep ERROR

Metrics

# Documentation statistics
curl http://localhost:8000/api/v1/stats | jq

# Response times
curl -w "@curl-format.txt" -o /dev/null -s http://localhost:8000/health

🛠️ Development

Local Development

# Install dependencies
pip install -r requirements.txt
pip install -r api/requirements-api.txt

# Run FastAPI locally
cd api
uvicorn main:app --reload --port 8000

# Run MCP server locally
cd mcp-server
uvicorn server:mcp_app --reload --port 8001

# Build docs locally
mkdocs serve

Testing

# Run tests
pytest tests/ -v

# Coverage
pytest tests/ --cov=api --cov=mcp-server --cov-report=html

# Linting
flake8 api/ mcp-server/
black --check api/ mcp-server/

🚢 Deployment

Production Deployment

# Via script
./scripts/deploy.sh

# Manual
docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d

# Verify
curl https://docs.datacenter.local/health

Update Documentation

# Pull latest
git pull origin main

# Rebuild
docker-compose build docs-server

# Rolling update
docker-compose up -d --no-deps docs-server

Rollback

# Rollback to previous image
docker-compose down
docker-compose up -d docs-server:previous-tag

# Or restore from backup
cp -r backup/docs/* docs/
docker-compose restart docs-server

📝 Configuration

Environment Variables

# Application
ENVIRONMENT=production
LOG_LEVEL=info

# MCP Connections
VCENTER_PASSWORD=xxx
SWITCH_PASSWORD=xxx
STORAGE_API_KEY=xxx

# Optional
REDIS_URL=redis://localhost:6379
DATABASE_URL=postgresql://user:pass@localhost/db

MkDocs Configuration

Edit mkdocs.yml:

site_name: Your Site Name
theme:
  name: material
  palette:
    primary: indigo
nav:
  - Home: index.md
  # ...

Nginx Configuration

Edit nginx/nginx.conf:

# Rate limiting
limit_req_zone $binary_remote_addr zone=api_limit:10m rate=10r/s;

# SSL certificates
ssl_certificate /etc/nginx/ssl/cert.pem;
ssl_certificate_key /etc/nginx/ssl/key.pem;

🔍 Troubleshooting

Common Issues

Port già in uso

# Check what's using port
sudo lsof -i :8000
sudo lsof -i :8001

# Stop conflicting service
sudo systemctl stop service_name

Docker build failed

# Clean build
docker-compose build --no-cache docs-server

# Check logs
docker-compose logs docs-server

MCP connection errors

# Test connectivity
telnet switch.domain.local 22
snmpget -v2c -c public ups.domain.local .1.3.6.1.2.1.1.1.0

# Check config
cat config/mcp_config.json | jq

# Test connection
curl -X GET http://localhost:8001/test/switch-core-01

Documentation not updating

# Rebuild docs
./scripts/build-docs.sh

# Force rebuild
docker-compose down
docker-compose up -d --build

# Check pipeline
# Go to GitHub Actions and check logs

📚 Additional Resources

• MkDocs Documentation
• Material for MkDocs
• FastAPI Documentation
• Docker Compose

🤝 Contributing

1. Fork repository
2. Create feature branch
3. Make changes
4. Test locally
5. Submit pull request

📞 Support

• Email: automation-team@company.com
• Issues: https://github.com/company/datacenter-docs/issues
• Wiki: https://github.com/company/datacenter-docs/wiki

📄 License

Internal use only - Company Proprietary

---

Sistema Web e MCP per Documentazione Datacenter
Versione: 1.0.0
Maintainer: Automation Team
Last Update: 2025-01-XX