@macaw-ai/client 0.0.0-stage → 0.9.11

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

@@ -0,0 +1,115 @@
+#!/usr/bin/env python3
+"""
+1a_simple_invocation.py - Simple MCP Tool Invocation
+
+Demonstrates:
+- Auto-discovering SecureMCP servers
+- Invoking tools on a server
+- Basic tool calls (add, subtract, multiply, divide)
+- Tool with context (calculate with history)
+
+Prerequisites:
+    - MACAW SDK installed (pip install macaw-client macaw-adapters)
+    - Calculator server running (securemcp_calculator.py)
+
+Run:
+    # Terminal 1: Start the server
+    python securemcp_calculator.py
+
+    # Terminal 2: Run this client
+    python 1a_simple_invocation.py
+"""
+
+from macaw_adapters.mcp import Client
+
+
+def find_calculator_server(client):
+    """Find the most recent securemcp-calculator server."""
+    agents = client.macaw_client.list_agents(agent_type="app")
+    # Match exactly "/app:securemcp-calculator:" to avoid stale registrations
+    calc_servers = [
+        a for a in agents
+        if "/app:securemcp-calculator:" in a.get("agent_id", "")
+        and "/tool." not in a.get("agent_id", "")
+    ]
+
+    if not calc_servers:
+        print("No calculator server found!")
+        print("\nStart the calculator server first:")
+        print("  python3 securemcp_calculator.py")
+        return None
+
+    return calc_servers[0]["agent_id"]
+
+
+def main():
+    print("=" * 50)
+    print("Example 1a: Simple Tool Invocation")
+    print("=" * 50)
+
+    # Create client (auto-registers with LocalAgent)
+    client = Client("example-1a")
+    print(f"Client: {client.client_id}")
+
+    # Find calculator server
+    server_id = find_calculator_server(client)
+    if not server_id:
+        return
+
+    print(f"Server: {server_id}")
+    print()
+
+    # Test basic tools
+    print("Basic Tool Invocations:")
+    print("-" * 40)
+
+    tests = [
+        ("add", {"a": 10, "b": 5}),
+        ("subtract", {"a": 100, "b": 42}),
+        ("multiply", {"a": 7, "b": 8}),
+        ("divide", {"a": 100, "b": 4}),
+    ]
+
+    for tool_name, args in tests:
+        result = client.macaw_client.invoke_tool(
+            tool_name,
+            args,
+            target_agent=server_id
+        )
+        args_str = ", ".join(f"{k}={v}" for k, v in args.items())
+        print(f"  {tool_name}({args_str}) = {result}")
+
+    print()
+
+    # Test tool with context
+    print("Tool with Context (history tracking):")
+    print("-" * 40)
+
+    for op in ["add", "multiply", "subtract"]:
+        result = client.macaw_client.invoke_tool(
+            "calculate",
+            {"operation": op, "a": 10, "b": 3},
+            target_agent=server_id
+        )
+        print(f"  calculate({op}, 10, 3) = {result}")
+
+    print()
+    print("=" * 50)
+    print("Done!")
+    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/1b_discovery_and_resources.py

@@ -0,0 +1,142 @@
+#!/usr/bin/env python3
+"""
+1b_discovery_and_resources.py - MCP Discovery and Resources
+
+Demonstrates:
+- list_tools() - discover available tools
+- list_resources() - discover available resources
+- list_prompts() - discover available prompts
+- get_resource() - read a resource
+- get_prompt() - get a prompt template
+- Filtering by server name
+
+Prerequisites:
+    - MACAW SDK installed (pip install macaw-client macaw-adapters)
+    - Calculator server running (securemcp_calculator.py)
+
+Run:
+    # Terminal 1: Start the server
+    python securemcp_calculator.py
+
+    # Terminal 2: Run this client
+    python 1b_discovery_and_resources.py
+"""
+
+import asyncio
+
+from macaw_adapters.mcp import Client
+
+
+def find_calculator_server(client):
+    """Find the most recent securemcp-calculator server."""
+    agents = client.macaw_client.list_agents(agent_type="app")
+    # Match exactly "/app:securemcp-calculator:" to avoid stale registrations
+    calc_servers = [
+        a for a in agents
+        if "/app:securemcp-calculator:" in a.get("agent_id", "")
+        and "/tool." not in a.get("agent_id", "")
+    ]
+
+    if not calc_servers:
+        print("No calculator server found!")
+        print("\nStart the calculator server first:")
+        print("  python3 securemcp_calculator.py")
+        return None
+
+    return calc_servers[0]["agent_id"]
+
+
+async def main():
+    print("=" * 50)
+    print("Example 1b: Discovery and Resources")
+    print("=" * 50)
+
+    # Create client
+    client = Client("example-1b")
+    print(f"Client: {client.client_id}")
+
+    # Find calculator server
+    server_id = find_calculator_server(client)
+    if not server_id:
+        return
+
+    print(f"Server: {server_id}")
+    print()
+
+    # Filter for calculator server only
+    server_filter = "securemcp-calculator"
+
+    # 1. Discover tools
+    print(f"list_tools('{server_filter}'):")
+    print("-" * 40)
+    tools = await client.list_tools(server_name=server_filter)
+    for t in tools:
+        print(f"  - {t['name']}")
+    print()
+
+    # 2. Discover resources
+    print(f"list_resources('{server_filter}'):")
+    print("-" * 40)
+    resources = await client.list_resources(server_name=server_filter)
+    for r in resources:
+        print(f"  - {r['uri']}")
+    print()
+
+    # 3. Discover prompts
+    print(f"list_prompts('{server_filter}'):")
+    print("-" * 40)
+    prompts = await client.list_prompts(server_name=server_filter)
+    for p in prompts:
+        print(f"  - {p['name']}")
+    print()
+
+    # Set default server for convenience
+    client.set_default_server(server_id)
+
+    # 4. Invoke a tool to create some history
+    print("Creating history with calculate():")
+    print("-" * 40)
+    for op, a, b in [("add", 5, 3), ("multiply", 4, 7)]:
+        result = client.macaw_client.invoke_tool(
+            "calculate",
+            {"operation": op, "a": a, "b": b},
+            target_agent=server_id
+        )
+        print(f"  calculate({op}, {a}, {b}) = {result['result']}")
+    print()
+
+    # 5. Read a resource
+    print("get_resource('calc://history'):")
+    print("-" * 40)
+    history = await client.get_resource("calc://history")
+    print(f"  History count: {history.get('count', 0)}")
+    for entry in history.get("history", [])[-3:]:  # Last 3 entries
+        print(f"    - {entry}")
+    print()
+
+    # 6. Get a prompt
+    print("get_prompt('calculation_prompt', {numbers: '1,2,3'}):")
+    print("-" * 40)
+    prompt = await client.get_prompt("calculation_prompt", {"numbers": "1,2,3"})
+    print(f"  {prompt}")
+    print()
+
+    print("=" * 50)
+    print("Done!")
+    print("=" * 50)
+
+
+if __name__ == "__main__":
+    try:
+        asyncio.run(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/1c_logging_client.py

@@ -0,0 +1,100 @@
+#!/usr/bin/env python3
+"""
+1c_logging_client.py - Context Logging and Audit
+
+Tests logging features in the calculator server:
+- ctx.info(), ctx.debug(), ctx.warning() during calculate()
+- ctx.audit() creates signed audit entries
+
+Prerequisites:
+    - MACAW SDK installed (pip install macaw-client macaw-adapters)
+    - Calculator server running (securemcp_calculator.py)
+
+Run:
+    # Terminal 1: Start the server
+    python securemcp_calculator.py
+
+    # Terminal 2: Run this client
+    python 1c_logging_client.py
+
+Check MACAW logs to see the logged events:
+    ~/.macaw/data/tenants/<tenant>/logs/events.log
+"""
+
+from macaw_adapters.mcp import Client
+
+
+def find_calculator_server(client):
+    """Find the most recent calculator server."""
+    agents = client.macaw_client.list_agents(agent_type="app")
+    # Match exactly "securemcp-calculator:" to avoid stale "securemcp-securemcp-calculator"
+    calc_servers = [
+        a["agent_id"] for a in agents
+        if "/app:securemcp-calculator:" in a.get("agent_id", "")
+        and "/tool." not in a.get("agent_id", "")
+    ]
+    return calc_servers[0] if calc_servers else None
+
+
+def main():
+    print("=" * 50)
+    print("Example 1c: Logging & Audit Demo")
+    print("=" * 50)
+
+    client = Client("logging-test-client")
+    print(f"Client: {client.client_id}")
+
+    server = find_calculator_server(client)
+    if not server:
+        print("\nNo calculator server found!")
+        print("Start it first: python3 securemcp_calculator.py")
+        return
+
+    print(f"Server: {server}")
+    print()
+
+    # Test calculate() - generates ctx.info(), ctx.debug(), ctx.audit()
+    print("Testing calculate() - generates logging and audit:")
+    print("-" * 40)
+
+    tests = [
+        ("add", 10, 5),
+        ("multiply", 7, 8),
+        ("subtract", 20, 7),
+        ("divide", 100, 4),
+    ]
+
+    for op, a, b in tests:
+        result = client.macaw_client.invoke_tool(
+            "calculate",
+            {"operation": op, "a": a, "b": b},
+            target_agent=server
+        )
+        print(f"  {op}({a}, {b}) = {result}")
+
+    print()
+    print("=" * 50)
+    print("Check MACAW logs at:")
+    print("  ~/.macaw/data/tenants/<tenant>/logs/events.log")
+    print()
+    print("Look for:")
+    print("  - tool_log: level=info, message='Calculating: ...'")
+    print("  - tool_log: level=debug, message='Result computed: ...'")
+    print("  - audit: action=calculation (signed)")
+    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/1d_progress_client.py

@@ -0,0 +1,100 @@
+#!/usr/bin/env python3
+"""
+1d_progress_client.py - Progress Reporting
+
+Tests progress reporting in the calculator server:
+- batch_calculate() reports progress via ctx.report_progress()
+- Progress events are emitted to MACAW audit system
+
+Prerequisites:
+    - MACAW SDK installed (pip install macaw-client macaw-adapters)
+    - Calculator server running (securemcp_calculator.py)
+
+Run:
+    # Terminal 1: Start the server
+    python securemcp_calculator.py
+
+    # Terminal 2: Run this client
+    python 1d_progress_client.py
+"""
+
+from macaw_adapters.mcp import Client
+
+
+def find_calculator_server(client):
+    """Find the most recent calculator server."""
+    agents = client.macaw_client.list_agents(agent_type="app")
+    # Match exactly "/app:securemcp-calculator:" to avoid stale registrations
+    calc_servers = [
+        a["agent_id"] for a in agents
+        if "/app:securemcp-calculator:" in a.get("agent_id", "")
+        and "/tool." not in a.get("agent_id", "")
+    ]
+    return calc_servers[0] if calc_servers else None
+
+
+def main():
+    print("=" * 50)
+    print("Example 1d: Progress Reporting Demo")
+    print("=" * 50)
+
+    client = Client("progress-test-client")
+    print(f"Client: {client.client_id}")
+
+    server = find_calculator_server(client)
+    if not server:
+        print("\nNo calculator server found!")
+        print("Start it first: python3 securemcp_calculator.py")
+        return
+
+    print(f"Server: {server}")
+    print()
+
+    # Test batch_calculate() - generates progress events
+    print("Testing batch_calculate() - generates progress events:")
+    print("-" * 40)
+
+    calculations = [
+        {"op": "add", "a": 1, "b": 2},
+        {"op": "multiply", "a": 3, "b": 4},
+        {"op": "subtract", "a": 10, "b": 3},
+        {"op": "divide", "a": 100, "b": 5},
+        {"op": "add", "a": 50, "b": 50},
+    ]
+
+    print(f"  Sending batch of {len(calculations)} calculations...")
+    result = client.macaw_client.invoke_tool(
+        "batch_calculate",
+        {"calculations": calculations},
+        target_agent=server
+    )
+
+    print(f"  Batch result: {result['count']} calculations")
+    for r in result.get("results", []):
+        print(f"    {r['expression']} = {r.get('result', r.get('error'))}")
+
+    print()
+    print("=" * 50)
+    print("Check MACAW logs for progress events:")
+    print("  - Progress 0%: 'Processing 5 calculations'")
+    print("  - Progress 20%: 'Calculating 1/5: ...'")
+    print("  - Progress 40%: 'Calculating 2/5: ...'")
+    print("  - ...")
+    print("  - Progress 100%: 'Batch complete'")
+    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/1e_sampling_client.py

@@ -0,0 +1,150 @@
+#!/usr/bin/env python3
+"""
+1e_sampling_client.py - MCP Sampling (Server->Client LLM)
+
+Demonstrates client.set_sampling_handler() for server->client LLM requests.
+
+The client registers an LLM handler that the server's ctx.sample() calls.
+Set ANTHROPIC_API_KEY environment variable to use real Claude API,
+otherwise falls back to mock responses.
+
+Prerequisites:
+    - MACAW SDK installed (pip install macaw-client macaw-adapters)
+    - Sampling server running (1e_sampling_server.py)
+    - ANTHROPIC_API_KEY environment variable (optional, for real Claude)
+
+Run:
+    # Terminal 1: Start the server
+    python 1e_sampling_server.py
+
+    # Terminal 2: Run this client (with optional API key)
+    export ANTHROPIC_API_KEY=sk-ant-...  # Optional
+    python 1e_sampling_client.py
+"""
+
+import os
+
+from macaw_adapters.mcp import Client
+
+MODEL = "claude-opus-4-8"
+
+
+def find_sampling_server(client):
+    """Find the most recent sampling demo server."""
+    agents = client.macaw_client.list_agents(agent_type="app")
+    matching = [
+        a["agent_id"] for a in agents
+        if "sampling-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 create_llm_handler():
+    """Create LLM handler - real Claude if API key available, else mock."""
+    api_key = os.environ.get("ANTHROPIC_API_KEY")
+
+    if api_key:
+        try:
+            import anthropic
+            client = anthropic.Anthropic(api_key=api_key)
+            print(f"Using Claude API ({MODEL})")
+
+            def claude_handler(prompt, system_prompt=None, max_tokens=1000, temperature=None, **kwargs):
+                print(f"  [Claude] Prompt: {prompt[:60]}...")
+                # temperature is intentionally not forwarded: this handler owns the
+                # model choice, and current Claude models reject temperature/top_p/
+                # top_k with a 400. MCP treats sampling params as ignorable hints.
+                response = client.messages.create(
+                    model=MODEL,
+                    max_tokens=max_tokens,
+                    system=system_prompt or "You are a helpful assistant.",
+                    messages=[{"role": "user", "content": prompt}]
+                )
+                result = response.content[0].text
+                print(f"  [Claude] Response: {result[:60]}...")
+                return result
+
+            return claude_handler
+        except ImportError:
+            print("anthropic package not installed, falling back to mock")
+        except Exception as e:
+            print(f"Error initializing Claude: {e}, falling back to mock")
+
+    # Mock handler fallback
+    print("Using mock LLM (set ANTHROPIC_API_KEY for real Claude)")
+
+    def mock_handler(prompt, system_prompt=None, max_tokens=1000, temperature=None, **kwargs):
+        print(f"  [Mock] Prompt: {prompt[:60]}...")
+        if "summarize" in prompt.lower():
+            return "This is a mock summary of the provided text."
+        elif "sentiment" in prompt.lower():
+            return '{"sentiment": "positive", "confidence": 0.85}'
+        return "Mock LLM response"
+
+    return mock_handler
+
+
+def main():
+    print("=" * 50)
+    print("Example 1e: Sampling Demo Client")
+    print("=" * 50)
+
+    client = Client("sampling-client")
+    print(f"Client: {client.client_id}")
+
+    # Create and register LLM handler (Claude or mock)
+    llm_handler = create_llm_handler()
+    client.set_sampling_handler(llm_handler)
+    print()
+
+    server = find_sampling_server(client)
+    if not server:
+        print("\nNo sampling-demo server found!")
+        print("Start it first: python3 1e_sampling_server.py")
+        return
+
+    print(f"Server: {server}")
+    print()
+
+    # Test summarize
+    print("Testing summarize():")
+    print("-" * 40)
+    result = client.macaw_client.invoke_tool(
+        "summarize",
+        {"text": "The quick brown fox jumps over the lazy dog. This sentence contains every letter of the alphabet and is commonly used for typing practice.", "max_length": 50},
+        target_agent=server
+    )
+    print(f"  Result: {result}")
+    print()
+
+    # Test analyze_sentiment
+    print("Testing analyze_sentiment():")
+    print("-" * 40)
+    result = client.macaw_client.invoke_tool(
+        "analyze_sentiment",
+        {"text": "I love this product! It's amazing and works perfectly!"},
+        target_agent=server
+    )
+    print(f"  Result: {result}")
+    print()
+
+    print("=" * 50)
+    print("Done!")
+    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/1e_sampling_server.py

@@ -0,0 +1,90 @@
+#!/usr/bin/env python3
+"""
+Example 1e: MCP Sampling - SERVER
+
+Demonstrates ctx.sample() - server requesting LLM completions from client.
+
+The server tools here use ctx.sample() to request AI assistance from
+the client's configured LLM handler.
+
+Run this server, then run 1e_sampling_client.py in another terminal.
+"""
+
+from macaw_adapters.mcp import SecureMCP, Context
+
+mcp = SecureMCP("sampling-demo")
+
+
+@mcp.tool(description="Summarize text using client's LLM")
+async def summarize(ctx: Context, text: str, max_length: int = 100) -> dict:
+    """Summarize text via client's LLM (ctx.sample)."""
+    ctx.info(f"Summarizing {len(text)} characters")
+
+    prompt = f"Summarize in {max_length} words or less:\n\n{text}\n\nSummary:"
+
+    try:
+        summary = await ctx.sample(
+            prompt=prompt,
+            system_prompt="You are a concise summarization assistant.",
+            max_tokens=200,
+            temperature=0.3
+        )
+        return {"summary": summary, "original_length": len(text)}
+    except Exception as e:
+        ctx.error(f"Sampling failed: {e}")
+        return {"error": str(e)}
+
+
+@mcp.tool(description="Analyze sentiment using client's LLM")
+async def analyze_sentiment(ctx: Context, text: str) -> dict:
+    """Analyze sentiment via client's LLM."""
+    ctx.info("Analyzing sentiment")
+
+    prompt = f"""Analyze sentiment. Respond with JSON:
+{{"sentiment": "positive/negative/neutral", "confidence": 0.0-1.0}}
+
+Text: {text}
+
+JSON:"""
+
+    try:
+        analysis = await ctx.sample(
+            prompt=prompt,
+            system_prompt="You are a sentiment analyzer. Respond only with JSON.",
+            max_tokens=100,
+            temperature=0.1
+        )
+        return {"text": text[:50] + "..." if len(text) > 50 else text, "analysis": analysis}
+    except Exception as e:
+        return {"error": str(e)}
+
+
+if __name__ == "__main__":
+    import sys
+
+    # Optional transport for native (non-MACAW) MCP clients:
+    #   python 1e_sampling_server.py           MACAW mesh only (use 1e_sampling_client.py)
+    #   python 1e_sampling_server.py stdio     also serve native MCP clients
+    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("=" * 50, file=out)
+    print("Example 1e: Sampling Demo Server", file=out)
+    print("=" * 50, file=out)
+    print(file=out)
+    print("Tools: summarize, analyze_sentiment", file=out)
+    print(file=out)
+    print("These tools use ctx.sample() to request LLM completions", file=out)
+    print("from the client's configured handler.", file=out)
+    print(file=out)
+    if transport:
+        print(f"Also serving native MCP clients over: {transport}", file=out)
+        print("Run client: python3 3c_native_mcp_sampling.py", file=out)
+    else:
+        print("Run client: python3 1e_sampling_client.py", file=out)
+    print(file=out)
+    print("Press Ctrl+C to stop", file=out)
+    print("=" * 50, file=out)
+    mcp.run(transport=transport)