jesus/provisioning

Fork 0

Jesús Pérez d0b6b9b759

chore: fix docs after fences fix

2026-01-14 04:59:11 +00:00

16 KiB

Raw Blame History

Model Context Protocol (MCP) Integration

Status: ✅ Production-Ready (MCP 0.6.0+, integrated with Claude, compatible with all LLMs)

The MCP server provides standardized Model Context Protocol integration, allowing external LLMs (Claude, GPT-4, local models) to access provisioning platform capabilities as tools. This enables complex multi-step workflows, tool composition, and integration with existing LLM applications.

Architecture Overview

The MCP integration follows the Model Context Protocol specification:

┌──────────────────────────────────────────────────────────────┐
│ External LLM (Claude, GPT-4, etc.)                           │
└────────────────────┬─────────────────────────────────────────┘
                     │
                     │ Tool Calls (JSON-RPC)
                     ▼
┌──────────────────────────────────────────────────────────────┐
│ MCP Server (provisioning/platform/crates/mcp-server)         │
│                                                              │
│ ┌───────────────────────────────────────────────────────┐    │
│ │ Tool Registry                                         │    │
│ │ - generate_config(description, schema)                │    │
│ │ - validate_config(config)                             │    │
│ │ - search_docs(query)                                  │    │
│ │ - troubleshoot_deployment(logs)                       │    │
│ │ - get_schema(name)                                    │    │
│ │ - check_compliance(config, policy)                    │    │
│ └───────────────────────────────────────────────────────┘    │
│                         │                                    │
│                         ▼                                    │
│ ┌───────────────────────────────────────────────────────┐    │
│ │ Implementation Layer                                  │    │
│ │ - AI Service client (ai-service port 8083)            │    │
│ │ - Validator client                                    │    │
│ │ - RAG client (SurrealDB)                              │    │
│ │ - Schema loader                                       │    │
│ └───────────────────────────────────────────────────────┘    │
└──────────────────────────────────────────────────────────────┘

MCP Server Launch

The MCP server is started as a stdio-based service:

# Start MCP server (stdio transport)
provisioning-mcp-server --config /etc/provisioning/ai.toml

# With debug logging
RUST_LOG=debug provisioning-mcp-server --config /etc/provisioning/ai.toml

# In Claude Desktop configuration
~/.claude/claude_desktop_config.json:
{
  "mcpServers": {
    "provisioning": {
      "command": "provisioning-mcp-server",
      "args": ["--config", "/etc/provisioning/ai.toml"],
      "env": {
        "PROVISIONING_TOKEN": "your-auth-token"
      }
    }
  }
}

Available Tools

1. Config Generation

Tool: generate_config

Generate infrastructure configuration from natural language description.

{
  "name": "generate_config",
  "description": "Generate a Nickel infrastructure configuration from a natural language description",
  "inputSchema": {
    "type": "object",
    "properties": {
      "description": {
        "type": "string",
        "description": "Natural language description of desired infrastructure"
      },
      "schema": {
        "type": "string",
        "description": "Target schema name (e.g., 'database', 'kubernetes', 'network'). Optional."
      },
      "format": {
        "type": "string",
        "enum": ["nickel", "toml"],
        "description": "Output format (default: nickel)"
      }
    },
    "required": ["description"]
  }
}

Example Usage:

# Via MCP client
mcp-client provisioning generate_config 
  --description "Production PostgreSQL cluster with encryption and daily backups" 
  --schema database

# Claude desktop prompt:
# @provisioning: Generate a production PostgreSQL setup with automated backups

Response:

{
  database = {
    engine = "postgresql",
    version = "15.0",
    
    instance = {
      instance_class = "db.r6g.xlarge",
      allocated_storage_gb = 100,
      iops = 3000,
    },
    
    security = {
      encryption_enabled = true,
      encryption_key_id = "kms://prod-db-key",
      tls_enabled = true,
      tls_version = "1.3",
    },
    
    backup = {
      enabled = true,
      retention_days = 30,
      preferred_window = "03:00-04:00",
      copy_to_region = "us-west-2",
    },
    
    monitoring = {
      enhanced_monitoring_enabled = true,
      monitoring_interval_seconds = 60,
      log_exports = ["postgresql"],
    },
  }
}

2. Config Validation

Tool: validate_config

Validate a Nickel configuration against schemas and policies.

{
  "name": "validate_config",
  "description": "Validate a Nickel configuration file",
  "inputSchema": {
    "type": "object",
    "properties": {
      "config": {
        "type": "string",
        "description": "Nickel configuration content or file path"
      },
      "schema": {
        "type": "string",
        "description": "Schema name to validate against (optional)"
      },
      "strict": {
        "type": "boolean",
        "description": "Enable strict validation (default: true)"
      }
    },
    "required": ["config"]
  }
}

Example Usage:

# Validate configuration
mcp-client provisioning validate_config 
  --config "$(cat workspaces/prod/database.ncl)"

# With specific schema
mcp-client provisioning validate_config 
  --config "workspaces/prod/kubernetes.ncl" 
  --schema kubernetes

Response:

{
  "valid": true,
  "errors": [],
  "warnings": [
    "Consider enabling automated backups for production use"
  ],
  "metadata": {
    "schema": "kubernetes",
    "version": "1.28",
    "validated_at": "2025-01-13T10:45:30Z"
  }
}

3. Documentation Search

Tool: search_docs

Search infrastructure documentation using RAG system.

{
  "name": "search_docs",
  "description": "Search provisioning documentation for information",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "Search query (natural language)"
      },
      "top_k": {
        "type": "integer",
        "description": "Number of results (default: 5)"
      },
      "doc_type": {
        "type": "string",
        "enum": ["guide", "schema", "example", "troubleshooting"],
        "description": "Filter by document type (optional)"
      }
    },
    "required": ["query"]
  }
}

Example Usage:

# Search documentation
mcp-client provisioning search_docs 
  --query "How do I configure PostgreSQL with replication?"

# Get examples
mcp-client provisioning search_docs 
  --query "Kubernetes networking" 
  --doc_type example 
  --top_k 3

Response:

{
  "results": [
    {
      "source": "provisioning/docs/src/guides/database-replication.md",
      "excerpt": "PostgreSQL logical replication enables streaming of changes...",
      "relevance": 0.94,
      "section": "Setup Logical Replication"
    },
    {
      "source": "provisioning/schemas/database.ncl",
      "excerpt": "replication = { enabled = true, mode = \"logical\", ... }",
      "relevance": 0.87,
      "section": "Replication Configuration"
    }
  ]
}

4. Deployment Troubleshooting

Tool: troubleshoot_deployment

Analyze deployment failures and suggest fixes.

{
  "name": "troubleshoot_deployment",
  "description": "Analyze deployment logs and suggest fixes",
  "inputSchema": {
    "type": "object",
    "properties": {
      "deployment_id": {
        "type": "string",
        "description": "Deployment ID (e.g., 'deploy-2025-01-13-001')"
      },
      "logs": {
        "type": "string",
        "description": "Deployment logs (optional, if deployment_id not provided)"
      },
      "error_analysis_depth": {
        "type": "string",
        "enum": ["shallow", "deep"],
        "description": "Analysis depth (default: deep)"
      }
    }
  }
}

Example Usage:

# Troubleshoot recent deployment
mcp-client provisioning troubleshoot_deployment 
  --deployment_id "deploy-2025-01-13-001"

# With custom logs
mcp-client provisioning troubleshoot_deployment 
| --logs "$(journalctl -u provisioning --no-pager | tail -100)" |

Response:

{
  "status": "failure",
  "root_cause": "Database connection timeout during migration phase",
  "analysis": {
    "phase": "database_migration",
    "error_type": "connectivity",
    "confidence": 0.95
  },
  "suggestions": [
    "Verify database security group allows inbound on port 5432",
    "Check database instance status (may be rebooting)",
    "Increase connection timeout in configuration"
  ],
  "corrected_config": "...generated Nickel config with fixes...",
  "similar_issues": [
    "[https://docs/troubleshooting/database-connectivity.md"](https://docs/troubleshooting/database-connectivity.md")
  ]
}

5. Get Schema

Tool: get_schema

Retrieve schema definition with examples.

{
  "name": "get_schema",
  "description": "Get a provisioning schema definition",
  "inputSchema": {
    "type": "object",
    "properties": {
      "schema_name": {
        "type": "string",
        "description": "Schema name (e.g., 'database', 'kubernetes')"
      },
      "format": {
        "type": "string",
        "enum": ["schema", "example", "documentation"],
        "description": "Response format (default: schema)"
      }
    },
    "required": ["schema_name"]
  }
}

Example Usage:

# Get schema definition
mcp-client provisioning get_schema --schema_name database

# Get example configuration
mcp-client provisioning get_schema 
  --schema_name kubernetes 
  --format example

6. Compliance Check

Tool: check_compliance

Verify configuration against compliance policies (Cedar).

{
  "name": "check_compliance",
  "description": "Check configuration against compliance policies",
  "inputSchema": {
    "type": "object",
    "properties": {
      "config": {
        "type": "string",
        "description": "Configuration to check"
      },
      "policy_set": {
        "type": "string",
        "description": "Policy set to check against (e.g., 'pci-dss', 'hipaa', 'sox')"
      }
    },
    "required": ["config", "policy_set"]
  }
}

Example Usage:

# Check against PCI-DSS
mcp-client provisioning check_compliance 
  --config "$(cat workspaces/prod/database.ncl)" 
  --policy_set pci-dss

Integration Examples

Claude Desktop (Most Common)

~/.claude/claude_desktop_config.json:
{
  "mcpServers": {
    "provisioning": {
      "command": "provisioning-mcp-server",
      "args": ["--config", "/etc/provisioning/ai.toml"],
      "env": {
        "PROVISIONING_API_KEY": "sk-...",
        "PROVISIONING_BASE_URL": "[http://localhost:8083"](http://localhost:8083")
      }
    }
  }
}

Usage in Claude:

User: I need a production Kubernetes cluster in AWS with automatic scaling

Claude can now use provisioning tools:
I'll help you create a production Kubernetes cluster. Let me:
1. Search the documentation for best practices
2. Generate a configuration template
3. Validate it against your policies
4. Provide the final configuration

OpenAI Function Calling

import openai

tools = [
    {
        "type": "function",
        "function": {
            "name": "generate_config",
            "description": "Generate infrastructure configuration",
            "parameters": {
                "type": "object",
                "properties": {
                    "description": {
                        "type": "string",
                        "description": "Infrastructure description"
                    }
                },
                "required": ["description"]
            }
        }
    }
]

response = openai.ChatCompletion.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Create a PostgreSQL database"}],
    tools=tools
)

Local LLM Integration (Ollama)

# Start Ollama with provisioning MCP
OLLAMA_MCP_SERVERS=provisioning://localhost:3000 
  ollama serve

# Use with llama2 or mistral
curl [http://localhost:11434/api/generate](http://localhost:11434/api/generate) 
  -d '{
    "model": "mistral",
    "prompt": "Create a Kubernetes cluster",
    "tools": [{"type": "mcp", "server": "provisioning"}]
  }'

Error Handling

Tools return consistent error responses:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Configuration has 3 validation errors",
    "details": [
      {
        "field": "database.version",
        "message": "PostgreSQL version 9.6 is deprecated",
        "severity": "error"
      },
      {
        "field": "backup.retention_days",
        "message": "Recommended minimum is 30 days for production",
        "severity": "warning"
      }
    ]
  }
}

Performance

| | Operation | Latency | Notes | | | | ----------- | --------- | ------- | | | | generate_config | 2-5s | Depends on LLM and config complexity | | | | validate_config | 500-1000ms | Parallel schema validation | | | | search_docs | 300-800ms | RAG hybrid search | | | | troubleshoot | 3-8s | Depends on log size and analysis depth | | | | get_schema | 100-300ms | Cached schema retrieval | | | | check_compliance | 500-2000ms | Policy evaluation | |

Configuration

See Configuration Guide for MCP-specific settings:

MCP server port and binding
Tool registry customization
Rate limiting for tool calls
Access control (Cedar policies)

Security

Authentication

Tools require valid provisioning API token
Token scoped to user's workspace
All tool calls authenticated and logged

Authorization

Cedar policies control which tools user can call
Example: allow(principal, action, resource) when role == "admin"
Detailed audit trail of all tool invocations

Data Protection

Secrets never passed through MCP
Configuration sanitized before analysis
PII removed from logs sent to external LLMs

Monitoring and Debugging

# Monitor MCP server
provisioning admin mcp status

# View MCP tool calls
provisioning admin logs --filter "mcp_tools" --tail 100

# Debug tool response
RUST_LOG=provisioning::mcp=debug provisioning-mcp-server

Architecture - AI system overview
RAG System - Documentation search
Configuration - MCP setup
API Reference - Detailed API endpoints
ADR-015 - Design decisions

Last Updated: 2025-01-13 Status: ✅ Production-Ready MCP Version: 0.6.0+ Supported LLMs: Claude, GPT-4, Llama, Mistral, all MCP-compatible models

16 KiB Raw Blame History

Model Context Protocol (MCP) Integration

Architecture Overview

MCP Server Launch

Available Tools

1. Config Generation

2. Config Validation

3. Documentation Search

4. Deployment Troubleshooting

5. Get Schema

6. Compliance Check

Integration Examples

Claude Desktop (Most Common)

OpenAI Function Calling

Local LLM Integration (Ollama)

Error Handling

Performance

Configuration

Security

Authentication

Authorization

Data Protection

Monitoring and Debugging

Related Documentation

16 KiB

Raw Blame History