@macaw-ai/client 0.0.0-stage → 0.9.11

package/payload/secureAI/examples/mcp/1f_elicitation_client.py

@@ -0,0 +1,127 @@
+#!/usr/bin/env python3
+"""
+1f_elicitation_client.py - MCP Elicitation (Server->User Input)
+
+Demonstrates client.set_elicitation_handler() for server->user input.
+
+The client registers an input handler that prompts the user when
+the server's ctx.elicit() is called.
+
+NOTE: This example requires interactive user input and is not suitable
+for automated test harnesses.
+
+Prerequisites:
+    - MACAW SDK installed (pip install macaw-client macaw-adapters)
+    - Elicitation server running (1f_elicitation_server.py)
+
+Run:
+    # Terminal 1: Start the server
+    python 1f_elicitation_server.py
+
+    # Terminal 2: Run this client (interactive)
+    python 1f_elicitation_client.py
+"""
+
+from macaw_adapters.mcp import Client
+
+
+def find_elicitation_server(client):
+    """Find the most recent elicitation demo server."""
+    agents = client.macaw_client.list_agents(agent_type="app")
+    matching = [
+        a["agent_id"] for a in agents
+        if "elicitation-demo" in a.get("agent_id", "")
+        and "/tool." not in a.get("agent_id", "")
+    ]
+    return matching[0] if matching else None  # Return first (most recent)
+
+
+def main():
+    print("=" * 50)
+    print("Example 1f: Elicitation Demo Client")
+    print("=" * 50)
+
+    client = Client("elicitation-client")
+    print(f"Client: {client.client_id}")
+
+    # Register interactive input handler
+    def input_handler(prompt, options, input_type, default, required, **kwargs):
+        print()
+        if input_type == "confirm":
+            response = input(f"  {prompt} (y/n) [{default or 'n'}]: ").strip().lower()
+            if not response:
+                response = (default or "n").lower()
+            return response in ("y", "yes")
+
+        elif input_type == "select" and options:
+            print(f"  {prompt}")
+            for i, opt in enumerate(options):
+                print(f"    {i+1}. {opt}")
+            while True:
+                try:
+                    choice = input(f"  Enter number (1-{len(options)}): ").strip()
+                    idx = int(choice) - 1
+                    if 0 <= idx < len(options):
+                        return options[idx]
+                except ValueError:
+                    pass
+                print("  Invalid choice, try again")
+
+        else:  # text
+            response = input(f"  {prompt}: ").strip()
+            return response or default
+
+    client.set_elicitation_handler(input_handler)
+    print("Elicitation handler registered (interactive)")
+    print()
+
+    server = find_elicitation_server(client)
+    if not server:
+        print("\nNo elicitation-demo server found!")
+        print("Start it first: python3 1f_elicitation_server.py")
+        return
+
+    print(f"Server: {server}")
+    print()
+
+    # Test create_profile
+    print("Testing create_profile():")
+    print("-" * 40)
+    result = client.macaw_client.invoke_tool(
+        "create_profile",
+        {},
+        target_agent=server
+    )
+    print(f"\n  Result: {result}")
+    print()
+
+    # Test delete_item
+    print("Testing delete_item():")
+    print("-" * 40)
+    result = client.macaw_client.invoke_tool(
+        "delete_item",
+        {"item_name": "important_file.txt"},
+        target_agent=server
+    )
+    print(f"\n  Result: {result}")
+
+    print()
+    print("=" * 50)
+    print("Elicitation enables human-in-the-loop workflows")
+    print("=" * 50)
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except Exception as e:
+        err = str(e)
+        print("\n" + "=" * 50)
+        if "Connection refused" in err or "connect" in err.lower():
+            print("ERROR: Cannot connect to MACAW")
+            print("Fix: Ensure MACAW is running")
+        else:
+            print(f"ERROR: {e}")
+        print("=" * 50)
+        import sys
+        sys.exit(1)

package/payload/secureAI/examples/mcp/1f_elicitation_server.py

@@ -0,0 +1,73 @@
+#!/usr/bin/env python3
+"""
+Example 1f: MCP Elicitation - SERVER
+
+Demonstrates ctx.elicit() - server requesting user input from client.
+
+The server tools here use ctx.elicit() to interactively request
+information from the user during execution.
+
+Run this server, then run 1f_elicitation_client.py in another terminal.
+"""
+
+from macaw_adapters.mcp import SecureMCP, Context
+
+mcp = SecureMCP("elicitation-demo")
+
+
+@mcp.tool(description="Create user profile interactively")
+async def create_profile(ctx: Context) -> dict:
+    """Create a profile by asking the user questions."""
+    ctx.info("Starting profile creation")
+
+    name = await ctx.elicit(
+        prompt="What is your name?",
+        input_type="text",
+        required=True
+    )
+
+    role = await ctx.elicit(
+        prompt="What is your role?",
+        options=["Developer", "Designer", "Manager", "Other"],
+        input_type="select"
+    )
+
+    ctx.audit(action="profile_created", target="user_profile", outcome="success", name=name)
+
+    return {"name": name, "role": role, "status": "created"}
+
+
+@mcp.tool(description="Delete with confirmation")
+async def delete_item(ctx: Context, item_name: str) -> dict:
+    """Delete an item with user confirmation."""
+    ctx.info(f"Request to delete: {item_name}")
+
+    confirmed = await ctx.elicit(
+        prompt=f"Delete '{item_name}'? This cannot be undone.",
+        input_type="confirm",
+        default="no"
+    )
+
+    if confirmed:
+        ctx.audit(action="delete", target=item_name, outcome="success")
+        return {"deleted": item_name, "status": "deleted"}
+    else:
+        ctx.info("Deletion cancelled")
+        return {"deleted": None, "status": "cancelled"}
+
+
+if __name__ == "__main__":
+    print("=" * 50)
+    print("Example 1f: Elicitation Demo Server")
+    print("=" * 50)
+    print()
+    print("Tools: create_profile, delete_item")
+    print()
+    print("These tools use ctx.elicit() to request user input")
+    print("during execution (human-in-the-loop).")
+    print()
+    print("Run client: python3 1f_elicitation_client.py")
+    print()
+    print("Press Ctrl+C to stop")
+    print("=" * 50)
+    mcp.run()

package/payload/secureAI/examples/mcp/1g_roots_client.py

@@ -0,0 +1,122 @@
+#!/usr/bin/env python3
+"""
+1g_roots_client.py - MCP Roots via MAPL (Filesystem Boundaries)
+
+Tests root boundaries declared by the server.
+
+Demonstrates:
+- list_roots() to discover server's allowed paths
+- Access allowed within roots
+- Access denied outside roots
+
+Prerequisites:
+    - MACAW SDK installed (pip install macaw-client macaw-adapters)
+    - Roots server running (1g_roots_server.py)
+
+Run:
+    # Terminal 1: Start the server
+    python 1g_roots_server.py
+
+    # Terminal 2: Run this client
+    python 1g_roots_client.py
+"""
+
+import asyncio
+
+from macaw_adapters.mcp import Client
+
+DEMO_DIR = "/tmp/securemcp-roots-demo"
+
+
+def find_roots_server(client):
+    """Find the most recent roots demo server."""
+    agents = client.macaw_client.list_agents(agent_type="app")
+    matching = [
+        a["agent_id"] for a in agents
+        if "roots-demo" in a.get("agent_id", "")
+        and "/tool." not in a.get("agent_id", "")
+    ]
+    return matching[0] if matching else None  # Return first (most recent)
+
+
+def main():
+    print("=" * 50)
+    print("Example 1g: Roots Demo Client")
+    print("=" * 50)
+
+    client = Client("roots-client")
+    print(f"Client: {client.client_id}")
+
+    server = find_roots_server(client)
+    if not server:
+        print("\nNo roots-demo server found!")
+        print("Start it first: python3 1g_roots_server.py")
+        return
+
+    print(f"Server: {server}")
+    print()
+
+    # Discover roots
+    print("Discovering server roots (list_roots()):")
+    print("-" * 40)
+
+    async def show_roots():
+        roots = await client.list_roots(server_name="roots-demo")
+        for r in roots:
+            print(f"  - {r['path']}")
+        return roots
+
+    asyncio.run(show_roots())
+    print()
+
+    # Test ALLOWED access
+    print(f"Testing list_dir('{DEMO_DIR}') - ALLOWED:")
+    print("-" * 40)
+    result = client.macaw_client.invoke_tool("list_dir", {"path": DEMO_DIR}, target_agent=server)
+    print(f"  Result: {result}")
+    print()
+
+    print(f"Testing read_file('{DEMO_DIR}/allowed.txt') - ALLOWED:")
+    print("-" * 40)
+    result = client.macaw_client.invoke_tool("read_file", {"path": f"{DEMO_DIR}/allowed.txt"}, target_agent=server)
+    print(f"  Result: {result}")
+    print()
+
+    # Test DENIED access (should raise exception or return error)
+    print("Testing list_dir('/etc') - DENIED (outside roots):")
+    print("-" * 40)
+    try:
+        result = client.macaw_client.invoke_tool("list_dir", {"path": "/etc"}, target_agent=server)
+        print(f"  Result: {result}")
+    except Exception as e:
+        print(f"  ✓ Access denied (as expected): {e}")
+    print()
+
+    print("Testing read_file('/etc/passwd') - DENIED:")
+    print("-" * 40)
+    try:
+        result = client.macaw_client.invoke_tool("read_file", {"path": "/etc/passwd"}, target_agent=server)
+        print(f"  Result: {result}")
+    except Exception as e:
+        print(f"  ✓ Access denied (as expected): {e}")
+    print()
+
+    print("=" * 50)
+    print("Roots enforce filesystem boundaries via MAPL")
+    print("=" * 50)
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except Exception as e:
+        err = str(e)
+        print("\n" + "=" * 50)
+        if "Connection refused" in err or "connect" in err.lower():
+            print("ERROR: Cannot connect to MACAW")
+            print("Fix: Ensure MACAW is running")
+        else:
+            print(f"ERROR: {e}")
+        print("=" * 50)
+        import sys
+        sys.exit(1)

package/payload/secureAI/examples/mcp/1g_roots_server.py

@@ -0,0 +1,85 @@
+#!/usr/bin/env python3
+"""
+Example 1g: MCP Roots via MAPL - SERVER
+
+Demonstrates declaring filesystem roots that constrain server access.
+
+Roots are declared via SecureMCP(roots=[...]) and translated to
+MAPL resource policies. Tools use ctx.get_roots() to check boundaries.
+
+Run this server, then run 1g_roots_client.py in another terminal.
+"""
+
+import os
+from pathlib import Path
+
+from macaw_adapters.mcp import SecureMCP, Context
+
+# Setup test directory
+DEMO_DIR = "/tmp/securemcp-roots-demo"
+os.makedirs(DEMO_DIR, exist_ok=True)
+(Path(DEMO_DIR) / "allowed.txt").write_text("This file is in an allowed root.")
+
+# Create server with declared roots
+mcp = SecureMCP(
+    "roots-demo",
+    roots=[DEMO_DIR]  # Only this directory is accessible
+)
+
+
+@mcp.tool(description="List files in directory")
+def list_dir(ctx: Context, path: str) -> dict:
+    """List directory contents (respects root boundaries)."""
+    ctx.info(f"Listing: {path}")
+    roots = ctx.get_roots()
+    path = os.path.abspath(path)
+
+    # Check boundaries
+    if not any(path.startswith(os.path.abspath(r)) for r in roots):
+        ctx.warning(f"Access denied: {path}")
+        ctx.audit(action="list_dir", target=path, outcome="denied")
+        return {"error": "Access denied - outside roots", "allowed_roots": roots}
+
+    if os.path.exists(path):
+        entries = os.listdir(path)
+        ctx.audit(action="list_dir", target=path, outcome="success")
+        return {"path": path, "entries": entries}
+    return {"error": "Path not found"}
+
+
+@mcp.tool(description="Read a file")
+def read_file(ctx: Context, path: str) -> dict:
+    """Read file contents (respects root boundaries)."""
+    ctx.info(f"Reading: {path}")
+    roots = ctx.get_roots()
+    path = os.path.abspath(path)
+
+    if not any(path.startswith(os.path.abspath(r)) for r in roots):
+        ctx.audit(action="read_file", target=path, outcome="denied")
+        return {"error": "Access denied - outside roots"}
+
+    if os.path.isfile(path):
+        content = Path(path).read_text()
+        ctx.audit(action="read_file", target=path, outcome="success")
+        return {"path": path, "content": content}
+    return {"error": "File not found"}
+
+
+if __name__ == "__main__":
+    print("=" * 50)
+    print("Example 1g: Roots Demo Server")
+    print("=" * 50)
+    print()
+    print("Tools: list_dir, read_file")
+    print()
+    print("Declared Roots (via MAPL):")
+    for root in mcp.roots:
+        print(f"  - {root}")
+    print()
+    print(f"Test file: {DEMO_DIR}/allowed.txt")
+    print()
+    print("Run client: python3 1g_roots_client.py")
+    print()
+    print("Press Ctrl+C to stop")
+    print("=" * 50)
+    mcp.run()

package/payload/secureAI/examples/mcp/2a_proxy_snowflake.py

@@ -0,0 +1,212 @@
+#!/usr/bin/env python3
+"""
+Example: SecureMCPProxy with Snowflake MCP Server
+
+Connect to Snowflake's MCP server with MACAW security for:
+- Cortex AI (search, analyst, agent)
+- SQL execution
+- Object management
+- Semantic views
+
+Prerequisites:
+1. Snowflake account (free trial: https://signup.snowflake.com)
+2. Snowflake Labs MCP server running with HTTP transport:
+   uvx snowflake-labs-mcp --service-config-file config.yaml --transport streamable-http
+3. MACAW LocalAgent running
+4. Install: pip install macaw-adapters[mcp-proxy]
+
+Reference: https://github.com/Snowflake-Labs/mcp
+
+Usage:
+    # Set environment variables
+    export SNOWFLAKE_MCP_URL="http://localhost:9000/snowflake-mcp"
+    export SNOWFLAKE_ACCOUNT="your-account"
+
+    python 2b_proxy_snowflake.py
+"""
+
+import os
+import logging
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+
+def example_snowflake_proxy():
+    """
+    Connect to Snowflake MCP server through SecureMCPProxy.
+
+    Snowflake Labs MCP supports HTTP transport, making it compatible
+    with SecureMCPProxy's streamable_http_client.
+    """
+    from macaw_adapters.mcp import SecureMCPProxy
+
+    # Snowflake MCP server URL (running with --transport streamable-http)
+    upstream_url = os.environ.get(
+        "SNOWFLAKE_MCP_URL",
+        "http://localhost:9000/mcp"
+    )
+
+    # Create proxy - connects to Snowflake MCP, wraps with MACAW security
+    # Note: Snowflake auth is handled by the MCP server itself via env vars
+    # (SNOWFLAKE_USER, SNOWFLAKE_PASSWORD, SNOWFLAKE_ACCOUNT, etc.)
+    proxy = SecureMCPProxy(
+        app_name="snowflake-mcp",
+        upstream_url=upstream_url,
+        # No upstream_auth needed - Snowflake MCP server handles auth internally
+    )
+
+    print(f"\n{proxy}")
+
+    # List discovered tools from Snowflake
+    print("\nDiscovered Snowflake tools:")
+    for tool in proxy.list_tools():
+        print(f"  - {tool['name']}: {tool.get('description', '')[:60]}...")
+
+    # Example: Run SQL query
+    try:
+        result = proxy.call_tool("run_snowflake_query", {
+            "statement": "SELECT CURRENT_USER(), CURRENT_ROLE(), CURRENT_DATABASE()"
+        })
+        print(f"\nSQL result: {result}")
+    except ValueError as e:
+        print(f"\nSQL not available: {e}")
+    except Exception as e:
+        print(f"\nSQL error: {e}")
+
+    # Example: List databases
+    try:
+        result = proxy.call_tool("list_objects", {
+            "object_type": "database"
+        })
+        # Result is a dict with 'result' key
+        content = result.get('result', result) if isinstance(result, dict) else result
+        preview = str(content)[:300] if content else "(empty)"
+        print(f"\nList databases result: {preview}...")
+    except ValueError as e:
+        print(f"\nList objects not available: {e}")
+    except Exception as e:
+        print(f"\nList objects error: {e}")
+
+
+def example_snowflake_multi_user():
+    """
+    Multi-user pattern: different users query Snowflake with their own policies.
+
+    Use case: Data platform where analysts have different access levels.
+    """
+    from macaw_adapters.mcp import SecureMCPProxy
+    from macaw_client import MACAWClient
+
+    # Service creates shared proxy to Snowflake
+    proxy = SecureMCPProxy(
+        app_name="snowflake-data-platform",
+        upstream_url=os.environ.get("SNOWFLAKE_MCP_URL", "http://localhost:9000/snowflake-mcp"),
+    )
+
+    # Analyst Alice - has access to sales data
+    alice = MACAWClient(
+        user_name="alice",
+        jwt_token=os.environ.get("ALICE_JWT", "alice-jwt"),
+        agent_type="user"
+    )
+    alice.register()
+    alice_proxy = proxy.bind_to_user(alice)
+
+    # Analyst Bob - restricted to aggregate queries only
+    bob = MACAWClient(
+        user_name="bob",
+        jwt_token=os.environ.get("BOB_JWT", "bob-jwt"),
+        agent_type="user"
+    )
+    bob.register()
+    bob_proxy = proxy.bind_to_user(bob)
+
+    print("\nMulti-user Snowflake access:")
+    print(f"  Alice: {alice_proxy}")
+    print(f"  Bob: {bob_proxy}")
+
+    # Alice's query - MACAW policy checked against alice's permissions
+    try:
+        result = alice_proxy.call_tool("execute_sql", {
+            "statement": "SELECT * FROM sales.customers LIMIT 10"
+        })
+        print(f"\nAlice's query result: {result}")
+    except PermissionError as e:
+        print(f"\nAlice denied: {e}")
+    except Exception as e:
+        print(f"\nAlice error: {e}")
+
+    # Bob's query - MACAW policy checked against bob's permissions
+    try:
+        result = bob_proxy.call_tool("execute_sql", {
+            "statement": "SELECT COUNT(*) FROM sales.customers"
+        })
+        print(f"\nBob's query result: {result}")
+    except PermissionError as e:
+        print(f"\nBob denied: {e}")
+    except Exception as e:
+        print(f"\nBob error: {e}")
+
+
+def setup_instructions():
+    """Print setup instructions for Snowflake MCP server."""
+    print("""
+================================================================================
+Snowflake MCP Server Setup
+================================================================================
+
+1. Get Snowflake Account (free 30-day trial):
+   https://signup.snowflake.com
+
+2. Create config.yaml for Snowflake MCP:
+
+   # config.yaml
+   agent_services: []
+
+   other_services:
+     object_manager: true
+     query_manager: true
+     semantic_manager: true
+
+   sql_statement_permissions:
+     Select: true
+     Create: false
+     Drop: false
+
+3. Set Snowflake credentials:
+   export SNOWFLAKE_ACCOUNT="your-account"
+   export SNOWFLAKE_USER="your-user"
+   export SNOWFLAKE_PASSWORD="your-password"
+   export SNOWFLAKE_WAREHOUSE="COMPUTE_WH"
+   export SNOWFLAKE_DATABASE="your-db"
+   export SNOWFLAKE_SCHEMA="PUBLIC"
+
+4. Run Snowflake MCP server with HTTP transport:
+   uvx snowflake-labs-mcp --service-config-file config.yaml --transport streamable-http
+
+5. Run this example:
+   export SNOWFLAKE_MCP_URL="http://localhost:9000/mcp"
+   python 2b_proxy_snowflake.py
+
+================================================================================
+""")
+
+
+if __name__ == "__main__":
+    print("=" * 60)
+    print("SecureMCPProxy + Snowflake MCP Server")
+    print("=" * 60)
+
+    setup_instructions()
+
+    print("\n--- Example: Basic Snowflake Proxy ---")
+    try:
+        example_snowflake_proxy()
+    except ConnectionError as e:
+        print(f"\nConnection failed: {e}")
+        print("Make sure Snowflake MCP server is running with HTTP transport.")
+
+    # Uncomment to test multi-user:
+    # print("\n--- Example: Multi-User Snowflake Access ---")
+    # example_snowflake_multi_user()