@macaw-ai/client 0.0.0-stage → 0.9.11

package/payload/secureAI/examples/mcp/securemcp_calculator.py

@@ -0,0 +1,248 @@
+#!/usr/bin/env python3
+"""
+Example: SecureMCP Calculator Server
+
+Demonstrates the FastMCP-compatible SecureMCP API:
+- @mcp.tool decorator for registering tools
+- @mcp.resource decorator for read-only resources
+- @mcp.prompt decorator for prompt templates
+- Context object for vault access
+- Context logging: ctx.debug(), ctx.info(), ctx.warning(), ctx.error()
+- Context audit: ctx.audit() for signed audit entries
+- Progress reporting: ctx.report_progress()
+- mcp.run() for starting the server
+
+This is the recommended way to build MCP servers with MACAW security.
+"""
+
+import asyncio
+from typing import List, Dict, Any
+
+from macaw_adapters.mcp import SecureMCP, Context
+
+
+# Create SecureMCP server - same pattern as FastMCP
+mcp = SecureMCP("calculator", version="1.0.0")
+
+
+# Tool: Add two numbers
+@mcp.tool(description="Add two numbers together")
+def add(a: float, b: float) -> float:
+    """Add a + b and return the result."""
+    return a + b
+
+
+# Tool: Subtract two numbers
+@mcp.tool(description="Subtract b from a")
+def subtract(a: float, b: float) -> float:
+    """Subtract a - b and return the result."""
+    return a - b
+
+
+# Tool: Multiply two numbers
+@mcp.tool(description="Multiply two numbers")
+def multiply(a: float, b: float) -> float:
+    """Multiply a * b and return the result."""
+    return a * b
+
+
+# Tool: Divide two numbers
+@mcp.tool(description="Divide a by b")
+def divide(a: float, b: float) -> dict:
+    """Divide a / b and return the result."""
+    if b == 0:
+        return {"error": "Division by zero"}
+    return {"result": a / b}
+
+
+# Tool with Context: Calculator with history tracking and logging
+@mcp.tool(description="Calculate and track history")
+def calculate(ctx: Context, operation: str, a: float, b: float) -> Dict[str, Any]:
+    """
+    Perform calculation and store in history.
+
+    Demonstrates Context usage for:
+    - Storing results in context vault (ctx.set)
+    - Retrieving previous values (ctx.get)
+    - Logging with ctx.info(), ctx.debug(), ctx.warning()
+    - Audit logging with ctx.audit()
+    """
+    ctx.info(f"Calculating: {a} {operation} {b}")
+
+    # Map operations to functions
+    ops = {
+        "add": lambda x, y: x + y,
+        "subtract": lambda x, y: x - y,
+        "multiply": lambda x, y: x * y,
+        "divide": lambda x, y: x / y if y != 0 else "error:div_by_zero"
+    }
+
+    if operation not in ops:
+        ctx.warning(f"Unknown operation requested: {operation}")
+        return {
+            "result": None,
+            "status": "invalid_operation",
+            "message": f"Unknown operation: {operation}"
+        }
+
+    # Check for division by zero
+    if operation == "divide" and b == 0:
+        ctx.warning("Division by zero attempted")
+
+    result = ops[operation](a, b)
+    ctx.debug(f"Result computed: {result}")
+
+    # Get existing history from context vault
+    history = ctx.get("calc_history") or []
+
+    # Add this calculation to history
+    entry = {
+        "operation": operation,
+        "a": a,
+        "b": b,
+        "result": result
+    }
+    history.append(entry)
+
+    # Store updated history in context vault
+    ctx.set("calc_history", history)
+
+    # Audit the calculation
+    ctx.audit(
+        action="calculation",
+        target="calculator",
+        outcome="success",
+        operation=operation,
+        operands=[a, b],
+        result=result
+    )
+
+    return {
+        "result": result,
+        "expression": f"{a} {operation} {b} = {result}",
+        "history_count": len(history)
+    }
+
+
+# Tool with Progress: Batch calculations
+@mcp.tool(description="Perform multiple calculations with progress")
+async def batch_calculate(ctx: Context, calculations: list) -> Dict[str, Any]:
+    """
+    Perform multiple calculations, reporting progress.
+
+    Demonstrates:
+    - ctx.report_progress() for long-running operations
+    - Async tool execution
+
+    Args:
+        calculations: List of {"op": str, "a": float, "b": float}
+    """
+    total = len(calculations)
+    if total == 0:
+        return {"results": [], "count": 0}
+
+    ctx.info(f"Starting batch of {total} calculations")
+    await ctx.report_progress(0.0, f"Processing {total} calculations")
+
+    ops = {
+        "add": lambda x, y: x + y,
+        "subtract": lambda x, y: x - y,
+        "multiply": lambda x, y: x * y,
+        "divide": lambda x, y: x / y if y != 0 else "error:div_by_zero"
+    }
+
+    results = []
+    for i, calc in enumerate(calculations):
+        op = calc.get("op", "add")
+        a = calc.get("a", 0)
+        b = calc.get("b", 0)
+
+        progress = i / total
+        await ctx.report_progress(progress, f"Calculating {i+1}/{total}: {a} {op} {b}")
+
+        if op in ops:
+            result = ops[op](a, b)
+            results.append({"expression": f"{a} {op} {b}", "result": result})
+        else:
+            results.append({"expression": f"{a} {op} {b}", "error": "unknown op"})
+
+        await asyncio.sleep(0.1)  # Simulate work
+
+    await ctx.report_progress(1.0, "Batch complete")
+    ctx.info(f"Batch complete: {total} calculations")
+
+    ctx.audit(
+        action="batch_calculation",
+        target="calculator",
+        outcome="success",
+        count=total
+    )
+
+    return {"results": results, "count": total}
+
+
+# Resource: Get calculation history
+@mcp.resource("calc://history", description="Get calculation history")
+def get_history(ctx: Context) -> List[Dict[str, Any]]:
+    """
+    Read-only resource that returns calculation history.
+
+    Resources are treated as read-only tools in SecureMCP.
+    """
+    history = ctx.get("calc_history") or []
+    return {
+        "history": history,
+        "count": len(history)
+    }
+
+
+# Prompt: Generate a calculation prompt
+@mcp.prompt(description="Generate a prompt for calculations")
+def calculation_prompt(numbers: str, operation: str = "add") -> str:
+    """
+    Generate a calculation prompt template.
+
+    Prompts are starting points for AuthenticatedPrompt creation.
+    """
+    return f"Please {operation} the following numbers: {numbers}"
+
+
+if __name__ == "__main__":
+    import sys
+
+    # Optional transport for native (non-MACAW) MCP clients:
+    #   python securemcp_calculator.py           MACAW mesh only
+    #   python securemcp_calculator.py stdio     also serve Claude Desktop / Cursor
+    #   python securemcp_calculator.py http      also serve http://localhost:8080/mcp
+    transport = sys.argv[1] if len(sys.argv) > 1 else None
+
+    # stdout is the JSON-RPC stream when transport="stdio", so the banner goes to stderr.
+    out = sys.stderr
+
+    print("=" * 60, file=out)
+    print("SecureMCP Calculator Server", file=out)
+    print("=" * 60, file=out)
+    print(file=out)
+    print("This server provides:", file=out)
+    print("  Tools: add, subtract, multiply, divide, calculate, batch_calculate", file=out)
+    print("  Resources: calc://history", file=out)
+    print("  Prompts: calculation_prompt", file=out)
+    print(file=out)
+    print("Demonstrates:", file=out)
+    print("  - ctx.info/debug/warning/error() - Logging", file=out)
+    print("  - ctx.audit() - Signed audit entries", file=out)
+    print("  - ctx.report_progress() - Progress reporting", file=out)
+    print("  - ctx.get/set() - Context vault", file=out)
+    print(file=out)
+    print("All invocations are secured by MACAW:", file=out)
+    print("  - Cryptographic signing", file=out)
+    print("  - Policy enforcement", file=out)
+    print("  - Audit logging", file=out)
+    print(file=out)
+    if transport:
+        print(f"Also serving native MCP clients over: {transport}", file=out)
+    print("Starting server...", file=out)
+    print("=" * 60, file=out)
+
+    # Run the server
+    mcp.run(transport=transport)

package/payload/secureAI/examples/mcp/securemcp_server.py

@@ -0,0 +1,75 @@
+#!/usr/bin/env python3
+"""
+SecureMCP Calculator Server
+
+Run this first, then use 1a_simple_invocation.py to test.
+"""
+
+from macaw_adapters.mcp import SecureMCP, Context
+
+mcp = SecureMCP("calculator")
+
+
+@mcp.tool(description="Add two numbers")
+def add(a: float, b: float) -> float:
+    return a + b
+
+
+@mcp.tool(description="Subtract two numbers")
+def subtract(a: float, b: float) -> float:
+    return a - b
+
+
+@mcp.tool(description="Multiply two numbers")
+def multiply(a: float, b: float) -> float:
+    return a * b
+
+
+@mcp.tool(description="Divide two numbers")
+def divide(a: float, b: float) -> float:
+    if b == 0:
+        return float('inf')
+    return a / b
+
+
+@mcp.tool(description="Calculate with history tracking")
+def calculate(ctx: Context, op: str, a: float, b: float) -> dict:
+    """Perform calculation and track in history."""
+    ops = {
+        "add": lambda x, y: x + y,
+        "subtract": lambda x, y: x - y,
+        "multiply": lambda x, y: x * y,
+        "divide": lambda x, y: x / y if y != 0 else float('inf')
+    }
+
+    if op not in ops:
+        return {"error": f"Unknown operation: {op}"}
+
+    result = ops[op](a, b)
+
+    # Track in context vault
+    history = ctx.get("calc_history") or []
+    history.append({"op": op, "a": a, "b": b, "result": result})
+    ctx.set("calc_history", history)
+
+    return {"result": result, "history_count": len(history)}
+
+
+@mcp.resource("calc://history")
+def get_history(ctx: Context) -> dict:
+    """Get calculation history from context vault."""
+    history = ctx.get("calc_history") or []
+    return {"history": history, "count": len(history)}
+
+
+if __name__ == "__main__":
+    print("=" * 50)
+    print("SecureMCP Calculator Server")
+    print("=" * 50)
+    print()
+    print("Tools: add, subtract, multiply, divide, calculate")
+    print("Resources: calc://history")
+    print()
+    print("Press Ctrl+C to stop")
+    print("=" * 50)
+    mcp.run()

package/payload/secureAI/examples/openai/openai_1a_dropin_simple.py

@@ -0,0 +1,102 @@
+#!/usr/bin/env python3
+"""
+openai_1a_dropin_simple.py - Drop-in replacement for OpenAI client
+
+The simplest integration path - just replace your import and it works.
+No Identity Provider needed.
+
+Prerequisites:
+    - MACAW SDK installed (pip install macaw-client macaw-adapters)
+    - OPENAI_API_KEY environment variable
+
+Run:
+    export OPENAI_API_KEY=sk-...
+    python openai_1a_dropin_simple.py
+"""
+
+import os
+import sys
+
+# BEFORE: from openai import OpenAI
+# AFTER:
+from macaw_adapters.openai import SecureOpenAI
+
+def main():
+    # Check for API key
+    if not os.environ.get("OPENAI_API_KEY"):
+        print("Set OPENAI_API_KEY environment variable")
+        print("  export OPENAI_API_KEY=sk-...")
+        return
+
+    print("=" * 60)
+    print("Example 1a: Drop-in Replacement (OpenAI)")
+    print("=" * 60)
+    print("\nPath: Direct on service (simplest)")
+    print("Use when: Single app, no user distinction, app-level policies")
+
+    # Create SecureOpenAI - just like regular OpenAI client
+    # Add intent_policy to restrict to GPT-3.5 only (no GPT-4)
+    client = SecureOpenAI(
+        app_name="my-simple-app",
+        intent_policy={
+            "constraints": {
+                "parameters": {
+                    "tool:*/generate": {
+                        "model": ["gpt-3.5-turbo"],  # Only GPT-3.5 allowed
+                        "max_tokens": {"max": 200}
+                    }
+                }
+            }
+        }
+    )
+
+    print(f"\nService registered: {client.server_id}")
+    print(f"Mode: {client._mode}")
+    print("Policy: GPT-3.5 only, max 200 tokens")
+
+    # Same API as OpenAI - no changes needed
+    print("\n--- Test 1: Allowed model (gpt-3.5-turbo) ---")
+    response = client.chat.completions.create(
+        model="gpt-3.5-turbo",
+        max_tokens=100,
+        messages=[
+            {"role": "user", "content": "What is compound interest? Answer briefly."}
+        ]
+    )
+
+    print(f"Model: {response.model}")
+    print(f"Response: {response.choices[0].message.content}")
+
+    # Policy enforcement - try a blocked model
+    print("\n--- Test 2: Blocked model (gpt-4) ---")
+    try:
+        response = client.chat.completions.create(
+            model="gpt-4",  # NOT in allowed list!
+            max_tokens=100,
+            messages=[
+                {"role": "user", "content": "What is compound interest?"}
+            ]
+        )
+        print(f"Unexpected success - should have been blocked!")
+        print(f"Response: {response.choices[0].message.content[:100]}...")
+    except Exception as e:
+        print(f"Correctly blocked: {e}")
+
+    print("\n" + "=" * 60)
+    print("Example complete!")
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except Exception as e:
+        err = str(e)
+        print("\n" + "=" * 60)
+        if "OPENAI_API_KEY" in err or "api_key" in err.lower():
+            print("ERROR: OpenAI API key not configured")
+            print("Fix: export OPENAI_API_KEY=sk-...")
+        else:
+            print(f"ERROR: {e}")
+        print("=" * 60)
+        sys.exit(1)

package/payload/secureAI/examples/openai/openai_1b_multiuser_bind.py

@@ -0,0 +1,193 @@
+#!/usr/bin/env python3
+"""
+openai_1b_multiuser_bind.py - Multi-user OpenAI with bind_to_user
+
+Each user's JWT identity flows through for policy evaluation.
+Different users get different permissions based on their policies.
+
+Prerequisites:
+    - MACAW SDK installed (pip install macaw-client macaw-adapters)
+    - OPENAI_API_KEY environment variable
+    - Identity Provider configured (Console -> Settings -> Identity Bridge)
+    - Test users: alice/Alice123!, bob/Bob@123!
+
+Run:
+    export OPENAI_API_KEY=sk-...
+    python openai_1b_multiuser_bind.py
+
+No IdP configured? Run simpler example first:
+    python openai_1a_dropin_simple.py
+"""
+
+import os
+import sys
+
+from macaw_adapters.openai import SecureOpenAI
+from macaw_client import MACAWClient, RemoteIdentityProvider
+
+
+# Test configurations based on user policies
+# Alice: GPT-3.5 only, max 500 tokens
+# Bob: GPT-3.5/4, max 2000 tokens
+USER_TESTS = {
+    "alice": {
+        "password": "Alice123!",
+        "policy_desc": "GPT-3.5 only, max 500 tokens",
+        "tests": [
+            # (model, max_tokens, should_succeed)
+            ("gpt-3.5-turbo", 400, True),   # ALLOWED - correct model, within limit
+            ("gpt-4", 400, False),           # BLOCKED - alice can't use GPT-4
+            ("gpt-3.5-turbo", 600, False),   # BLOCKED - exceeds max_tokens
+        ]
+    },
+    "bob": {
+        "password": "Bob@123!",
+        "policy_desc": "GPT-3.5/4, max 2000 tokens",
+        "tests": [
+            ("gpt-3.5-turbo", 400, True),   # ALLOWED
+            ("gpt-4", 400, True),            # ALLOWED - bob CAN use GPT-4
+            ("gpt-3.5-turbo", 600, True),   # ALLOWED - within bob's 2000 limit
+            ("gpt-4", 2500, False),          # BLOCKED - exceeds max_tokens
+        ]
+    }
+}
+
+
+def create_user_client(username: str, password: str) -> MACAWClient:
+    """Create authenticated user client."""
+    print(f"  Authenticating {username}...")
+    jwt_token, _ = RemoteIdentityProvider().login(username, password)
+
+    user = MACAWClient(
+        user_name=username,
+        iam_token=jwt_token,
+        agent_type="user",
+        app_name="financial-app"
+    )
+
+    if not user.register():
+        raise RuntimeError(f"Failed to register user {username}")
+
+    print(f"  User agent: {user.agent_id}")
+    return user
+
+
+def test_user(username: str, openai_service: SecureOpenAI):
+    """Test a user with bind_to_user pattern."""
+    config = USER_TESTS[username]
+
+    print(f"\n{'=' * 60}")
+    print(f"Testing {username.upper()} via bind_to_user")
+    print(f"Policy: {config['policy_desc']}")
+    print("=" * 60)
+
+    # 1. Create user client with JWT
+    user_client = create_user_client(username, config["password"])
+
+    # 2. Bind user to service
+    print(f"\n  Binding to service: {openai_service.server_id}")
+    user_openai = openai_service.bind_to_user(user_client)
+
+    # 3. Test with different parameters
+    print(f"\n  Running tests:")
+    for model, max_tokens, should_succeed in config["tests"]:
+        expected = "SHOULD SUCCEED" if should_succeed else "SHOULD BE BLOCKED"
+        print(f"\n  -> {model}, {max_tokens} tokens ({expected})")
+
+        try:
+            response = user_openai.chat.completions.create(
+                model=model,
+                max_tokens=max_tokens,
+                messages=[
+                    {"role": "system", "content": "You are a financial analyst."},
+                    {"role": "user", "content": "What is revenue growth? Brief answer."}
+                ]
+            )
+
+            if should_succeed:
+                print(f"     SUCCESS (as expected)")
+                # Non-streaming: response is a ChatCompletion object
+                content = response.choices[0].message.content
+                print(f"     Model: {response.model}")
+                print(f"     Response: {content[:60]}...")
+            else:
+                print(f"     UNEXPECTED SUCCESS - should have been blocked!")
+
+        except Exception as e:
+            error = str(e)
+            is_policy_block = any(word in error.lower() for word in
+                                  ["not in allowed", "not permitted", "policy",
+                                   "max_tokens", "model", "blocked", "denied"])
+            if is_policy_block:
+                if should_succeed:
+                    print(f"     UNEXPECTED BLOCK: {error[:60]}...")
+                else:
+                    print(f"     CORRECTLY BLOCKED by policy")
+            else:
+                print(f"     ERROR: {error[:60]}...")
+
+    # 4. Cleanup
+    print(f"\n  Unbinding user...")
+    user_openai.unbind()
+    print(f"  is_bound: {user_openai.is_bound}")
+
+
+def main():
+    # Check for API key
+    if not os.environ.get("OPENAI_API_KEY"):
+        print("Set OPENAI_API_KEY environment variable")
+        print("  export OPENAI_API_KEY=sk-...")
+        return
+
+    print("=" * 60)
+    print("Example 1b: Multi-user with bind_to_user (OpenAI)")
+    print("=" * 60)
+    print("\nPath: bind_to_user (per-user identity)")
+    print("Use when: SaaS app, different users need different permissions")
+    print("\nArchitecture:")
+    print("  - Single SecureOpenAI service (shared)")
+    print("  - Per-user MACAWClient with JWT identity")
+    print("  - bind_to_user() connects user to service")
+    print("  - User's identity flows through for policy evaluation")
+
+    # Create SINGLE service (shared across all users)
+    print("\n--- Creating SecureOpenAI service ---")
+    openai_service = SecureOpenAI(app_name="openai-service")
+    print(f"Service registered: {openai_service.server_id}")
+    print(f"Mode: {openai_service._mode}")
+
+    # Test alice (restricted)
+    try:
+        test_user("alice", openai_service)
+    except Exception as e:
+        print(f"\nFailed to test alice: {e}")
+
+    # Test bob (enhanced)
+    try:
+        test_user("bob", openai_service)
+    except Exception as e:
+        print(f"\nFailed to test bob: {e}")
+
+    print("\n" + "=" * 60)
+    print("Example complete!")
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except Exception as e:
+        err = str(e)
+        print("\n" + "=" * 60)
+        if "OPENAI_API_KEY" in err or "api_key" in err.lower():
+            print("ERROR: OpenAI API key not configured")
+            print("Fix: export OPENAI_API_KEY=sk-...")
+        elif "Local provider does not support" in err:
+            print("ERROR: Identity Provider not configured")
+            print("Fix: Console -> Settings -> Identity Bridge")
+            print("\nOr run simpler example first:")
+            print("  python openai_1a_dropin_simple.py")
+        else:
+            print(f"ERROR: {e}")
+        print("=" * 60)
+        sys.exit(1)