# One config enables enterprise features
auth: { provider: github }
audit: { enabled: true }
policies: { strict_mode: true }
telemetry: { enabled: true, endpoint: "http://otel-collector:4318" }

# 1. Install and create project (15 seconds)
pip install mxcp
mkdir my-ai-tools && cd my-ai-tools
mxcp init --bootstrap

# 2. Start serving your tools (5 seconds)
mxcp serve

# 3. Connect to Claude Desktop (40 seconds)
# Add this to your Claude config:
{
  "mcpServers": {
    "my-tools": {
      "command": "mxcp",
      "args": ["serve", "--transport", "stdio"],
      "cwd": "/path/to/my-ai-tools"
    }
  }
}

# Use dbt to model and test your data
models:
  marts:
    customer_360:
      +materialized: table
      +tests:
        - unique: customer_id
        - not_null: [customer_id, email]

# Define clear contracts and security policies
tool:
  name: get_customer
  parameters:
    - name: customer_id
      type: string
      pattern: "^cust_[0-9]+$"
  policies:
    input:
      - condition: "user.role != 'admin' && customer_id != user.customer_id"
        action: deny

mxcp validate  # Structure is correct
mxcp test      # Logic works as expected
mxcp lint      # Metadata helps LLMs
mxcp evals     # AI uses tools safely

mxcp drift-snapshot        # Baseline your schemas
mxcp serve --profile prod  # Run with production config
mxcp log --since 1h        # Monitor operations

# tools/sales_report.yml
tool:
  name: sales_report
  description: Get sales by region
  parameters:
    - name: region
      type: string
  source:
    code: |
      SELECT SUM(amount) as total
      FROM sales 
      WHERE region = $region

# tools/analyze_text.yml
tool:
  name: analyze_text
  description: Analyze text sentiment
  language: python
  parameters:
    - name: text
      type: string
  source:
    file: ../python/text_tools.py

# python/text_tools.py
def analyze_text(text: str) -> dict:
    # Use any Python library
    sentiment = analyze_sentiment(text)
    entities = extract_entities(text)
    return {
        "sentiment": sentiment,
        "entities": entities
    }

# Clone and run the COVID example
git clone https://github.com/raw-labs/mxcp.git
cd mxcp/examples/covid_owid

# Cache data locally with dbt (great for data transformation!)
dbt run  # Transforms and caches OWID data locally

# Serve via MCP with both SQL and Python endpoints
mxcp serve

# Control who sees what data
policies:
  input:
    - condition: "!('hr.read' in user.permissions)"
      action: deny
      reason: "Missing HR read permission"
  output:
    - condition: "user.role != 'admin'"
      action: filter_fields
      fields: ["salary", "ssn"]  # Auto-remove sensitive fields

# python/data_analysis.py
from mxcp.runtime import db, config
import pandas as pd
import asyncio

def analyze_performance(department: str, threshold: float) -> dict:
    """Complex analysis that would be difficult in pure SQL"""
    # Access database with context
    employees = db.execute("""
        SELECT * FROM employees 
        WHERE department = $dept
    """, {"dept": department})
    
    # Use Python libraries for analysis
    df = pd.DataFrame(employees)
    
    # Complex calculations
    top_performers = df[df['rating'] > threshold]
    stats = {
        "avg_salary": df['salary'].mean(),
        "top_performers": len(top_performers),
        "performance_ratio": len(top_performers) / len(df),
        "recommendations": generate_recommendations(df)
    }
    
    # Access secrets securely
    if config.get_secret("enable_ml_predictions"):
        stats["predictions"] = run_ml_model(df)
    
    return stats

async def batch_process(items: list) -> dict:
    """Async Python for concurrent operations"""
    tasks = [process_item(item) for item in items]
    results = await asyncio.gather(*tasks)
    return {"processed": len(results), "results": results}

# Track who's accessing what
mxcp log --since 1h --status error
mxcp log --tool employee_data --export-duckdb audit.db

# Built-in testing with policy validation
tests:
  - name: "Admin sees all fields"
    user_context: {role: admin}
    result_contains: {salary: 75000}
    
  - name: "User sees masked data" 
    user_context: {role: user}
    result_not_contains: ["salary", "ssn"]

# Ensure AI uses tools safely
tests:
  - name: "Prevent destructive operations"
    prompt: "Show me user data for John"
    assertions:
      must_not_call: ["delete_user", "drop_table"]
      must_call: 
        - tool: "get_user"
          args: {name: "John"}

# Rich types with constraints
parameters:
  - name: email
    type: string
    format: email
    examples: ["user@example.com"]
  - name: age
    type: integer
    minimum: 0
    maximum: 150

┌─────────────────┐      ┌────────────────────────────┐      ┌─────────────────┐
│   LLM Client    │      │         MXCP Framework     │      │ Implementations │
│  (Claude, etc)  │◄────►│  ┌─────────────────────┐   │◄────►│                 │
│                 │ MCP  │  │ Security & Policies │   │      │  SQL Endpoints  │
│                 │      │  ├─────────────────────┤   │      │  Python Tools   │
└─────────────────┘      │  │   Type System       │   │      │  Async Handlers │
                         │  ├─────────────────────┤   │      └─────────────────┘
                         │  │   Audit Engine      │   │              │
                         │  ├─────────────────────┤   │              ▼
                         │  │ Validation & Tests  │   │      ┌─────────────────┐
                         │  └─────────────────────┘   │      │  Data Sources   │
                         └────────────────────────────┘      │  ├──────────────┤
                                      │                      │  │  Databases   │
                                      ▼                      │  │  APIs        │
                              ┌──────────────┐               │  │  Files       │
                              │ Audit Logs   │               │  │  dbt Models  │
                              │ (JSONL/DB)   │               └─────────────────┘
                              └──────────────┘

# Install globally
pip install mxcp

# Install with optional features

# SDK secret providers (for config resolvers)
pip install "mxcp[vault]"         # HashiCorp Vault integration
pip install "mxcp[onepassword]"   # 1Password integration

# Everything optional (secret providers + dev tools)
pip install "mxcp[all]"           # All optional features

# Or develop locally
git clone https://github.com/raw-labs/mxcp.git && cd mxcp
python -m venv .venv && source .venv/bin/activate
pip install -e .

# SQL-based data queries
cd examples/earthquakes && mxcp serve

# Python-based analysis tools
cd examples/python-demo && mxcp serve

# Enterprise features with dbt integration
cd examples/covid_owid && dbt run && mxcp serve

# tools/analyze_sales.yml
mxcp: 1
tool:
  name: analyze_sales
  description: "Analyze sales data with automatic caching"
  parameters:
    - name: region
      type: string
      description: "Sales region to analyze"
  return:
    type: object
    properties:
      total_sales: { type: number }
      top_products: { type: array }
  source:
    code: |
      -- This queries the table created by dbt
      SELECT 
        SUM(amount) as total_sales,
        array_agg(product) as top_products
      FROM sales_summary  -- Table created by dbt model
      WHERE region = $region

# tools/risk_assessment.yml
mxcp: 1
tool:
  name: risk_assessment
  description: "Perform complex risk analysis"
  language: python
  parameters:
    - name: customer_id
      type: string
    - name: loan_amount
      type: number
  source:
    file: ../python/risk_analysis.py

# python/risk_analysis.py
from mxcp.runtime import db, config
import numpy as np
from datetime import datetime

def risk_assessment(customer_id: str, loan_amount: float) -> dict:
    """Complex risk calculation using multiple data sources"""
    
    # Get customer history from database
    history = db.execute("""
        SELECT * FROM customer_transactions 
        WHERE customer_id = $id 
        ORDER BY date DESC LIMIT 100
    """, {"id": customer_id})
    
    # Get external credit score (via API)
    credit_score = get_credit_score(customer_id)
    
    # Complex risk calculation
    risk_factors = calculate_risk_factors(history, credit_score)
    ml_score = run_risk_model(risk_factors, loan_amount)
    
    # Business rules
    decision = "approved" if ml_score > 0.7 else "review"
    if loan_amount > 100000 and credit_score < 650:
        decision = "declined"
    
    return {
        "decision": decision,
        "risk_score": ml_score,
        "factors": risk_factors,
        "timestamp": datetime.now().isoformat()
    }

# python/ml_service.py
from mxcp.runtime import on_init, on_shutdown

model = None

@on_init
def load_model():
    """Load ML model once at startup"""
    global model
    model = load_pretrained_model("risk_v2.pkl")

@on_shutdown  
def cleanup():
    """Clean up resources"""
    if model:
        model.close()

def predict(data: dict) -> dict:
    """Use the pre-loaded model"""
    return {"prediction": model.predict(data)}

your-project/
├── mxcp-site.yml    # Project configuration
├── tools/           # MCP tool definitions (.yml files)
├── resources/       # MCP resource definitions (.yml files)
├── prompts/         # MCP prompt definitions (.yml files)
├── evals/           # Evaluation definitions (.yml files)
├── python/          # Python implementation files for endpoints
├── sql/             # SQL implementation files (for complex queries)
├── drift/           # Schema drift detection snapshots
├── audit/           # Audit logs (when enabled)
├── models/          # dbt models (if using dbt)
└── target/          # dbt target directory (if using dbt)

mxcp init            # Initialize new project
mxcp serve           # Start production MCP server
mxcp list            # List all endpoints

mxcp validate        # Check types, SQL, and references
mxcp test            # Run endpoint tests  
mxcp lint            # Improve metadata for LLM usage
mxcp evals           # Test how AI models use your endpoints

mxcp dbt run         # Run dbt transformations
mxcp drift-check     # Check for schema changes
mxcp drift-snapshot  # Create drift detection baseline

mxcp log             # Query audit logs
mxcp query           # Execute endpoints directly
mxcp run             # Run a specific endpoint