docs: add Starlight documentation site
- Set up Astro + Starlight for documentation - Create comprehensive docs covering: - Getting started (introduction, installation, quickstart) - Configuration (environment variables, vCenter connection) - Deployment (Docker, OAuth multi-user) - Reference (94 tools, RBAC permissions, architecture) - VMware-inspired blue color scheme - Custom logo and styling - Search enabled via Pagefind
This commit is contained in:
parent
a0f405412e
commit
0e7942f510
19
docs/.gitignore
vendored
Normal file
19
docs/.gitignore
vendored
Normal file
@ -0,0 +1,19 @@
|
||||
# Dependencies
|
||||
node_modules/
|
||||
|
||||
# Build output
|
||||
dist/
|
||||
.astro/
|
||||
|
||||
# Editor
|
||||
.idea/
|
||||
.vscode/
|
||||
*.swp
|
||||
*.swo
|
||||
|
||||
# OS
|
||||
.DS_Store
|
||||
Thumbs.db
|
||||
|
||||
# Logs
|
||||
*.log
|
||||
2
docs/.pnpm-approve-builds
Normal file
2
docs/.pnpm-approve-builds
Normal file
@ -0,0 +1,2 @@
|
||||
esbuild@*
|
||||
sharp@*
|
||||
70
docs/astro.config.mjs
Normal file
70
docs/astro.config.mjs
Normal file
@ -0,0 +1,70 @@
|
||||
// @ts-check
|
||||
import { defineConfig } from 'astro/config';
|
||||
import starlight from '@astrojs/starlight';
|
||||
|
||||
// https://astro.build/config
|
||||
export default defineConfig({
|
||||
site: 'https://docs.mcvsphere.dev',
|
||||
telemetry: false,
|
||||
devToolbar: { enabled: false },
|
||||
integrations: [
|
||||
starlight({
|
||||
title: 'mcvsphere',
|
||||
description: 'AI-driven VMware vSphere management via Model Context Protocol',
|
||||
logo: {
|
||||
src: './src/assets/logo.svg',
|
||||
replacesTitle: false,
|
||||
},
|
||||
social: {
|
||||
github: 'https://git.supported.systems/MCP/mcvsphere',
|
||||
},
|
||||
sidebar: [
|
||||
{
|
||||
label: 'Getting Started',
|
||||
items: [
|
||||
{ label: 'Introduction', slug: 'getting-started/introduction' },
|
||||
{ label: 'Installation', slug: 'getting-started/installation' },
|
||||
{ label: 'Quick Start', slug: 'getting-started/quickstart' },
|
||||
],
|
||||
},
|
||||
{
|
||||
label: 'Configuration',
|
||||
items: [
|
||||
{ label: 'Environment Variables', slug: 'configuration/environment' },
|
||||
{ label: 'vCenter Connection', slug: 'configuration/vcenter' },
|
||||
],
|
||||
},
|
||||
{
|
||||
label: 'Deployment',
|
||||
items: [
|
||||
{ label: 'Docker Setup', slug: 'deployment/docker' },
|
||||
{ label: 'OAuth Multi-User', slug: 'deployment/oauth' },
|
||||
],
|
||||
},
|
||||
{
|
||||
label: 'Reference',
|
||||
items: [
|
||||
{ label: 'Tool Reference', slug: 'reference/tools' },
|
||||
{ label: 'RBAC Permissions', slug: 'reference/rbac' },
|
||||
{ label: 'Architecture', slug: 'reference/architecture' },
|
||||
],
|
||||
},
|
||||
],
|
||||
customCss: [
|
||||
'./src/styles/custom.css',
|
||||
],
|
||||
head: [
|
||||
{
|
||||
tag: 'meta',
|
||||
attrs: {
|
||||
name: 'theme-color',
|
||||
content: '#146eb4',
|
||||
},
|
||||
},
|
||||
],
|
||||
editLink: {
|
||||
baseUrl: 'https://git.supported.systems/MCP/mcvsphere/edit/main/docs/',
|
||||
},
|
||||
}),
|
||||
],
|
||||
});
|
||||
15
docs/package.json
Normal file
15
docs/package.json
Normal file
@ -0,0 +1,15 @@
|
||||
{
|
||||
"name": "mcvsphere-docs",
|
||||
"type": "module",
|
||||
"version": "0.0.1",
|
||||
"scripts": {
|
||||
"dev": "astro dev",
|
||||
"build": "astro build",
|
||||
"preview": "astro preview"
|
||||
},
|
||||
"dependencies": {
|
||||
"@astrojs/starlight": "^0.32.3",
|
||||
"astro": "^5.1.6",
|
||||
"sharp": "^0.33.5"
|
||||
}
|
||||
}
|
||||
4429
docs/pnpm-lock.yaml
generated
Normal file
4429
docs/pnpm-lock.yaml
generated
Normal file
File diff suppressed because it is too large
Load Diff
4
docs/public/robots.txt
Normal file
4
docs/public/robots.txt
Normal file
@ -0,0 +1,4 @@
|
||||
User-agent: *
|
||||
Allow: /
|
||||
|
||||
Sitemap: https://docs.mcvsphere.dev/sitemap-index.xml
|
||||
22
docs/src/assets/logo.svg
Normal file
22
docs/src/assets/logo.svg
Normal file
@ -0,0 +1,22 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48" fill="none">
|
||||
<!-- vSphere-inspired cube -->
|
||||
<defs>
|
||||
<linearGradient id="grad1" x1="0%" y1="0%" x2="100%" y2="100%">
|
||||
<stop offset="0%" style="stop-color:#3d9cdb;stop-opacity:1" />
|
||||
<stop offset="100%" style="stop-color:#146eb4;stop-opacity:1" />
|
||||
</linearGradient>
|
||||
<linearGradient id="grad2" x1="0%" y1="100%" x2="100%" y2="0%">
|
||||
<stop offset="0%" style="stop-color:#0d4f8c;stop-opacity:1" />
|
||||
<stop offset="100%" style="stop-color:#146eb4;stop-opacity:1" />
|
||||
</linearGradient>
|
||||
</defs>
|
||||
<!-- Main cube shape -->
|
||||
<path d="M24 4L6 14v20l18 10 18-10V14L24 4z" fill="url(#grad1)" opacity="0.9"/>
|
||||
<path d="M24 4L6 14l18 10 18-10L24 4z" fill="url(#grad2)" opacity="0.8"/>
|
||||
<path d="M24 24v20l18-10V14L24 24z" fill="#0d4f8c" opacity="0.7"/>
|
||||
<path d="M24 24L6 14v20l18 10V24z" fill="#146eb4" opacity="0.6"/>
|
||||
<!-- VM representation lines -->
|
||||
<path d="M18 20l6-3.5 6 3.5" stroke="#fff" stroke-width="1.5" fill="none" opacity="0.8"/>
|
||||
<path d="M18 26l6-3.5 6 3.5" stroke="#fff" stroke-width="1.5" fill="none" opacity="0.6"/>
|
||||
<path d="M18 32l6-3.5 6 3.5" stroke="#fff" stroke-width="1.5" fill="none" opacity="0.4"/>
|
||||
</svg>
|
||||
|
After Width: | Height: | Size: 1.2 KiB |
6
docs/src/content.config.ts
Normal file
6
docs/src/content.config.ts
Normal file
@ -0,0 +1,6 @@
|
||||
import { defineCollection } from 'astro:content';
|
||||
import { docsSchema } from '@astrojs/starlight/schema';
|
||||
|
||||
export const collections = {
|
||||
docs: defineCollection({ schema: docsSchema() }),
|
||||
};
|
||||
99
docs/src/content/docs/configuration/environment.md
Normal file
99
docs/src/content/docs/configuration/environment.md
Normal file
@ -0,0 +1,99 @@
|
||||
---
|
||||
title: Environment Variables
|
||||
description: Complete reference for all mcvsphere configuration options
|
||||
---
|
||||
|
||||
import { Aside } from '@astrojs/starlight/components';
|
||||
|
||||
## vCenter Connection
|
||||
|
||||
These are required to connect to your VMware infrastructure.
|
||||
|
||||
| Variable | Description | Default |
|
||||
|----------|-------------|---------|
|
||||
| `VCENTER_HOST` | vCenter or ESXi hostname/IP | **required** |
|
||||
| `VCENTER_USER` | Username (e.g., `admin@vsphere.local`) | **required** |
|
||||
| `VCENTER_PASSWORD` | Password | **required** |
|
||||
| `VCENTER_INSECURE` | Skip SSL certificate verification | `false` |
|
||||
| `VCENTER_DATACENTER` | Target datacenter | auto-detect |
|
||||
| `VCENTER_CLUSTER` | Target cluster | auto-detect |
|
||||
| `VCENTER_DATASTORE` | Default datastore | auto-detect |
|
||||
| `VCENTER_NETWORK` | Default network | auto-detect |
|
||||
|
||||
<Aside type="caution">
|
||||
Only set `VCENTER_INSECURE=true` in development environments. Production deployments should use valid SSL certificates.
|
||||
</Aside>
|
||||
|
||||
## MCP Transport
|
||||
|
||||
Control how mcvsphere communicates with MCP clients.
|
||||
|
||||
| Variable | Description | Default |
|
||||
|----------|-------------|---------|
|
||||
| `MCP_TRANSPORT` | `stdio` or `streamable-http` | `stdio` |
|
||||
| `MCP_HOST` | HTTP bind address | `0.0.0.0` |
|
||||
| `MCP_PORT` | HTTP port | `8080` |
|
||||
|
||||
### Transport Modes
|
||||
|
||||
- **stdio**: Direct subprocess communication. Used for single-user local development.
|
||||
- **streamable-http**: HTTP server with streaming support. Required for OAuth multi-user deployments.
|
||||
|
||||
## OAuth Authentication
|
||||
|
||||
Required when `OAUTH_ENABLED=true` for multi-user deployments.
|
||||
|
||||
| Variable | Description |
|
||||
|----------|-------------|
|
||||
| `OAUTH_ENABLED` | Enable OAuth authentication |
|
||||
| `OAUTH_ISSUER_URL` | OIDC discovery URL |
|
||||
| `OAUTH_CLIENT_ID` | OAuth client ID |
|
||||
| `OAUTH_CLIENT_SECRET` | OAuth client secret |
|
||||
| `OAUTH_BASE_URL` | Public HTTPS URL for callbacks |
|
||||
|
||||
Example OIDC discovery URLs:
|
||||
- **Authentik**: `https://auth.example.com/application/o/mcvsphere/`
|
||||
- **Keycloak**: `https://keycloak.example.com/realms/myrealm`
|
||||
- **Auth0**: `https://myapp.auth0.com/`
|
||||
- **Okta**: `https://myorg.okta.com/oauth2/default`
|
||||
|
||||
## Logging
|
||||
|
||||
| Variable | Description | Default |
|
||||
|----------|-------------|---------|
|
||||
| `LOG_LEVEL` | Logging verbosity (`DEBUG`, `INFO`, `WARNING`, `ERROR`) | `INFO` |
|
||||
|
||||
## Example Configurations
|
||||
|
||||
### Local Development
|
||||
|
||||
```bash
|
||||
export VCENTER_HOST=10.20.0.222
|
||||
export VCENTER_USER=admin@vsphere.local
|
||||
export VCENTER_PASSWORD=secret
|
||||
export VCENTER_INSECURE=true
|
||||
export LOG_LEVEL=DEBUG
|
||||
```
|
||||
|
||||
### Production (Single User)
|
||||
|
||||
```bash
|
||||
export VCENTER_HOST=vcenter.prod.example.com
|
||||
export VCENTER_USER=svc-mcvsphere@vsphere.local
|
||||
export VCENTER_PASSWORD="${VCENTER_PASSWORD}" # from secrets manager
|
||||
export VCENTER_INSECURE=false
|
||||
```
|
||||
|
||||
### Production (Multi-User OAuth)
|
||||
|
||||
```bash
|
||||
export VCENTER_HOST=vcenter.prod.example.com
|
||||
export VCENTER_USER=svc-mcvsphere@vsphere.local
|
||||
export VCENTER_PASSWORD="${VCENTER_PASSWORD}"
|
||||
export MCP_TRANSPORT=streamable-http
|
||||
export OAUTH_ENABLED=true
|
||||
export OAUTH_ISSUER_URL=https://auth.example.com/application/o/mcvsphere/
|
||||
export OAUTH_CLIENT_ID=mcvsphere-client
|
||||
export OAUTH_CLIENT_SECRET="${OAUTH_CLIENT_SECRET}"
|
||||
export OAUTH_BASE_URL=https://mcp.example.com
|
||||
```
|
||||
126
docs/src/content/docs/configuration/vcenter.md
Normal file
126
docs/src/content/docs/configuration/vcenter.md
Normal file
@ -0,0 +1,126 @@
|
||||
---
|
||||
title: vCenter Connection
|
||||
description: Configuring vCenter/ESXi access for mcvsphere
|
||||
---
|
||||
|
||||
import { Aside, Steps } from '@astrojs/starlight/components';
|
||||
|
||||
## Service Account Setup
|
||||
|
||||
For production deployments, create a dedicated service account rather than using your personal administrator credentials.
|
||||
|
||||
<Steps>
|
||||
|
||||
1. **Create the user in vCenter**
|
||||
|
||||
In the vSphere Client, go to **Administration** → **Single Sign-On** → **Users and Groups** → **Add User**
|
||||
|
||||
- Username: `svc-mcvsphere`
|
||||
- Domain: `vsphere.local`
|
||||
- Password: Generate a strong password
|
||||
|
||||
2. **Create a role with required permissions**
|
||||
|
||||
Go to **Administration** → **Access Control** → **Roles** → **Add Role**
|
||||
|
||||
Required permissions vary by which tools you need:
|
||||
|
||||
| Permission Category | Required For |
|
||||
|---------------------|--------------|
|
||||
| Virtual machine → Interaction | Power operations, console |
|
||||
| Virtual machine → Inventory | Create, delete, rename VMs |
|
||||
| Virtual machine → Configuration | CPU, memory, disk changes |
|
||||
| Virtual machine → Snapshot management | Snapshots |
|
||||
| Virtual machine → Guest operations | Commands, file transfer |
|
||||
| Datastore → Browse datastore | OVF deploy, file operations |
|
||||
| Network → Assign network | Network adapter changes |
|
||||
| Host → Configuration | Host management tools |
|
||||
|
||||
3. **Assign the role**
|
||||
|
||||
Go to your datacenter or cluster, **Permissions** tab, **Add Permission**
|
||||
|
||||
- User: `svc-mcvsphere@vsphere.local`
|
||||
- Role: The role you created
|
||||
- Propagate to children: **Yes**
|
||||
|
||||
</Steps>
|
||||
|
||||
## Connection Testing
|
||||
|
||||
Test your credentials before configuring mcvsphere:
|
||||
|
||||
```bash
|
||||
# Set credentials
|
||||
export VCENTER_HOST=vcenter.example.com
|
||||
export VCENTER_USER=svc-mcvsphere@vsphere.local
|
||||
export VCENTER_PASSWORD=your-password
|
||||
|
||||
# Quick test with Python
|
||||
python -c "
|
||||
from pyVim.connect import SmartConnect
|
||||
import ssl
|
||||
ctx = ssl._create_unverified_context()
|
||||
si = SmartConnect(host='$VCENTER_HOST', user='$VCENTER_USER', pwd='$VCENTER_PASSWORD', sslContext=ctx)
|
||||
print(f'Connected to: {si.content.about.fullName}')
|
||||
"
|
||||
```
|
||||
|
||||
## SSL Certificates
|
||||
|
||||
### Self-Signed Certificates (Development)
|
||||
|
||||
```bash
|
||||
export VCENTER_INSECURE=true
|
||||
```
|
||||
|
||||
<Aside type="caution">
|
||||
This disables SSL verification. Only use in lab environments.
|
||||
</Aside>
|
||||
|
||||
### Custom CA Certificates (Production)
|
||||
|
||||
If your vCenter uses certificates signed by an internal CA:
|
||||
|
||||
```bash
|
||||
# Add your CA to the system trust store
|
||||
sudo cp your-ca.crt /usr/local/share/ca-certificates/
|
||||
sudo update-ca-certificates
|
||||
|
||||
# Or specify the CA bundle
|
||||
export REQUESTS_CA_BUNDLE=/path/to/ca-bundle.crt
|
||||
```
|
||||
|
||||
## Auto-Detection Behavior
|
||||
|
||||
When `VCENTER_DATACENTER`, `VCENTER_CLUSTER`, `VCENTER_DATASTORE`, or `VCENTER_NETWORK` are not set, mcvsphere auto-detects defaults:
|
||||
|
||||
1. **Datacenter**: First datacenter found
|
||||
2. **Cluster**: First cluster in the datacenter
|
||||
3. **Datastore**: Datastore with most free space
|
||||
4. **Network**: Network named "VM Network", or first network found
|
||||
|
||||
To see what was auto-detected, check the startup logs:
|
||||
|
||||
```bash
|
||||
LOG_LEVEL=DEBUG uvx mcvsphere
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "Cannot complete login due to an incorrect user name or password"
|
||||
|
||||
- Check username includes domain: `admin@vsphere.local` not `admin`
|
||||
- Verify password doesn't contain special characters that need escaping
|
||||
- Confirm the account isn't locked in vCenter
|
||||
|
||||
### "SSL: CERTIFICATE_VERIFY_FAILED"
|
||||
|
||||
- Use `VCENTER_INSECURE=true` for self-signed certs
|
||||
- Or install the vCenter CA certificate (see above)
|
||||
|
||||
### "Permission denied" for specific operations
|
||||
|
||||
- Check the service account has the required vCenter permissions
|
||||
- Permissions must be assigned at the right level (datacenter, cluster, or VM folder)
|
||||
- Ensure "Propagate to children" is enabled
|
||||
186
docs/src/content/docs/deployment/docker.md
Normal file
186
docs/src/content/docs/deployment/docker.md
Normal file
@ -0,0 +1,186 @@
|
||||
---
|
||||
title: Docker Deployment
|
||||
description: Run mcvsphere in Docker for production deployments
|
||||
---
|
||||
|
||||
import { Tabs, TabItem, Aside, Steps } from '@astrojs/starlight/components';
|
||||
|
||||
## Quick Start
|
||||
|
||||
<Steps>
|
||||
|
||||
1. **Create configuration**
|
||||
|
||||
```bash
|
||||
# Create environment file
|
||||
cat > .env << 'EOF'
|
||||
COMPOSE_PROJECT_NAME=mcvsphere
|
||||
|
||||
# vCenter Connection
|
||||
VCENTER_HOST=vcenter.example.com
|
||||
VCENTER_USER=svc-mcvsphere@vsphere.local
|
||||
VCENTER_PASSWORD=your-password
|
||||
VCENTER_INSECURE=false
|
||||
|
||||
# Transport
|
||||
MCP_TRANSPORT=streamable-http
|
||||
MCP_HOST=0.0.0.0
|
||||
MCP_PORT=8080
|
||||
EOF
|
||||
```
|
||||
|
||||
2. **Run the container**
|
||||
|
||||
```bash
|
||||
docker run -d \
|
||||
--name mcvsphere \
|
||||
--env-file .env \
|
||||
-p 8080:8080 \
|
||||
ghcr.io/supportedsystems/mcvsphere:latest
|
||||
```
|
||||
|
||||
3. **Verify it's running**
|
||||
|
||||
```bash
|
||||
curl http://localhost:8080/.well-known/oauth-authorization-server
|
||||
```
|
||||
|
||||
</Steps>
|
||||
|
||||
## Docker Compose
|
||||
|
||||
For production deployments, use Docker Compose:
|
||||
|
||||
```yaml
|
||||
# docker-compose.yml
|
||||
services:
|
||||
mcvsphere:
|
||||
image: ghcr.io/supportedsystems/mcvsphere:latest
|
||||
container_name: mcvsphere
|
||||
restart: unless-stopped
|
||||
env_file:
|
||||
- .env
|
||||
ports:
|
||||
- "8080:8080"
|
||||
volumes:
|
||||
- ./logs:/app/logs
|
||||
healthcheck:
|
||||
test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8080/.well-known/oauth-authorization-server')"]
|
||||
interval: 30s
|
||||
timeout: 10s
|
||||
retries: 3
|
||||
start_period: 15s
|
||||
deploy:
|
||||
resources:
|
||||
limits:
|
||||
memory: 512M
|
||||
cpus: '1.0'
|
||||
reservations:
|
||||
memory: 256M
|
||||
cpus: '0.25'
|
||||
```
|
||||
|
||||
```bash
|
||||
docker compose up -d
|
||||
docker compose logs -f
|
||||
```
|
||||
|
||||
## With Caddy Reverse Proxy
|
||||
|
||||
For HTTPS termination, use [caddy-docker-proxy](https://github.com/lucaslorentz/caddy-docker-proxy):
|
||||
|
||||
```yaml
|
||||
# docker-compose.yml
|
||||
services:
|
||||
mcvsphere:
|
||||
image: ghcr.io/supportedsystems/mcvsphere:latest
|
||||
restart: unless-stopped
|
||||
env_file:
|
||||
- .env
|
||||
networks:
|
||||
- caddy
|
||||
labels:
|
||||
caddy: mcp.example.com
|
||||
caddy.reverse_proxy: "{{upstreams 8080}}"
|
||||
# WebSocket/streaming support
|
||||
caddy.reverse_proxy.flush_interval: "-1"
|
||||
caddy.reverse_proxy.transport: http
|
||||
caddy.reverse_proxy.transport.read_timeout: "0"
|
||||
caddy.reverse_proxy.transport.write_timeout: "0"
|
||||
|
||||
networks:
|
||||
caddy:
|
||||
external: true
|
||||
```
|
||||
|
||||
<Aside type="tip">
|
||||
The `flush_interval` and timeout settings are important for MCP's streaming protocol. Without them, connections may drop unexpectedly.
|
||||
</Aside>
|
||||
|
||||
## Building from Source
|
||||
|
||||
```bash
|
||||
# Clone repository
|
||||
git clone https://git.supported.systems/MCP/mcvsphere.git
|
||||
cd mcvsphere
|
||||
|
||||
# Build image
|
||||
docker build -t mcvsphere:local .
|
||||
|
||||
# Run
|
||||
docker run -d --env-file .env mcvsphere:local
|
||||
```
|
||||
|
||||
### Multi-Stage Build
|
||||
|
||||
The Dockerfile uses a multi-stage build for minimal image size:
|
||||
|
||||
1. **Builder stage**: Installs dependencies with `uv`
|
||||
2. **Production stage**: Copies only the virtual environment, runs as non-root user
|
||||
|
||||
## Health Checks
|
||||
|
||||
The container includes automatic health checks that verify the MCP endpoint is responding:
|
||||
|
||||
```bash
|
||||
# Check container health
|
||||
docker inspect --format='{{.State.Health.Status}}' mcvsphere
|
||||
|
||||
# View health check logs
|
||||
docker inspect --format='{{range .State.Health.Log}}{{.Output}}{{end}}' mcvsphere
|
||||
```
|
||||
|
||||
## Logging
|
||||
|
||||
Logs are written to `/app/logs` inside the container. Mount a volume to persist them:
|
||||
|
||||
```yaml
|
||||
volumes:
|
||||
- ./logs:/app/logs
|
||||
```
|
||||
|
||||
View logs:
|
||||
|
||||
```bash
|
||||
# Docker logs
|
||||
docker logs mcvsphere
|
||||
|
||||
# Application logs (if volume mounted)
|
||||
tail -f ./logs/mcvsphere.log
|
||||
```
|
||||
|
||||
## Resource Limits
|
||||
|
||||
Recommended resource limits:
|
||||
|
||||
| Setting | Development | Production |
|
||||
|---------|-------------|------------|
|
||||
| Memory limit | 256M | 512M |
|
||||
| Memory reservation | 128M | 256M |
|
||||
| CPU limit | 0.5 | 1.0 |
|
||||
| CPU reservation | 0.1 | 0.25 |
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [OAuth Multi-User Mode](/deployment/oauth/) — Enable authentication for shared deployments
|
||||
- [RBAC Permissions](/reference/rbac/) — Understand permission levels
|
||||
259
docs/src/content/docs/deployment/oauth.md
Normal file
259
docs/src/content/docs/deployment/oauth.md
Normal file
@ -0,0 +1,259 @@
|
||||
---
|
||||
title: OAuth Multi-User Mode
|
||||
description: Enable browser-based authentication with any OIDC provider
|
||||
---
|
||||
|
||||
import { Tabs, TabItem, Aside, Steps, Badge } from '@astrojs/starlight/components';
|
||||
|
||||
For shared infrastructure or production deployments, mcvsphere supports OAuth 2.1 with any OIDC-compliant provider. This enables:
|
||||
|
||||
- **Browser-based authentication** via Authentik, Keycloak, Auth0, Okta, etc.
|
||||
- **Group-based RBAC** with 5 permission levels
|
||||
- **Audit logging** with user identity
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ MCP Client (Claude Code) │
|
||||
└─────────────────────────────┬───────────────────────────────┘
|
||||
│ 1. OAuth 2.1 + PKCE flow
|
||||
│ (browser opens for login)
|
||||
┌─────────────────────────────▼───────────────────────────────┐
|
||||
│ OIDC Provider │
|
||||
│ (Authentik, Keycloak, Auth0, etc.) │
|
||||
│ - Issues JWT access tokens │
|
||||
│ - Validates user credentials │
|
||||
│ - Includes groups claim in token │
|
||||
└─────────────────────────────┬───────────────────────────────┘
|
||||
│ 2. JWT Bearer token
|
||||
┌─────────────────────────────▼───────────────────────────────┐
|
||||
│ mcvsphere │
|
||||
│ ┌────────────────────────────────────────────────────┐ │
|
||||
│ │ OIDCProxy: Validates JWT via JWKS, extracts claims │ │
|
||||
│ └────────────────────────────────────────────────────┘ │
|
||||
│ ┌────────────────────────────────────────────────────┐ │
|
||||
│ │ RBACMiddleware: Maps groups → permissions │ │
|
||||
│ └────────────────────────────────────────────────────┘ │
|
||||
│ ┌────────────────────────────────────────────────────┐ │
|
||||
│ │ VMware Tools: Execute vCenter operations │ │
|
||||
│ └────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────┬───────────────────────────────┘
|
||||
│ 3. pyvmomi (service account)
|
||||
┌─────────────────────────────▼───────────────────────────────┐
|
||||
│ vCenter / ESXi │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Quick Start
|
||||
|
||||
<Tabs>
|
||||
<TabItem label="Existing OIDC Provider">
|
||||
If you already have Authentik, Keycloak, Auth0, or another OIDC provider:
|
||||
|
||||
<Steps>
|
||||
|
||||
1. **Create OAuth application in your provider**
|
||||
|
||||
- Client type: Confidential
|
||||
- Redirect URI: `https://mcp.example.com/auth/callback`
|
||||
- Scopes: `openid`, `profile`, `email`, `groups`
|
||||
|
||||
2. **Configure environment**
|
||||
|
||||
```bash
|
||||
cat > .env << 'EOF'
|
||||
# vCenter
|
||||
VCENTER_HOST=vcenter.example.com
|
||||
VCENTER_USER=svc-mcvsphere@vsphere.local
|
||||
VCENTER_PASSWORD=your-password
|
||||
|
||||
# Transport (required for OAuth)
|
||||
MCP_TRANSPORT=streamable-http
|
||||
MCP_DOMAIN=mcp.example.com
|
||||
|
||||
# OAuth
|
||||
OAUTH_ENABLED=true
|
||||
OAUTH_ISSUER_URL=https://auth.example.com/application/o/mcvsphere/
|
||||
OAUTH_CLIENT_ID=your-client-id
|
||||
OAUTH_CLIENT_SECRET=your-client-secret
|
||||
OAUTH_BASE_URL=https://mcp.example.com
|
||||
EOF
|
||||
```
|
||||
|
||||
3. **Deploy with Docker**
|
||||
|
||||
```bash
|
||||
docker compose -f docker-compose.oauth-standalone.yml up -d
|
||||
```
|
||||
|
||||
4. **Add to Claude Code**
|
||||
|
||||
```bash
|
||||
claude mcp add -t http vsphere https://mcp.example.com/mcp
|
||||
```
|
||||
|
||||
</Steps>
|
||||
</TabItem>
|
||||
<TabItem label="New Authentik Setup">
|
||||
To deploy mcvsphere with a fresh Authentik identity provider:
|
||||
|
||||
<Steps>
|
||||
|
||||
1. **Generate secrets**
|
||||
|
||||
```bash
|
||||
./scripts/setup-oauth.sh
|
||||
```
|
||||
|
||||
2. **Start full stack**
|
||||
|
||||
```bash
|
||||
docker compose -f docker-compose.oauth.yml up -d
|
||||
```
|
||||
|
||||
This starts:
|
||||
- mcvsphere (MCP server)
|
||||
- Authentik (identity provider)
|
||||
- PostgreSQL (Authentik database)
|
||||
- Redis (Authentik cache)
|
||||
|
||||
3. **Configure Authentik**
|
||||
|
||||
Open `https://auth.yourdomain.com` and:
|
||||
- Create OAuth2 provider for mcvsphere
|
||||
- Create `vsphere-*` groups
|
||||
- Assign users to groups
|
||||
|
||||
</Steps>
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## RBAC Permission Groups
|
||||
|
||||
Create these groups in your OIDC provider and assign users:
|
||||
|
||||
| Group | Access Level |
|
||||
|-------|--------------|
|
||||
| `vsphere-super-admins` | Full control (all 94 tools) |
|
||||
| `vsphere-host-admins` | Host operations + VM management |
|
||||
| `vsphere-admins` | VM lifecycle management |
|
||||
| `vsphere-operators` | Power ops + snapshots |
|
||||
| `vsphere-readers` | Read-only |
|
||||
|
||||
<Aside type="caution">
|
||||
**Default Deny**: Users without any `vsphere-*` group are denied all access. This is a security feature, not a bug.
|
||||
</Aside>
|
||||
|
||||
See [RBAC Permissions Reference](/reference/rbac/) for complete tool-to-permission mappings.
|
||||
|
||||
## Authentik Configuration
|
||||
|
||||
<Steps>
|
||||
|
||||
1. **Create OAuth2/OIDC Provider**
|
||||
|
||||
In Authentik, go to **Applications** → **Providers** → **Create**
|
||||
|
||||
- Name: `mcvsphere`
|
||||
- Authorization flow: `default-authorization-flow`
|
||||
- Client type: **Confidential**
|
||||
- Client ID: (auto-generated, copy this)
|
||||
- Client Secret: (auto-generated, copy this)
|
||||
- Redirect URIs:
|
||||
```
|
||||
http://localhost:*/callback
|
||||
https://mcp.example.com/auth/callback
|
||||
```
|
||||
- Signing Key: Select your RS256 certificate
|
||||
|
||||
2. **Create Application**
|
||||
|
||||
Go to **Applications** → **Applications** → **Create**
|
||||
|
||||
- Name: `mcvsphere`
|
||||
- Slug: `mcvsphere`
|
||||
- Provider: Select the provider from step 1
|
||||
|
||||
3. **Create Groups**
|
||||
|
||||
Go to **Directory** → **Groups** → **Create** for each:
|
||||
|
||||
- `vsphere-readers`
|
||||
- `vsphere-operators`
|
||||
- `vsphere-admins`
|
||||
- `vsphere-host-admins`
|
||||
- `vsphere-super-admins`
|
||||
|
||||
4. **Assign Users to Groups**
|
||||
|
||||
Edit each user and add them to appropriate groups.
|
||||
|
||||
</Steps>
|
||||
|
||||
## OAuth Flow
|
||||
|
||||
When a user connects with Claude Code:
|
||||
|
||||
1. **Initial connection** — Client connects without auth, server returns 401 with OAuth metadata URL
|
||||
2. **Discovery** — Client fetches OIDC configuration from provider
|
||||
3. **Authorization** — Browser opens, user logs in via OIDC provider
|
||||
4. **Token exchange** — Authorization code exchanged for JWT access token
|
||||
5. **Authenticated requests** — Client includes `Authorization: Bearer <jwt>` header
|
||||
6. **Permission check** — RBACMiddleware validates user's groups against required tool permissions
|
||||
7. **Audit logging** — Every operation logged with user identity and timing
|
||||
|
||||
## Audit Logging
|
||||
|
||||
All tool invocations are logged with user context:
|
||||
|
||||
```json
|
||||
{
|
||||
"timestamp": "2025-01-16T08:15:32.123456+00:00",
|
||||
"user": "ryan@example.com",
|
||||
"groups": ["vsphere-admins", "vsphere-operators"],
|
||||
"tool": "power_on",
|
||||
"args": {"vm_name": "web-server"},
|
||||
"duration_ms": 1234.56,
|
||||
"result": "success"
|
||||
}
|
||||
```
|
||||
|
||||
Permission denied events:
|
||||
|
||||
```json
|
||||
{
|
||||
"timestamp": "2025-01-16T08:15:32.123456+00:00",
|
||||
"user": "guest@example.com",
|
||||
"groups": ["vsphere-readers"],
|
||||
"tool": "delete_vm",
|
||||
"required_permission": "vm_lifecycle",
|
||||
"event": "PERMISSION_DENIED"
|
||||
}
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "401 Unauthorized" on all requests
|
||||
|
||||
- Check `OAUTH_ISSUER_URL` points to valid OIDC discovery endpoint
|
||||
- Verify client ID and secret match provider configuration
|
||||
- Ensure token hasn't expired
|
||||
|
||||
### "Permission denied" errors
|
||||
|
||||
- Check user's group memberships in OIDC provider
|
||||
- Verify groups claim is included in JWT (decode at [jwt.io](https://jwt.io))
|
||||
- Confirm group names match exactly: `vsphere-admins` not `vsphere_admins`
|
||||
|
||||
### Token validation fails
|
||||
|
||||
- Ensure OIDC provider issues JWTs (not opaque tokens)
|
||||
- Check signing key is configured in provider
|
||||
- Verify `OAUTH_BASE_URL` matches redirect URI in provider
|
||||
|
||||
### User shows as "anonymous"
|
||||
|
||||
- Restart Claude Code session after OAuth flow completes
|
||||
- Check server logs for claims extraction errors
|
||||
- Verify `groups` scope is included in token request
|
||||
71
docs/src/content/docs/getting-started/installation.md
Normal file
71
docs/src/content/docs/getting-started/installation.md
Normal file
@ -0,0 +1,71 @@
|
||||
---
|
||||
title: Installation
|
||||
description: Install mcvsphere in under 30 seconds
|
||||
---
|
||||
|
||||
import { Tabs, TabItem } from '@astrojs/starlight/components';
|
||||
|
||||
## Quick Install
|
||||
|
||||
<Tabs>
|
||||
<TabItem label="uvx (Recommended)">
|
||||
```bash
|
||||
uvx mcvsphere
|
||||
```
|
||||
|
||||
No installation needed. uvx downloads and runs in one command.
|
||||
</TabItem>
|
||||
<TabItem label="pip">
|
||||
```bash
|
||||
pip install mcvsphere
|
||||
```
|
||||
|
||||
Then run with:
|
||||
```bash
|
||||
mcvsphere
|
||||
```
|
||||
</TabItem>
|
||||
<TabItem label="pipx">
|
||||
```bash
|
||||
pipx install mcvsphere
|
||||
```
|
||||
|
||||
Isolated environment, available system-wide.
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## Requirements
|
||||
|
||||
| Requirement | Version |
|
||||
|------------|---------|
|
||||
| Python | 3.11+ |
|
||||
| VMware vSphere | 7.0+ |
|
||||
| VMware Tools | Latest (for guest operations) |
|
||||
|
||||
## Verify Installation
|
||||
|
||||
```bash
|
||||
# Check version
|
||||
uvx mcvsphere --version
|
||||
|
||||
# Or if installed via pip
|
||||
mcvsphere --version
|
||||
```
|
||||
|
||||
You should see something like:
|
||||
|
||||
```
|
||||
mcvsphere v0.2.3
|
||||
```
|
||||
|
||||
## Dependencies
|
||||
|
||||
mcvsphere installs these automatically:
|
||||
|
||||
- **[FastMCP](https://gofastmcp.com)** — MCP server framework
|
||||
- **[pyvmomi](https://github.com/vmware/pyvmomi)** — VMware vSphere Python SDK
|
||||
- **[pydantic](https://docs.pydantic.dev)** — Configuration validation
|
||||
|
||||
## Next Steps
|
||||
|
||||
Now that mcvsphere is installed, [configure your vCenter connection](/getting-started/quickstart/).
|
||||
71
docs/src/content/docs/getting-started/introduction.md
Normal file
71
docs/src/content/docs/getting-started/introduction.md
Normal file
@ -0,0 +1,71 @@
|
||||
---
|
||||
title: Introduction
|
||||
description: What is mcvsphere and why you'd want it
|
||||
---
|
||||
|
||||
mcvsphere is a Model Context Protocol (MCP) server that connects AI assistants like Claude to your VMware vSphere infrastructure. Instead of clicking through the vSphere UI or writing scripts, you can manage your virtual machines through natural language conversation.
|
||||
|
||||
## How It Works
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Claude Code / MCP Client │
|
||||
└──────────────────────┬──────────────────────────────────────┘
|
||||
│ MCP Protocol (stdio or HTTP)
|
||||
│
|
||||
┌──────────────────────▼──────────────────────────────────────┐
|
||||
│ mcvsphere │
|
||||
│ FastMCP + pyvmomi │
|
||||
│ │
|
||||
│ 94 Tools 6 Resources │
|
||||
│ • VM lifecycle • VMs list │
|
||||
│ • Power operations • Hosts list │
|
||||
│ • Snapshots • Datastores │
|
||||
│ • Guest operations • Networks │
|
||||
│ • Disk/NIC management • Clusters │
|
||||
│ • Host management • Resource pools │
|
||||
└──────────────────────┬──────────────────────────────────────┘
|
||||
│ pyvmomi (vSphere API)
|
||||
│
|
||||
┌──────────────────────▼──────────────────────────────────────┐
|
||||
│ VMware vCenter / ESXi Host │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Two Operating Modes
|
||||
|
||||
### STDIO Mode (Single User)
|
||||
|
||||
Direct connection for local development or single-user setups. Claude Code spawns the MCP server as a subprocess.
|
||||
|
||||
```bash
|
||||
claude mcp add vsphere "uvx mcvsphere"
|
||||
```
|
||||
|
||||
### HTTP + OAuth Mode (Multi-User)
|
||||
|
||||
Browser-based authentication via any OIDC provider. Multiple users share one server, each with their own permissions based on group membership.
|
||||
|
||||
```bash
|
||||
claude mcp add -t http vsphere https://mcp.example.com/mcp
|
||||
```
|
||||
|
||||
## What Can You Do?
|
||||
|
||||
With mcvsphere connected, you can ask Claude to:
|
||||
|
||||
- **Create infrastructure**: "Spin up 3 Ubuntu VMs with 4 CPUs each"
|
||||
- **Manage power**: "Power on all VMs starting with 'prod-'"
|
||||
- **Take snapshots**: "Snapshot all production VMs before the update"
|
||||
- **Run commands**: "Check the disk usage on linux-server" (no SSH needed)
|
||||
- **Configure hardware**: "Add a 100GB disk to the database server"
|
||||
- **Deploy appliances**: "Deploy this OVA to the dev cluster"
|
||||
- **Monitor systems**: "Show me which hosts have high memory usage"
|
||||
|
||||
All 94 tools work through conversation. No scripting required.
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [Install mcvsphere](/getting-started/installation/)
|
||||
- [Configure vCenter connection](/getting-started/quickstart/)
|
||||
- [Learn about all 94 tools](/reference/tools/)
|
||||
102
docs/src/content/docs/getting-started/quickstart.md
Normal file
102
docs/src/content/docs/getting-started/quickstart.md
Normal file
@ -0,0 +1,102 @@
|
||||
---
|
||||
title: Quick Start
|
||||
description: Connect mcvsphere to vCenter and Claude Code in 2 minutes
|
||||
---
|
||||
|
||||
import { Steps, Aside } from '@astrojs/starlight/components';
|
||||
|
||||
## Single-User Setup (STDIO)
|
||||
|
||||
<Steps>
|
||||
|
||||
1. **Set your vCenter credentials**
|
||||
|
||||
```bash
|
||||
export VCENTER_HOST=vcenter.example.com
|
||||
export VCENTER_USER=administrator@vsphere.local
|
||||
export VCENTER_PASSWORD=your-password
|
||||
```
|
||||
|
||||
<Aside type="tip">
|
||||
For self-signed certificates in dev/lab environments:
|
||||
```bash
|
||||
export VCENTER_INSECURE=true
|
||||
```
|
||||
</Aside>
|
||||
|
||||
2. **Add to Claude Code**
|
||||
|
||||
```bash
|
||||
claude mcp add vsphere "uvx mcvsphere"
|
||||
```
|
||||
|
||||
3. **Test the connection**
|
||||
|
||||
Open Claude Code and ask:
|
||||
```
|
||||
List all VMs in my vCenter
|
||||
```
|
||||
|
||||
Claude should respond with your VM inventory.
|
||||
|
||||
</Steps>
|
||||
|
||||
## Multi-User Setup (HTTP + OAuth)
|
||||
|
||||
For shared infrastructure with multiple users, see [OAuth Multi-User Deployment](/deployment/oauth/).
|
||||
|
||||
## Example Conversations
|
||||
|
||||
Once connected, try these:
|
||||
|
||||
### Create a VM
|
||||
|
||||
```
|
||||
Create a VM called "test-web" with 4 CPUs, 8GB RAM, and 100GB disk
|
||||
```
|
||||
|
||||
### Manage Snapshots
|
||||
|
||||
```
|
||||
Take a snapshot of production-db called "before-upgrade"
|
||||
```
|
||||
|
||||
### Run Commands in Guests
|
||||
|
||||
```
|
||||
What's the uptime on linux-server?
|
||||
```
|
||||
|
||||
mcvsphere runs `uptime` inside the VM via VMware Tools—no SSH required.
|
||||
|
||||
### Take Console Screenshots
|
||||
|
||||
```
|
||||
Show me what's on the screen of that stuck VM
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "Failed to connect to vCenter"
|
||||
|
||||
- Verify `VCENTER_HOST` is reachable: `nc -zv $VCENTER_HOST 443`
|
||||
- Check username format: `admin@vsphere.local` not just `admin`
|
||||
- Try `VCENTER_INSECURE=true` for certificate issues
|
||||
|
||||
### "VMware Tools not running"
|
||||
|
||||
Guest operations require VMware Tools installed and running in the VM:
|
||||
|
||||
```
|
||||
Check VMware Tools status on linux-server
|
||||
```
|
||||
|
||||
### "Permission denied"
|
||||
|
||||
Your vCenter user needs appropriate permissions. For testing, use an administrator account. For production, create a dedicated service account with minimal required permissions.
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [Environment Variables Reference](/configuration/environment/)
|
||||
- [Docker Deployment](/deployment/docker/)
|
||||
- [All 94 Tools](/reference/tools/)
|
||||
81
docs/src/content/docs/index.mdx
Normal file
81
docs/src/content/docs/index.mdx
Normal file
@ -0,0 +1,81 @@
|
||||
---
|
||||
title: mcvsphere
|
||||
description: 94 tools. Full VMware control. Natural language.
|
||||
template: splash
|
||||
hero:
|
||||
tagline: Stop clicking through vSphere. Start talking to it.
|
||||
image:
|
||||
file: ../../assets/logo.svg
|
||||
actions:
|
||||
- text: Get Started
|
||||
link: /getting-started/installation/
|
||||
icon: right-arrow
|
||||
- text: View on GitHub
|
||||
link: https://git.supported.systems/MCP/mcvsphere
|
||||
icon: external
|
||||
variant: minimal
|
||||
---
|
||||
|
||||
import { Card, CardGrid } from '@astrojs/starlight/components';
|
||||
|
||||
## What is mcvsphere?
|
||||
|
||||
mcvsphere is an MCP server that gives AI assistants like Claude complete control over your VMware infrastructure. Create VMs, manage snapshots, run commands inside guests, take console screenshots, configure network appliances—all through conversation.
|
||||
|
||||
**94 MCP tools.** Not a toy demo. Not "just the basics." The whole thing.
|
||||
|
||||
```
|
||||
You: "Spin up a new VM with 4 CPUs and 16GB RAM, clone it twice,
|
||||
then snapshot all three before I start testing"
|
||||
|
||||
Claude: Done. Three VMs running, all snapshotted. What's next?
|
||||
```
|
||||
|
||||
## Key Features
|
||||
|
||||
<CardGrid stagger>
|
||||
<Card title="94 MCP Tools" icon="rocket">
|
||||
VM lifecycle, power operations, snapshots, guest operations, serial console, disk management, network adapters, OVF/OVA, host management, and more.
|
||||
</Card>
|
||||
<Card title="Guest Operations" icon="seti:shell">
|
||||
Run commands inside VMs, transfer files, browse filesystems—no SSH required. VMware Tools does the heavy lifting.
|
||||
</Card>
|
||||
<Card title="OAuth + RBAC" icon="shield">
|
||||
Multi-user authentication via any OIDC provider with 5 permission levels. Audit logging shows WHO did WHAT.
|
||||
</Card>
|
||||
<Card title="Real-time Resources" icon="list-format">
|
||||
6 MCP resources provide always-current data: VMs, hosts, datastores, networks, clusters, resource pools.
|
||||
</Card>
|
||||
</CardGrid>
|
||||
|
||||
## Quick Example
|
||||
|
||||
```bash
|
||||
# Install
|
||||
uvx mcvsphere
|
||||
|
||||
# Configure
|
||||
export VCENTER_HOST=vcenter.example.com
|
||||
export VCENTER_USER=administrator@vsphere.local
|
||||
export VCENTER_PASSWORD=your-password
|
||||
|
||||
# Add to Claude Code
|
||||
claude mcp add vsphere "uvx mcvsphere"
|
||||
```
|
||||
|
||||
That's it. You're managing vSphere with AI now.
|
||||
|
||||
## Requirements
|
||||
|
||||
- Python 3.11+
|
||||
- VMware vSphere 7.0+ (ESXi or vCenter)
|
||||
- VMware Tools (for guest operations)
|
||||
|
||||
## Built With
|
||||
|
||||
- [FastMCP](https://github.com/jlowin/fastmcp) — MCP server framework
|
||||
- [pyVmomi](https://github.com/vmware/pyvmomi) — VMware vSphere API
|
||||
|
||||
---
|
||||
|
||||
**94 tools. Your entire VMware infrastructure. Controlled by conversation.**
|
||||
239
docs/src/content/docs/reference/architecture.md
Normal file
239
docs/src/content/docs/reference/architecture.md
Normal file
@ -0,0 +1,239 @@
|
||||
---
|
||||
title: Architecture
|
||||
description: Technical overview of mcvsphere internals
|
||||
---
|
||||
|
||||
import { Aside } from '@astrojs/starlight/components';
|
||||
|
||||
## System Architecture
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ MCP Client (Claude Code) │
|
||||
└──────────────────────────┬──────────────────────────────────┘
|
||||
│
|
||||
│ MCP Protocol
|
||||
│ (stdio or streamable-http)
|
||||
│
|
||||
┌──────────────────────────▼──────────────────────────────────┐
|
||||
│ mcvsphere │
|
||||
│ │
|
||||
│ ┌───────────────────────────────────────────────────────┐ │
|
||||
│ │ FastMCP │ │
|
||||
│ │ - Protocol handling (JSON-RPC 2.0) │ │
|
||||
│ │ - Tool registration and dispatch │ │
|
||||
│ │ - Resource serving │ │
|
||||
│ │ - OAuth integration (OIDCProxy) │ │
|
||||
│ └───────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ┌───────────────────────────────────────────────────────┐ │
|
||||
│ │ RBACMiddleware │ │
|
||||
│ │ - Intercepts all tool calls │ │
|
||||
│ │ - Extracts user from OAuth token │ │
|
||||
│ │ - Enforces permission checks │ │
|
||||
│ │ - Audit logging │ │
|
||||
│ └───────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ┌───────────────────────────────────────────────────────┐ │
|
||||
│ │ Tool Implementations │ │
|
||||
│ │ - vm_lifecycle.py (7 tools) │ │
|
||||
│ │ - power_ops.py (6 tools) │ │
|
||||
│ │ - snapshots.py (5 tools) │ │
|
||||
│ │ - guest_ops.py (7 tools) │ │
|
||||
│ │ - ... (94 tools total) │ │
|
||||
│ └───────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ┌───────────────────────────────────────────────────────┐ │
|
||||
│ │ Connection Manager │ │
|
||||
│ │ - pyvmomi ServiceInstance │ │
|
||||
│ │ - Connection pooling │ │
|
||||
│ │ - Reconnection handling │ │
|
||||
│ └───────────────────────────────────────────────────────┘ │
|
||||
└──────────────────────────┬──────────────────────────────────┘
|
||||
│
|
||||
│ vSphere API (SOAP/REST)
|
||||
│
|
||||
┌──────────────────────────▼──────────────────────────────────┐
|
||||
│ VMware vCenter / ESXi │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Source Layout
|
||||
|
||||
```
|
||||
src/mcvsphere/
|
||||
├── __init__.py # Package entry point, version
|
||||
├── server.py # FastMCP server setup
|
||||
├── config.py # Pydantic Settings configuration
|
||||
├── connection.py # vSphere connection manager
|
||||
├── auth.py # OIDCProxy configuration
|
||||
├── middleware.py # RBAC middleware
|
||||
├── permissions.py # Permission levels and mappings
|
||||
├── audit.py # Audit logging
|
||||
└── tools/ # MCP tool implementations
|
||||
├── __init__.py
|
||||
├── vm_lifecycle.py
|
||||
├── power_ops.py
|
||||
├── snapshots.py
|
||||
├── guest_ops.py
|
||||
├── serial_console.py
|
||||
├── disk_mgmt.py
|
||||
├── nic_mgmt.py
|
||||
├── ovf_ops.py
|
||||
├── host_mgmt.py
|
||||
├── datastore_ops.py
|
||||
└── vcenter_ops.py
|
||||
```
|
||||
|
||||
## Key Components
|
||||
|
||||
### FastMCP Server (`server.py`)
|
||||
|
||||
The core MCP server built on [FastMCP](https://gofastmcp.com):
|
||||
|
||||
```python
|
||||
from fastmcp import FastMCP
|
||||
|
||||
mcp = FastMCP(
|
||||
name="mcvsphere",
|
||||
instructions="VMware vSphere management server..."
|
||||
)
|
||||
|
||||
# Tools are registered via decorators
|
||||
@mcp.tool()
|
||||
def list_vms() -> list[dict]:
|
||||
"""List all virtual machines."""
|
||||
return connection.list_vms()
|
||||
```
|
||||
|
||||
### Configuration (`config.py`)
|
||||
|
||||
Pydantic Settings model for type-safe configuration:
|
||||
|
||||
```python
|
||||
from pydantic_settings import BaseSettings
|
||||
|
||||
class Settings(BaseSettings):
|
||||
vcenter_host: str
|
||||
vcenter_user: str
|
||||
vcenter_password: str
|
||||
vcenter_insecure: bool = False
|
||||
mcp_transport: Literal["stdio", "streamable-http"] = "stdio"
|
||||
oauth_enabled: bool = False
|
||||
# ...
|
||||
```
|
||||
|
||||
### Connection Manager (`connection.py`)
|
||||
|
||||
Manages the pyvmomi ServiceInstance connection:
|
||||
|
||||
```python
|
||||
class VSphereConnection:
|
||||
def __init__(self, settings: Settings):
|
||||
self.si = SmartConnect(
|
||||
host=settings.vcenter_host,
|
||||
user=settings.vcenter_user,
|
||||
pwd=settings.vcenter_password,
|
||||
sslContext=self._get_ssl_context()
|
||||
)
|
||||
|
||||
def list_vms(self) -> list[dict]:
|
||||
content = self.si.RetrieveContent()
|
||||
# ... pyvmomi operations
|
||||
```
|
||||
|
||||
### RBAC Middleware (`middleware.py`)
|
||||
|
||||
Intercepts all tool calls for permission checking:
|
||||
|
||||
```python
|
||||
from fastmcp import Middleware
|
||||
|
||||
class RBACMiddleware(Middleware):
|
||||
async def on_call_tool(self, context, call_next):
|
||||
# 1. Extract user from OAuth token
|
||||
claims = self._extract_user_from_context(context.fastmcp_context)
|
||||
groups = claims.get("groups", [])
|
||||
|
||||
# 2. Check permission
|
||||
tool_name = context.message.name
|
||||
if not check_permission(tool_name, groups):
|
||||
raise PermissionDeniedError(...)
|
||||
|
||||
# 3. Execute with audit logging
|
||||
result = await call_next(context)
|
||||
audit_log(tool_name, claims, result)
|
||||
return result
|
||||
```
|
||||
|
||||
### OAuth Configuration (`auth.py`)
|
||||
|
||||
Configures FastMCP's OIDCProxy for token validation:
|
||||
|
||||
```python
|
||||
from fastmcp.server.auth import OIDCProxy
|
||||
|
||||
def create_auth_provider(settings: Settings) -> OIDCProxy | None:
|
||||
if not settings.oauth_enabled:
|
||||
return None
|
||||
|
||||
return OIDCProxy(
|
||||
issuer_url=settings.oauth_issuer_url,
|
||||
client_id=settings.oauth_client_id,
|
||||
client_secret=settings.oauth_client_secret,
|
||||
redirect_uri=f"{settings.oauth_base_url}/auth/callback",
|
||||
required_scopes=[], # Authentik uses opaque tokens
|
||||
)
|
||||
```
|
||||
|
||||
## Data Flow
|
||||
|
||||
### Tool Invocation (STDIO mode)
|
||||
|
||||
1. Claude Code sends JSON-RPC request via stdin
|
||||
2. FastMCP parses and validates request
|
||||
3. Tool function executes
|
||||
4. pyvmomi calls vSphere API
|
||||
5. Result serialized and returned via stdout
|
||||
|
||||
### Tool Invocation (HTTP + OAuth mode)
|
||||
|
||||
1. Client sends HTTP POST with Bearer token
|
||||
2. OIDCProxy validates JWT via JWKS
|
||||
3. RBACMiddleware extracts claims, checks permissions
|
||||
4. Tool function executes
|
||||
5. Audit log written
|
||||
6. Result returned as HTTP response
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
### Connection Reuse
|
||||
|
||||
A single pyvmomi connection is shared across all requests. This avoids the overhead of establishing new connections for each tool call.
|
||||
|
||||
### Lazy Loading
|
||||
|
||||
vCenter inventory is fetched on-demand rather than cached. This ensures data freshness but means each tool call queries vCenter directly.
|
||||
|
||||
### Resource Pooling
|
||||
|
||||
For high-volume deployments, consider running multiple mcvsphere instances behind a load balancer. Each instance maintains its own vCenter connection.
|
||||
|
||||
## Security Model
|
||||
|
||||
### STDIO Mode
|
||||
|
||||
- No authentication (trusts the parent process)
|
||||
- Single-user by design
|
||||
- Credentials passed via environment variables
|
||||
|
||||
### HTTP + OAuth Mode
|
||||
|
||||
- JWT validation via OIDC provider
|
||||
- Group-based RBAC
|
||||
- Audit trail with user identity
|
||||
- Service account connection to vCenter (user identity tracked in audit logs, not vCenter permissions)
|
||||
|
||||
<Aside>
|
||||
In OAuth mode, ALL users share the same vCenter service account. User identity is tracked in mcvsphere audit logs, not vCenter audit logs. Future versions may support per-user vCenter credentials via Vault integration.
|
||||
</Aside>
|
||||
184
docs/src/content/docs/reference/rbac.md
Normal file
184
docs/src/content/docs/reference/rbac.md
Normal file
@ -0,0 +1,184 @@
|
||||
---
|
||||
title: RBAC Permissions
|
||||
description: Role-based access control for multi-user deployments
|
||||
---
|
||||
|
||||
import { Aside } from '@astrojs/starlight/components';
|
||||
|
||||
When OAuth is enabled, mcvsphere enforces role-based access control (RBAC) based on the user's OAuth group memberships.
|
||||
|
||||
## Permission Levels
|
||||
|
||||
mcvsphere defines 5 permission levels, from least to most privileged:
|
||||
|
||||
| Level | Description | Tools |
|
||||
|-------|-------------|-------|
|
||||
| `READ_ONLY` | View-only operations | 32 tools |
|
||||
| `POWER_OPS` | Power and snapshot operations | 14 tools |
|
||||
| `VM_LIFECYCLE` | Create/delete/modify VMs | 33 tools |
|
||||
| `HOST_ADMIN` | ESXi host operations | 6 tools |
|
||||
| `FULL_ADMIN` | Everything including guest OS | 11 tools |
|
||||
|
||||
## OAuth Groups
|
||||
|
||||
Map OAuth groups to permission levels:
|
||||
|
||||
| OAuth Group | Permissions Granted |
|
||||
|-------------|---------------------|
|
||||
| `vsphere-readers` | READ_ONLY |
|
||||
| `vsphere-operators` | READ_ONLY + POWER_OPS |
|
||||
| `vsphere-admins` | READ_ONLY + POWER_OPS + VM_LIFECYCLE |
|
||||
| `vsphere-host-admins` | READ_ONLY + POWER_OPS + VM_LIFECYCLE + HOST_ADMIN |
|
||||
| `vsphere-super-admins` | ALL (full access) |
|
||||
|
||||
<Aside type="caution">
|
||||
**Default Deny Security**: Users with NO recognized `vsphere-*` groups are denied ALL access. There is no implicit "read" permission.
|
||||
</Aside>
|
||||
|
||||
## Tool Permission Mapping
|
||||
|
||||
### READ_ONLY (32 tools)
|
||||
|
||||
View and inspect operations:
|
||||
|
||||
```
|
||||
list_vms, get_vm_info, list_snapshots, get_vm_stats
|
||||
get_host_stats, vm_screenshot, get_vm_tools_status
|
||||
wait_for_vm_tools, list_disks, get_disk_info
|
||||
list_nics, get_nic_info, get_serial_port
|
||||
list_hosts, get_host_info, get_host_hardware
|
||||
get_host_networking, list_services, get_service_status
|
||||
get_ntp_config, get_datastore_info, browse_datastore
|
||||
get_vcenter_info, get_resource_pool_info, get_network_info
|
||||
list_templates, get_alarms, get_recent_events
|
||||
list_folders, list_clusters, get_cluster_info
|
||||
list_resource_pools, list_tags, get_vm_tags
|
||||
list_recent_tasks, list_recent_events
|
||||
```
|
||||
|
||||
### POWER_OPS (14 tools)
|
||||
|
||||
Power state and snapshots:
|
||||
|
||||
```
|
||||
power_on_vm, power_off_vm, shutdown_guest
|
||||
reboot_guest, suspend_vm, reset_vm
|
||||
create_snapshot, revert_to_snapshot
|
||||
delete_snapshot, delete_all_snapshots
|
||||
connect_nic, setup_serial_port
|
||||
connect_serial_port, clear_serial_port
|
||||
```
|
||||
|
||||
### VM_LIFECYCLE (33 tools)
|
||||
|
||||
Create, modify, and delete VMs:
|
||||
|
||||
```
|
||||
create_vm, clone_vm, delete_vm
|
||||
reconfigure_vm, rename_vm
|
||||
add_disk, remove_disk, resize_disk
|
||||
add_nic, remove_nic, change_nic_network
|
||||
remove_serial_port
|
||||
deploy_ovf, export_ovf, list_ovf_networks
|
||||
upload_to_datastore, download_from_datastore
|
||||
create_folder, delete_folder, move_vm_to_folder
|
||||
create_resource_pool, delete_resource_pool
|
||||
move_vm_to_resource_pool
|
||||
apply_tag_to_vm, remove_tag_from_vm
|
||||
migrate_vm, cancel_task
|
||||
```
|
||||
|
||||
### HOST_ADMIN (6 tools)
|
||||
|
||||
ESXi host management:
|
||||
|
||||
```
|
||||
start_service, stop_service, restart_service
|
||||
enter_maintenance_mode, exit_maintenance_mode
|
||||
reboot_host, shutdown_host
|
||||
```
|
||||
|
||||
### FULL_ADMIN (11 tools)
|
||||
|
||||
Guest OS operations and full control:
|
||||
|
||||
```
|
||||
run_command_in_guest, read_guest_file, write_guest_file
|
||||
list_guest_processes, list_guest_directory
|
||||
create_guest_directory, delete_guest_file
|
||||
```
|
||||
|
||||
<Aside>
|
||||
Guest operations are the most privileged because they allow arbitrary command execution inside VMs.
|
||||
</Aside>
|
||||
|
||||
## Permission Check Flow
|
||||
|
||||
When a tool is invoked:
|
||||
|
||||
1. **Extract user identity** from OAuth token claims
|
||||
2. **Get user's groups** from `groups` claim
|
||||
3. **Look up required permission** for the tool
|
||||
4. **Check if any group grants** the required permission
|
||||
5. **Allow or deny** with audit logging
|
||||
|
||||
```python
|
||||
# Pseudocode
|
||||
def check_permission(tool_name: str, user_groups: list[str]) -> bool:
|
||||
required = TOOL_PERMISSIONS[tool_name] # e.g., POWER_OPS
|
||||
|
||||
for group in user_groups:
|
||||
if group in GROUP_PERMISSIONS:
|
||||
granted = GROUP_PERMISSIONS[group] # e.g., {READ_ONLY, POWER_OPS}
|
||||
if required in granted:
|
||||
return True
|
||||
|
||||
return False # Default deny
|
||||
```
|
||||
|
||||
## Audit Logging
|
||||
|
||||
Every permission decision is logged:
|
||||
|
||||
### Successful access
|
||||
|
||||
```json
|
||||
{
|
||||
"timestamp": "2025-01-16T08:15:32.123456+00:00",
|
||||
"user": "ryan@example.com",
|
||||
"groups": ["vsphere-admins"],
|
||||
"tool": "power_on_vm",
|
||||
"args": {"vm_name": "web-server"},
|
||||
"duration_ms": 1234.56,
|
||||
"result": "success"
|
||||
}
|
||||
```
|
||||
|
||||
### Permission denied
|
||||
|
||||
```json
|
||||
{
|
||||
"timestamp": "2025-01-16T08:15:32.123456+00:00",
|
||||
"user": "intern@example.com",
|
||||
"groups": ["vsphere-readers"],
|
||||
"tool": "delete_vm",
|
||||
"args": {"vm_name": "production-db"},
|
||||
"required_permission": "vm_lifecycle",
|
||||
"event": "PERMISSION_DENIED"
|
||||
}
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "Permission denied" for expected access
|
||||
|
||||
1. **Check group names match exactly**: `vsphere-admins` vs `vsphere_admins`
|
||||
2. **Verify groups claim** in JWT token (decode at [jwt.io](https://jwt.io))
|
||||
3. **Check group membership** in your OIDC provider
|
||||
4. **Review audit logs** for the exact permission required
|
||||
|
||||
### User has no permissions at all
|
||||
|
||||
1. **Confirm user is in at least one** `vsphere-*` group
|
||||
2. **Check OIDC provider** includes `groups` in token claims
|
||||
3. **Verify** the groups scope is requested during OAuth flow
|
||||
202
docs/src/content/docs/reference/tools.md
Normal file
202
docs/src/content/docs/reference/tools.md
Normal file
@ -0,0 +1,202 @@
|
||||
---
|
||||
title: Tool Reference
|
||||
description: Complete reference for all 94 MCP tools
|
||||
---
|
||||
|
||||
import { Aside } from '@astrojs/starlight/components';
|
||||
|
||||
mcvsphere provides 94 MCP tools for comprehensive VMware vSphere management.
|
||||
|
||||
## VM Lifecycle
|
||||
|
||||
Create, clone, delete, and configure virtual machines.
|
||||
|
||||
| Tool | Description |
|
||||
|------|-------------|
|
||||
| `create_vm` | Create a new VM from scratch |
|
||||
| `clone_vm` | Clone from template or existing VM |
|
||||
| `delete_vm` | Remove a VM permanently |
|
||||
| `reconfigure_vm` | Change CPU, memory, annotations |
|
||||
| `rename_vm` | Rename a VM |
|
||||
| `list_vms` | List all VMs |
|
||||
| `get_vm_info` | Detailed VM information |
|
||||
|
||||
## Power Operations
|
||||
|
||||
Control VM power state.
|
||||
|
||||
| Tool | Description |
|
||||
|------|-------------|
|
||||
| `power_on_vm` | Start a VM |
|
||||
| `power_off_vm` | Force power off (like pulling the plug) |
|
||||
| `shutdown_guest` | Graceful OS shutdown via VMware Tools |
|
||||
| `reboot_guest` | Graceful OS reboot via VMware Tools |
|
||||
| `suspend_vm` | Suspend to memory |
|
||||
| `reset_vm` | Hard reset |
|
||||
|
||||
<Aside type="tip">
|
||||
Use `shutdown_guest` and `reboot_guest` for graceful operations. They require VMware Tools running in the guest.
|
||||
</Aside>
|
||||
|
||||
## Snapshots
|
||||
|
||||
Point-in-time VM state management.
|
||||
|
||||
| Tool | Description |
|
||||
|------|-------------|
|
||||
| `create_snapshot` | Create a new snapshot |
|
||||
| `revert_to_snapshot` | Restore VM to snapshot state |
|
||||
| `delete_snapshot` | Remove a specific snapshot |
|
||||
| `delete_all_snapshots` | Remove all snapshots (consolidate) |
|
||||
| `list_snapshots` | List all snapshots |
|
||||
|
||||
## Guest Operations
|
||||
|
||||
Execute commands and transfer files inside VMs without SSH.
|
||||
|
||||
| Tool | Description |
|
||||
|------|-------------|
|
||||
| `run_command_in_guest` | Execute any command in the guest OS |
|
||||
| `read_guest_file` | Download file from guest |
|
||||
| `write_guest_file` | Upload file to guest |
|
||||
| `list_guest_processes` | List running processes |
|
||||
| `list_guest_directory` | Browse guest filesystem |
|
||||
| `create_guest_directory` | Create directory in guest |
|
||||
| `delete_guest_file` | Delete file in guest |
|
||||
|
||||
<Aside type="note">
|
||||
Guest operations require VMware Tools installed and running. Use `get_vm_tools_status` to verify.
|
||||
</Aside>
|
||||
|
||||
## Console & Monitoring
|
||||
|
||||
Visual access and performance monitoring.
|
||||
|
||||
| Tool | Description |
|
||||
|------|-------------|
|
||||
| `vm_screenshot` | Capture VM console as image |
|
||||
| `get_vm_stats` | CPU, memory, disk, network metrics |
|
||||
| `get_host_stats` | ESXi host performance metrics |
|
||||
| `wait_for_vm_tools` | Block until Tools are ready |
|
||||
| `get_vm_tools_status` | Check Tools installation state |
|
||||
|
||||
## Serial Console
|
||||
|
||||
For network appliances and headless systems.
|
||||
|
||||
| Tool | Description |
|
||||
|------|-------------|
|
||||
| `setup_serial_port` | Configure serial port |
|
||||
| `get_serial_port` | Get serial port configuration |
|
||||
| `connect_serial_port` | Get connection URI (telnet/ssh) |
|
||||
| `clear_serial_port` | Clear serial port buffer |
|
||||
| `remove_serial_port` | Remove serial port |
|
||||
|
||||
## Disk Management
|
||||
|
||||
Virtual disk operations.
|
||||
|
||||
| Tool | Description |
|
||||
|------|-------------|
|
||||
| `add_disk` | Add new virtual disk |
|
||||
| `remove_disk` | Remove virtual disk |
|
||||
| `resize_disk` | Expand disk capacity |
|
||||
| `list_disks` | List all disks |
|
||||
| `get_disk_info` | Detailed disk information |
|
||||
|
||||
## Network Adapters
|
||||
|
||||
Virtual NIC management.
|
||||
|
||||
| Tool | Description |
|
||||
|------|-------------|
|
||||
| `add_nic` | Add network adapter |
|
||||
| `remove_nic` | Remove network adapter |
|
||||
| `connect_nic` | Connect/disconnect NIC |
|
||||
| `change_nic_network` | Change port group |
|
||||
| `list_nics` | List all NICs |
|
||||
| `get_nic_info` | Detailed NIC information |
|
||||
|
||||
## OVF/OVA Operations
|
||||
|
||||
Deploy and export virtual appliances.
|
||||
|
||||
| Tool | Description |
|
||||
|------|-------------|
|
||||
| `deploy_ovf` | Deploy OVF/OVA package |
|
||||
| `export_ovf` | Export VM as OVF |
|
||||
| `list_ovf_networks` | List networks in OVF |
|
||||
| `upload_to_datastore` | Upload file to datastore |
|
||||
| `download_from_datastore` | Download file from datastore |
|
||||
|
||||
## Host Management
|
||||
|
||||
ESXi host operations.
|
||||
|
||||
| Tool | Description |
|
||||
|------|-------------|
|
||||
| `list_hosts` | List all ESXi hosts |
|
||||
| `get_host_info` | Host configuration details |
|
||||
| `get_host_hardware` | Hardware inventory |
|
||||
| `get_host_networking` | Network configuration |
|
||||
| `list_services` | Host services |
|
||||
| `get_service_status` | Service state |
|
||||
| `start_service` | Start a host service |
|
||||
| `stop_service` | Stop a host service |
|
||||
| `restart_service` | Restart a host service |
|
||||
| `get_ntp_config` | NTP configuration |
|
||||
|
||||
## Datastore & Resources
|
||||
|
||||
Storage and resource inventory.
|
||||
|
||||
| Tool | Description |
|
||||
|------|-------------|
|
||||
| `get_datastore_info` | Datastore capacity and usage |
|
||||
| `browse_datastore` | List datastore contents |
|
||||
| `get_vcenter_info` | vCenter version and configuration |
|
||||
| `get_resource_pool_info` | Resource pool settings |
|
||||
| `get_network_info` | Network/port group details |
|
||||
| `list_templates` | VM templates |
|
||||
| `get_alarms` | Active alarms |
|
||||
| `get_recent_events` | Recent vCenter events |
|
||||
|
||||
## vCenter Operations
|
||||
|
||||
Organization and cluster management.
|
||||
|
||||
| Tool | Description |
|
||||
|------|-------------|
|
||||
| `list_folders` | VM and host folders |
|
||||
| `create_folder` | Create new folder |
|
||||
| `delete_folder` | Remove folder |
|
||||
| `move_vm_to_folder` | Organize VMs |
|
||||
| `list_clusters` | Compute clusters |
|
||||
| `get_cluster_info` | Cluster configuration |
|
||||
| `list_resource_pools` | Resource pools |
|
||||
| `create_resource_pool` | Create resource pool |
|
||||
| `delete_resource_pool` | Remove resource pool |
|
||||
| `move_vm_to_resource_pool` | Move VM to pool |
|
||||
| `list_tags` | vCenter tags |
|
||||
| `get_vm_tags` | Tags on a VM |
|
||||
| `apply_tag_to_vm` | Apply tag |
|
||||
| `remove_tag_from_vm` | Remove tag |
|
||||
| `migrate_vm` | vMotion/Storage vMotion |
|
||||
| `list_recent_tasks` | Recent vCenter tasks |
|
||||
| `list_recent_events` | Recent events |
|
||||
| `cancel_task` | Cancel running task |
|
||||
|
||||
## MCP Resources
|
||||
|
||||
In addition to tools, mcvsphere provides 6 real-time resources:
|
||||
|
||||
| Resource URI | Data |
|
||||
|--------------|------|
|
||||
| `esxi://vms` | All virtual machines |
|
||||
| `esxi://hosts` | All ESXi hosts |
|
||||
| `esxi://datastores` | All datastores |
|
||||
| `esxi://networks` | All networks |
|
||||
| `esxi://clusters` | All clusters |
|
||||
| `esxi://resource-pools` | All resource pools |
|
||||
|
||||
Resources provide always-current inventory data that Claude can reference during conversations.
|
||||
74
docs/src/styles/custom.css
Normal file
74
docs/src/styles/custom.css
Normal file
@ -0,0 +1,74 @@
|
||||
/* mcvsphere Documentation Custom Styles */
|
||||
|
||||
:root {
|
||||
/* VMware-inspired color palette */
|
||||
--sl-color-accent-low: #1a3a5c;
|
||||
--sl-color-accent: #146eb4;
|
||||
--sl-color-accent-high: #3d9cdb;
|
||||
--sl-color-white: #ffffff;
|
||||
--sl-color-gray-1: #eceef2;
|
||||
--sl-color-gray-2: #c0c2c7;
|
||||
--sl-color-gray-3: #888b96;
|
||||
--sl-color-gray-4: #545861;
|
||||
--sl-color-gray-5: #353841;
|
||||
--sl-color-gray-6: #24272f;
|
||||
--sl-color-black: #17181c;
|
||||
}
|
||||
|
||||
:root[data-theme='dark'] {
|
||||
--sl-color-accent-low: #1a3a5c;
|
||||
--sl-color-accent: #3d9cdb;
|
||||
--sl-color-accent-high: #7fbfeb;
|
||||
}
|
||||
|
||||
/* Code block styling */
|
||||
.expressive-code {
|
||||
margin: 1.5rem 0;
|
||||
}
|
||||
|
||||
/* Hero section enhancement */
|
||||
.hero {
|
||||
--sl-color-hero-text: var(--sl-color-white);
|
||||
}
|
||||
|
||||
/* Card styling for feature boxes */
|
||||
.card {
|
||||
border-radius: 0.5rem;
|
||||
background: var(--sl-color-gray-6);
|
||||
padding: 1.5rem;
|
||||
margin: 1rem 0;
|
||||
}
|
||||
|
||||
/* Badge styling for permission levels */
|
||||
.badge {
|
||||
display: inline-block;
|
||||
padding: 0.25rem 0.5rem;
|
||||
border-radius: 0.25rem;
|
||||
font-size: 0.875rem;
|
||||
font-weight: 500;
|
||||
}
|
||||
|
||||
.badge-reader {
|
||||
background: #e3f2fd;
|
||||
color: #1565c0;
|
||||
}
|
||||
|
||||
.badge-operator {
|
||||
background: #e8f5e9;
|
||||
color: #2e7d32;
|
||||
}
|
||||
|
||||
.badge-admin {
|
||||
background: #fff3e0;
|
||||
color: #ef6c00;
|
||||
}
|
||||
|
||||
.badge-host-admin {
|
||||
background: #fce4ec;
|
||||
color: #c2185b;
|
||||
}
|
||||
|
||||
.badge-super-admin {
|
||||
background: #f3e5f5;
|
||||
color: #7b1fa2;
|
||||
}
|
||||
6
docs/tsconfig.json
Normal file
6
docs/tsconfig.json
Normal file
@ -0,0 +1,6 @@
|
||||
{
|
||||
"extends": "astro/tsconfigs/strict",
|
||||
"compilerOptions": {
|
||||
"strictNullChecks": true
|
||||
}
|
||||
}
|
||||
Loading…
x
Reference in New Issue
Block a user