@macaw-ai/client 0.0.0-stage → 0.9.11

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

@@ -0,0 +1,299 @@
+#!/usr/bin/env python3
+"""
+Example: SecureMCPProxy with Databricks MCP Server
+
+Connect to Databricks MCP servers with MACAW security for:
+- Vector Search (RAG queries)
+- Genie Space (natural language data analysis)
+- SQL execution
+- Unity Catalog functions
+
+Databricks MCP Options:
+1. Databricks Managed MCP Servers - HTTP-based, Unity Catalog integrated
+2. Community server (databricks-mcp-server PyPI) - stdio-based
+
+This example focuses on Databricks Managed MCP Servers (HTTP).
+
+Prerequisites:
+1. Databricks workspace (community edition is free)
+2. MCP servers enabled in workspace
+3. MACAW LocalAgent running
+4. Install: pip install macaw-adapters[mcp-proxy]
+
+References:
+- Managed MCP: https://docs.databricks.com/aws/en/generative-ai/mcp/managed-mcp
+- Unity Catalog: https://docs.databricks.com/en/data-governance/unity-catalog/
+
+Usage:
+    export DATABRICKS_HOST="https://your-workspace.databricks.com"
+    export DATABRICKS_TOKEN="dapi..."
+    python 2d_proxy_databricks.py
+"""
+
+import os
+import logging
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+
+def example_databricks_sql_proxy():
+    """
+    Connect to Databricks SQL MCP server through SecureMCPProxy.
+
+    Databricks Managed MCP servers use OAuth/PAT authentication
+    and expose SQL, Vector Search, Genie, and UC Functions.
+    """
+    from macaw_adapters.mcp import SecureMCPProxy
+
+    # Databricks workspace URL and token
+    workspace_host = os.environ.get(
+        "DATABRICKS_HOST",
+        "https://your-workspace.databricks.com"
+    )
+    token = os.environ.get("DATABRICKS_TOKEN", "")
+
+    # Databricks SQL MCP endpoint
+    # Pattern: https://<workspace>/api/2.0/mcp/sql
+    sql_mcp_url = f"{workspace_host}/api/2.0/mcp/sql"
+
+    # Create proxy with Databricks PAT authentication
+    proxy = SecureMCPProxy(
+        app_name="databricks-sql",
+        upstream_url=sql_mcp_url,
+        upstream_auth={
+            "type": "bearer",
+            "token": token
+        }
+    )
+
+    print(f"\n{proxy}")
+
+    # List discovered tools
+    print("\nDiscovered Databricks SQL tools:")
+    for tool in proxy.list_tools():
+        print(f"  - {tool['name']}: {tool.get('description', '')[:60]}...")
+
+    # Example: Execute SQL query
+    try:
+        result = proxy.call_tool("execute_sql", {
+            "query": "SELECT current_user(), current_catalog(), current_schema()"
+        })
+        print(f"\nSQL result: {result}")
+    except ValueError as e:
+        print(f"\nSQL tool not available: {e}")
+    except Exception as e:
+        print(f"\nSQL error: {e}")
+
+
+def example_databricks_vector_search():
+    """
+    Connect to Databricks Vector Search MCP server.
+
+    Use case: RAG applications querying indexed documents.
+    """
+    from macaw_adapters.mcp import SecureMCPProxy
+
+    workspace_host = os.environ.get("DATABRICKS_HOST", "https://your-workspace.databricks.com")
+    token = os.environ.get("DATABRICKS_TOKEN", "")
+
+    # Vector Search MCP endpoint
+    # Pattern: https://<workspace>/api/2.0/mcp/vector-search/{catalog}/{schema}/{index}
+    catalog = os.environ.get("DATABRICKS_CATALOG", "main")
+    schema = os.environ.get("DATABRICKS_SCHEMA", "default")
+    index_name = os.environ.get("DATABRICKS_VS_INDEX", "documents_index")
+
+    vs_mcp_url = f"{workspace_host}/api/2.0/mcp/vector-search/{catalog}/{schema}/{index_name}"
+
+    proxy = SecureMCPProxy(
+        app_name="databricks-vector-search",
+        upstream_url=vs_mcp_url,
+        upstream_auth={"type": "bearer", "token": token}
+    )
+
+    print(f"\n{proxy}")
+
+    # Example: Search documents
+    try:
+        result = proxy.call_tool("search", {
+            "query": "How do I configure Unity Catalog?",
+            "num_results": 5
+        })
+        print(f"\nVector search result: {result}")
+    except ValueError as e:
+        print(f"\nSearch tool not available: {e}")
+    except Exception as e:
+        print(f"\nSearch error: {e}")
+
+
+def example_databricks_genie():
+    """
+    Connect to Databricks Genie Space MCP server.
+
+    Use case: Natural language queries over structured data.
+    """
+    from macaw_adapters.mcp import SecureMCPProxy
+
+    workspace_host = os.environ.get("DATABRICKS_HOST", "https://your-workspace.databricks.com")
+    token = os.environ.get("DATABRICKS_TOKEN", "")
+
+    # Genie Space MCP endpoint
+    # Pattern: https://<workspace>/api/2.0/mcp/genie/{genie_space_id}
+    genie_space_id = os.environ.get("DATABRICKS_GENIE_SPACE", "your-genie-space-id")
+
+    genie_mcp_url = f"{workspace_host}/api/2.0/mcp/genie/{genie_space_id}"
+
+    proxy = SecureMCPProxy(
+        app_name="databricks-genie",
+        upstream_url=genie_mcp_url,
+        upstream_auth={"type": "bearer", "token": token}
+    )
+
+    print(f"\n{proxy}")
+
+    # Example: Ask Genie a question
+    try:
+        result = proxy.call_tool("ask", {
+            "question": "What were the top 5 products by revenue last quarter?"
+        })
+        print(f"\nGenie result: {result}")
+    except ValueError as e:
+        print(f"\nGenie tool not available: {e}")
+    except Exception as e:
+        print(f"\nGenie error: {e}")
+
+
+def example_databricks_multi_user():
+    """
+    Multi-user pattern: data analysts with different Unity Catalog permissions.
+
+    Use case: Data platform where teams have different catalog access.
+    """
+    from macaw_adapters.mcp import SecureMCPProxy
+    from macaw_client import MACAWClient
+
+    workspace_host = os.environ.get("DATABRICKS_HOST", "https://your-workspace.databricks.com")
+    token = os.environ.get("DATABRICKS_TOKEN", "")
+
+    # Service creates shared proxy
+    proxy = SecureMCPProxy(
+        app_name="databricks-data-platform",
+        upstream_url=f"{workspace_host}/api/2.0/mcp/sql",
+        upstream_auth={"type": "bearer", "token": token}
+    )
+
+    # Data Engineer - full access
+    engineer = MACAWClient(
+        user_name="data-engineer-sam",
+        jwt_token=os.environ.get("SAM_JWT", "sam-jwt"),
+        agent_type="user"
+    )
+    engineer.register()
+    engineer_proxy = proxy.bind_to_user(engineer)
+
+    # Analyst - read-only access
+    analyst = MACAWClient(
+        user_name="analyst-kim",
+        jwt_token=os.environ.get("KIM_JWT", "kim-jwt"),
+        agent_type="user"
+    )
+    analyst.register()
+    analyst_proxy = proxy.bind_to_user(analyst)
+
+    print("\nMulti-user Databricks access:")
+    print(f"  Engineer (Sam): {engineer_proxy}")
+    print(f"  Analyst (Kim): {analyst_proxy}")
+
+    # Sam can create tables
+    try:
+        result = engineer_proxy.call_tool("execute_sql", {
+            "statement": "CREATE TABLE IF NOT EXISTS analytics.metrics (id INT, value DOUBLE)"
+        })
+        print(f"\nSam's CREATE result: {result}")
+    except PermissionError as e:
+        print(f"\nSam denied: {e}")
+    except Exception as e:
+        print(f"\nSam error: {e}")
+
+    # Kim can only query
+    try:
+        result = analyst_proxy.call_tool("execute_sql", {
+            "statement": "SELECT * FROM analytics.metrics LIMIT 10"
+        })
+        print(f"\nKim's SELECT result: {result}")
+    except PermissionError as e:
+        print(f"\nKim denied: {e}")
+    except Exception as e:
+        print(f"\nKim error: {e}")
+
+
+def setup_instructions():
+    """Print setup instructions for Databricks MCP."""
+    print("""
+================================================================================
+Databricks Managed MCP Server Setup
+================================================================================
+
+1. Get Databricks workspace:
+   - Enterprise: Contact Databricks
+   - Community Edition (free): https://community.cloud.databricks.com
+
+2. Enable MCP in your workspace:
+   - Go to: Workspace > Agents > MCP Servers
+   - View available MCP endpoints
+
+3. Create Personal Access Token (PAT):
+   - User Settings > Developer > Access Tokens
+   - Generate new token with appropriate permissions
+
+4. Set environment variables:
+   export DATABRICKS_HOST="https://your-workspace.databricks.com"
+   export DATABRICKS_TOKEN="dapi..."
+
+5. MCP Endpoint Patterns:
+   - SQL: {host}/api/2.0/mcp/sql
+   - Vector Search: {host}/api/2.0/mcp/vector-search/{catalog}/{schema}/{index}
+   - Genie: {host}/api/2.0/mcp/genie/{genie_space_id}
+   - UC Functions: {host}/api/2.0/mcp/functions/{catalog}/{schema}/{function}
+
+6. Run this example:
+   python 2d_proxy_databricks.py
+
+
+ALTERNATIVE: Community MCP Server (stdio-based)
+-----------------------------------------------
+
+For local development with stdio transport:
+
+1. Install: pip install databricks-mcp-server
+2. Run: uvx databricks-mcp-server@latest
+
+Note: stdio servers require an HTTP bridge (mcp-proxy) for SecureMCPProxy.
+
+================================================================================
+""")
+
+
+if __name__ == "__main__":
+    print("=" * 60)
+    print("SecureMCPProxy + Databricks MCP Server")
+    print("=" * 60)
+
+    setup_instructions()
+
+    print("\n--- Example: Databricks SQL Proxy ---")
+    try:
+        example_databricks_sql_proxy()
+    except ConnectionError as e:
+        print(f"\nConnection failed: {e}")
+        print("Make sure Databricks workspace is accessible and MCP is enabled.")
+
+    # Uncomment to test other examples:
+    # print("\n--- Example: Vector Search ---")
+    # example_databricks_vector_search()
+
+    # print("\n--- Example: Genie Space ---")
+    # example_databricks_genie()
+
+    # print("\n--- Example: Multi-User Access ---")
+    # example_databricks_multi_user()

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

@@ -0,0 +1,91 @@
+#!/usr/bin/env python3
+"""
+Example: SecureMCPProxy with mcp-server-fetch (stdio transport)
+
+Demonstrates SecureMCPProxy connecting to a standard MCP server via stdio.
+This validates the stdio transport with a simple, credential-free MCP server.
+
+Security Model:
+- MACAW creates AuthenticatedContext for EACH invocation
+- Even with persistent subprocess, each call gets fresh identity/policy/signature
+- Solves the "shared context" problem in standard MCP
+
+Prerequisites:
+    pip install mcp-server-fetch
+    pip install macaw-adapters[mcp-proxy]
+
+Usage:
+    python 2e_proxy_stdio_fetch.py
+"""
+
+import sys
+import logging
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+
+def main():
+    """Test SecureMCPProxy with mcp-server-fetch."""
+    from macaw_adapters.mcp import SecureMCPProxy
+
+    print("=" * 60)
+    print("SecureMCPProxy + mcp-server-fetch (stdio)")
+    print("=" * 60)
+
+    # Step 1: Check mcp-server-fetch is installed
+    print("\n1. Checking mcp-server-fetch installation...")
+    try:
+        import mcp_server_fetch
+        print("   OK: mcp-server-fetch is installed")
+    except ImportError:
+        print("   ERROR: mcp-server-fetch not installed")
+        print("   Fix: pip install mcp-server-fetch")
+        return 1
+
+    # Step 2: Create proxy with stdio transport
+    print("\n2. Creating SecureMCPProxy with stdio transport...")
+    try:
+        proxy = SecureMCPProxy(
+            app_name="fetch-stdio-test",
+            command=["python", "-m", "mcp_server_fetch"],
+        )
+        print(f"   OK: {proxy}")
+    except Exception as e:
+        print(f"   ERROR: {e}")
+        return 1
+
+    # Step 3: Discover tools
+    print("\n3. Discovering tools...")
+    tools = proxy.list_tools()
+    print(f"   Found {len(tools)} tools:")
+    for tool in tools:
+        desc = tool.get('description', '')[:50]
+        print(f"   - {tool['name']}: {desc}...")
+
+    if not tools:
+        print("   ERROR: No tools discovered")
+        return 1
+
+    # Step 4: Call fetch tool
+    print("\n4. Calling fetch tool (https://httpbin.org/html)...")
+    try:
+        result = proxy.call_tool("fetch", {"url": "https://httpbin.org/html"})
+        if result:
+            content = result.get('result', result) if isinstance(result, dict) else result
+            preview = str(content)[:200].replace('\n', ' ')
+            print(f"   OK: {preview}...")
+        else:
+            print("   OK: (empty result)")
+    except Exception as e:
+        print(f"   ERROR: {e}")
+        return 1
+
+    print("\n" + "=" * 60)
+    print("SUCCESS: SecureMCPProxy stdio transport works!")
+    print("=" * 60)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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

@@ -0,0 +1,119 @@
+#!/usr/bin/env python3
+"""
+Example: SecureMCPProxy with Salesforce DX MCP (stdio transport)
+
+Demonstrates SecureMCPProxy connecting to Salesforce DX CLI via stdio.
+Salesforce DX MCP provides tools for org management, deployment, and queries.
+
+Security Model:
+- MACAW creates AuthenticatedContext for EACH invocation
+- Even with persistent subprocess, each call gets fresh identity/policy/signature
+- Salesforce operations are policy-enforced and audited
+
+Prerequisites:
+    1. Salesforce account (free Developer Edition: https://developer.salesforce.com/signup)
+    2. Salesforce CLI: npm install -g @salesforce/cli
+    3. Authenticated org: sf org login web
+    4. MACAW: pip install macaw-adapters[mcp-proxy]
+
+NOTE: This example requires a Salesforce account. Skip if you don't have one -
+      the stdio pattern is validated by 2e_proxy_stdio_fetch.py.
+
+Usage:
+    python 2f_proxy_stdio_salesforce.py
+"""
+
+import os
+import sys
+import shutil
+import logging
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+
+def main():
+    """Test SecureMCPProxy with Salesforce DX MCP."""
+    from macaw_adapters.mcp import SecureMCPProxy
+
+    print("=" * 60)
+    print("SecureMCPProxy + Salesforce DX MCP (stdio)")
+    print("=" * 60)
+
+    # Step 1: Check npx is available
+    print("\n1. Checking prerequisites...")
+    if not shutil.which("npx"):
+        print("   ERROR: npx not found")
+        print("   Fix: Install Node.js (https://nodejs.org)")
+        return 1
+    print("   OK: npx found")
+
+    # Check if sf CLI is available
+    if not shutil.which("sf"):
+        print("   WARNING: sf CLI not found")
+        print("   You may need to install: npm install -g @salesforce/cli")
+
+    # Step 2: Create proxy with stdio transport
+    print("\n2. Creating SecureMCPProxy with Salesforce DX...")
+    try:
+        proxy = SecureMCPProxy(
+            app_name="salesforce-dx",
+            command=["npx", "@salesforce/mcp", "--orgs", "DEFAULT", "--dynamic-tools"],
+            env={
+                "HOME": os.environ.get("HOME", ""),
+                "PATH": os.environ.get("PATH", ""),
+            }
+        )
+        print(f"   OK: {proxy}")
+    except ConnectionError as e:
+        print(f"   ERROR: Failed to connect: {e}")
+        print("\n   Troubleshooting:")
+        print("   1. Install @salesforce/mcp: npm install -g @salesforce/mcp")
+        print("   2. Login to an org: sf org login web")
+        print("   3. Set default org: sf config set target-org=<alias>")
+        return 1
+    except Exception as e:
+        print(f"   ERROR: {e}")
+        return 1
+
+    # Step 3: Discover tools
+    print("\n3. Discovering Salesforce DX tools...")
+    tools = proxy.list_tools()
+    print(f"   Found {len(tools)} tools:")
+    for tool in tools[:10]:  # Show first 10
+        print(f"   - {tool['name']}")
+    if len(tools) > 10:
+        print(f"   ... and {len(tools) - 10} more")
+
+    if not tools:
+        print("   ERROR: No tools discovered")
+        return 1
+
+    # Step 4: Test tool calls
+    print("\n4. Testing tool calls...")
+
+    # Get current username (requires directory - use current dir)
+    try:
+        result = proxy.call_tool("get_username", {"directory": os.getcwd()})
+        content = result.get('result', result) if isinstance(result, dict) else result
+        print(f"   get_username: {content}")
+    except Exception as e:
+        print(f"   get_username error: {e}")
+
+    # List available tools (dynamic)
+    try:
+        result = proxy.call_tool("list_tools", {})
+        content = result.get('result', result) if isinstance(result, dict) else result
+        preview = str(content)[:300] if content else "(empty)"
+        print(f"   list_tools: {preview}...")
+    except Exception as e:
+        print(f"   list_tools error: {e}")
+
+    print("\n" + "=" * 60)
+    print("SUCCESS: SecureMCPProxy + Salesforce DX works!")
+    print("=" * 60)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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

@@ -0,0 +1,136 @@
+#!/usr/bin/env python3
+"""
+Example: SecureMCPProxy Multi-User Pattern
+
+Demonstrates bind_to_user() for multi-tenant SaaS applications.
+The service maintains the upstream MCP connection, but each request
+runs with a specific user's identity and policy.
+
+Security Model:
+- Service creates ONE proxy to the upstream MCP server
+- Each user gets a BoundMCPProxy via bind_to_user()
+- User's calls are: evaluated against their policy, signed with their identity, logged under their audit trail
+- Even with shared subprocess, MACAW provides per-user isolation
+
+Prerequisites:
+    1. pip install mcp-server-fetch macaw-adapters[mcp-proxy]
+    2. Identity Provider configured (Console -> Settings -> Identity Bridge)
+    3. Test users: alice/Alice123!, bob/Bob@123!
+
+Usage:
+    python 2g_proxy_multiuser.py
+
+No IdP configured? Use simpler examples first:
+    python 2e_proxy_stdio_fetch.py
+"""
+
+import os
+import sys
+import logging
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+
+def main():
+    """Test multi-user SecureMCPProxy pattern."""
+    from macaw_adapters.mcp import SecureMCPProxy
+    from macaw_client import MACAWClient, RemoteIdentityProvider
+
+    print("=" * 60)
+    print("SecureMCPProxy Multi-User Pattern")
+    print("=" * 60)
+
+    # Step 1: Service creates shared proxy
+    print("\n1. Creating shared proxy (service-level)...")
+    try:
+        import mcp_server_fetch
+    except ImportError:
+        print("   ERROR: mcp-server-fetch not installed")
+        print("   Fix: pip install mcp-server-fetch")
+        return 1
+
+    try:
+        proxy = SecureMCPProxy(
+            app_name="shared-fetch-proxy",
+            command=["python", "-m", "mcp_server_fetch"],
+        )
+        print(f"   OK: {proxy}")
+    except Exception as e:
+        print(f"   ERROR: {e}")
+        return 1
+
+    # Step 2: Authenticate users
+    print("\n2. Authenticating users...")
+
+    users = {}
+    for username, password in [("alice", "Alice123!"), ("bob", "Bob@123!")]:
+        try:
+            print(f"   Authenticating {username}...")
+            jwt_token, _ = RemoteIdentityProvider().login(username, password)
+
+            user = MACAWClient(
+                user_name=username,
+                iam_token=jwt_token,
+                agent_type="user",
+                app_name="mcp-multiuser-test"
+            )
+
+            if not user.register():
+                print(f"   ERROR: Failed to register {username}")
+                continue
+
+            users[username] = user
+            print(f"   OK: {username} -> {user.agent_id}")
+
+        except Exception as e:
+            print(f"   ERROR: {username} authentication failed: {e}")
+            print("   Make sure IdP is configured in Console -> Settings -> Identity Bridge")
+            return 1
+
+    if len(users) < 2:
+        print("\n   ERROR: Could not authenticate both users")
+        return 1
+
+    # Step 3: Create per-user bound proxies
+    print("\n3. Creating per-user proxies via bind_to_user()...")
+    alice_proxy = proxy.bind_to_user(users["alice"])
+    bob_proxy = proxy.bind_to_user(users["bob"])
+    print(f"   Alice: {alice_proxy}")
+    print(f"   Bob: {bob_proxy}")
+
+    # Step 4: Test user-specific calls
+    print("\n4. Testing user-specific tool calls...")
+
+    test_urls = [
+        ("alice", alice_proxy, "https://alice.example.com"),
+        ("bob", bob_proxy, "https://bob.example.com"),
+    ]
+
+    for username, user_proxy, url in test_urls:
+        print(f"\n   {username.upper()}'s call to {url}:")
+        try:
+            result = user_proxy.call_tool("fetch", {"url": url})
+            preview = str(result)[:80].replace('\n', ' ')
+            print(f"   OK: {preview}...")
+            print(f"   (Policy: {username}'s policy applied)")
+            print(f"   (Signed: {username}'s identity)")
+            print(f"   (Audit: logged under {username})")
+        except PermissionError as e:
+            print(f"   BLOCKED by policy: {e}")
+        except Exception as e:
+            print(f"   ERROR: {e}")
+
+    print("\n" + "=" * 60)
+    print("SUCCESS: Multi-user SecureMCPProxy works!")
+    print("=" * 60)
+    print("\nKey points:")
+    print("  - Same subprocess, different identities")
+    print("  - Each call has fresh AuthenticatedContext")
+    print("  - Policy enforcement per user")
+    print("  - Audit trail tracks who did what")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())