Revise README for improved clarity and structure

Updated README to enhance clarity and structure, added sections for installation, configuration, and troubleshooting.

Author: Warezloder

README.md

@@ -1,22 +1,338 @@
-# vsphere-mcp-pro
+# vSphere-MCP-Pro
 
-Secure, feature-rich MCP server for VMware vCenter 8.0+.
+A secure, feature-rich Machine Control Plane (MCP) server for VMware vCenter 8.0+.  
+This service exposes a controlled set of vCenter operations via MCP tools, including VM lifecycle management, snapshot operations, datastore/host discovery, and more—wrapped with audit logging, RBAC authorization, and rate limiting.
 
-## Highlights
-- SSL verify on by default, optional CA bundle
-- vCenter host allow-list
-- Bearer token auth + role→tools gating
-- Destructive ops require `confirm=True`
-- Rate limiting + JSON-lines audit
-- Supports `/api` (preferred) and `/rest` endpoints
+---
+
+## Table of Contents
+- [Overview](#overview)
+- [Key Features](#key-features)
+- [Architecture](#architecture)
+- [Directory Structure](#directory-structure)
+- [Installation](#installation)
+- [Configuration](#configuration)
+- [Running the Server](#running-the-server)
+- [Available Tools / API](#available-tools--api)
+- [Audit Logging](#audit-logging)
+- [Rate Limiting](#rate-limiting)
+- [Security Model](#security-model)
+- [Development](#development)
+- [Docker Usage](#docker-usage)
+- [Troubleshooting](#troubleshooting)
+- [License](#license)
+
+---
+
+## Overview
+
+`vsphere-mcp-pro` is an MCP server designed for VMware vCenter 8.0+ environments.  
+It provides:
+
+- Safe, structured access to vCenter operations  
+- Strict authorization via roles → allowed tools  
+- Snapshot + VM lifecycle operations  
+- Auditing and rate limiting for secure multi-tenant use  
+- Support for both `/api` (preferred) and `/rest` vCenter endpoints  
+- Optional host allow-listing to prevent accidental cross-cluster operations
+
+The server runs using `FastMCP` and automatically wraps every tool operation with:
+- Token-based RBAC (`Authorizer`)
+- Token bucket rate limiting
+- JSONL audit logging
+- Optional confirmation for destructive operations
+
+---
+
+## Key Features
+
+### ✔ Secure by design
+- SSL verification enabled by default  
+- Optional CA bundle support  
+- Allowed-host enforcement prevents unauthorized vCenter targets  
+
+### ✔ Strong authorization model
+- Token → role mapping  
+- Role → allowed-tools mapping  
+- Enforced unless explicitly disabled  
+- Destructive operations require `confirm=True`
+
+### ✔ Operationally robust
+- Automatic retry logic for vCenter API calls (`Retry + HTTPAdapter`)  
+- Session auto-renewal on 401  
+- Extensive logging for auditing and observability  
+
+### ✔ High performance
+- Thread-safe vCenter session management  
+- MCP server built with `uvicorn`
+
+---
+
+## Architecture
+
+**Key modules:**
+
+- **`server.py`**  
+  Builds the MCP server, registers all tools, injects authorization, rate-limiting, and auditing wrappers.
+
+- **`vsphere_client.py`**  
+  Handles retries, authentication, and REST/API mode switching for VMware vCenter.
+
+- **`authz.py`**  
+  Implements:
+  - Token → role resolution  
+  - Role → tool gating  
+  - Token bucket rate limiting  
+
+- **`audit.py`**  
+  Writes JSON-lines logs for every operation.
+
+- **`config.py`**  
+  Loads environment variables into a typed `AppConfig` using `pydantic`.
+
+---
+
+## Directory Structure
+
+```Structure
+
+/
+├── vsphere-mcp-pro/        # Python package
+│   ├── server.py
+│   ├── vsphere_client.py
+│   ├── authz.py
+│   ├── audit.py
+│   ├── config.py
+├── pyproject.toml
+├── README.md
+├── .env.example
+├── Dockerfile
+
+````
+
+---
+
+## Installation
+
+### Prerequisites
+
+- Python **3.10+**
+- VMware vCenter **8.0+**
+- A valid set of API credentials
+
+### Install from source
 
-## Quickstart
 ```bash
-cp env.example .env
-# Fill VCENTER_* and tokens
+
+git clone https://github.com/Warezloder/vSphere-MCP-Pro
+cd vsphere-mcp-pro
+pip install -e .
+
+````
+
+---
+
+## Configuration
+
+Configuration is environment-driven. Copy the example file:
+
+```bash
+
+cp .env.example .env
+
+```
+
+### Required Environment Variables
+
+| Variable                | Description                                   |
+| ----------------------- | --------------------------------------------- |
+| `VCENTER_HOST`          | vCenter hostname/IP                           |
+| `VCENTER_USER`          | vCenter username                              |
+| `VCENTER_PASSWORD`      | vCenter password                              |
+| `ROLES_TO_TOOLS`        | JSON map of role → allowed tools              |
+| `TOKENS_TO_ROLES`       | JSON map of token → role                      |
+| `ALLOWED_VCENTER_HOSTS` | Optional allowlist for multi-host deployments |
+
+Example snippet:
+
+```python
+
+VCENTER_HOST=vcenter.example.com
+VCENTER_USER=administrator@vsphere.local
+VCENTER_PASSWORD=s3cret
+TOKENS_TO_ROLES={"token1": "read", "token2": "ops"}
+ROLES_TO_TOOLS={"read":["list_vms","get_vm_details"],"ops":["power_on_vm"]}
+
+```
+
+---
+
+## Running the Server
+
+### Local execution
+
+```bash
+
 python -m vsphere_mcp_pro.server
 
-# Docker
-docker build -t vsphere-mcp-pro:latest .
-docker run --rm -p 8000:8000 --env-file .env vsphere-mcp-pro:latest
 ```
+
+Server defaults (override via env vars):
+
+* Host: `0.0.0.0`
+* Port: `8000`
+* MCP path: `/mcp`
+
+---
+
+## Available Tools / API
+
+Below is a categorized summary of available MCP tools exposed by the server.
+
+### VM Discovery
+
+* `list_vms`
+* `get_vm_details`
+
+### Inventory Discovery
+
+* `list_hosts`
+* `list_datastores`
+* `list_networks`
+* `list_datacenters`
+* `get_datastore_usage`
+* `get_resource_utilization_summary`
+
+### Power Operations
+
+* `power_on_vm`
+* `power_off_vm`
+* `restart_vm`
+
+### Snapshot Operations
+
+* `list_vm_snapshots`
+* `create_vm_snapshot`
+* `delete_vm_snapshot`
+
+### VM Resource Management
+
+* `modify_vm_resources` (CPU / memory)
+
+### Destructive Operations (require `confirm=True`)
+
+* `delete_vm`
+* `delete_vm_snapshot`
+
+---
+
+## Audit Logging
+
+Every MCP tool call is logged as a JSON line containing:
+
+* tool name
+* execution status
+* duration (ms)
+* sanitized arguments (passwords & tokens masked)
+* optional error message
+* role + host context
+
+Logs either write to stdout or to the configured `AUDIT_LOG_PATH`.
+
+---
+
+## Rate Limiting
+
+Uses a token-bucket strategy:
+
+* Configurable `RATE_LIMIT_RPS` and `RATE_LIMIT_BURST`
+* Separate buckets per token
+* Disabled by setting `RATE_LIMIT=false`
+
+---
+
+## Security Model
+
+| Mechanism              | Purpose                                   |
+| ---------------------- | ----------------------------------------- |
+| SSL verification       | Prevent MITM attacks                      |
+| Allowed-host list      | Prevent unauthorized target selection     |
+| Role → tool mapping    | Enforce least-privilege principle         |
+| Token authentication   | Multi-tenant safe access                  |
+| Required confirmations | Prevent accidental destructive operations |
+| Rate limiting          | Protects vCenter and MCP server           |
+
+---
+
+## Development
+
+### Install dev deps
+
+```bash
+
+pip install -e .[dev]
+
+```
+
+### Run with autoreload
+
+```bash
+
+uvicorn vsphere_mcp_pro.server:main --reload
+
+```
+
+---
+
+## Docker Usage
+
+### Build
+
+```bash
+
+docker build -t vsphere-mcp-pro .
+
+```
+
+### Run
+
+```bash
+
+docker run \
+  --rm \
+  -p 8000:8000 \
+  --env-file .env \
+  vsphere-mcp-pro
+  
+```
+
+---
+
+## Troubleshooting
+
+### "login failed: HTTP 401"
+
+* Verify vCenter username/password
+* Ensure correct API mode (`VSPHERE_API_MODE=api|rest`)
+
+### "Hostname not in allowed set"
+
+* Add the hostname to `ALLOWED_VCENTER_HOSTS`
+
+### Rate limit errors
+
+* Increase `RATE_LIMIT_BURST`
+* Adjust per-token usage
+
+### SSL certificate issues
+
+* Set `VCENTER_CA_BUNDLE`
+  or
+* Disable SSL verification only if absolutely necessary:
+  `INSECURE=true`
+
+---
+
+## License
+
+This project is licensed under your chosen repository license.