mcp-proxy-adapter 2.1.0__py3-none-any.whl → 2.1.2__py3-none-any.whl

examples/extension_example.py

@@ -0,0 +1,60 @@
+"""
+Extension Example for MCPProxyAdapter
+
+- How to add custom commands
+- How to extend help logic
+- How to customize error handling
+
+Run:
+    python examples/extension_example.py
+"""
+import os
+import sys
+sys.path.insert(0, os.path.abspath(os.path.dirname(os.path.dirname(__file__))))
+from mcp_proxy_adapter.adapter import MCPProxyAdapter
+
+class MyRegistry:
+    def __init__(self):
+        self.dispatcher = self
+        self.commands = {"ping": self.ping, "help": self.help_command}
+        self.commands_info = {
+            "ping": {"description": "Ping command (returns pong)", "params": {}},
+            "help": {"description": "Show help for commands", "params": {"command": {"type": "string", "description": "Command name", "required": False}}}
+        }
+    def get_valid_commands(self):
+        return list(self.commands.keys())
+    def get_command_info(self, command):
+        return self.commands_info.get(command)
+    def get_commands_info(self):
+        return self.commands_info
+    def execute(self, *args, **params):
+        if args:
+            command = args[0]
+            params = {k: v for k, v in params.items()}
+        else:
+            command = params.pop("command", None)
+        if command == "ping":
+            return self.ping()
+        if command == "help":
+            return self.help_command(**params)
+        raise KeyError(f"Unknown command: {command}")
+    def add_generator(self, generator):
+        pass
+    def ping(self):
+        """Ping command."""
+        return {"result": "pong"}
+    def help_command(self, command: str = None):
+        """Custom help logic: returns info for command or all commands."""
+        if not command:
+            return {"commands": list(self.commands_info.keys())}
+        if command in self.commands_info:
+            return {"command": command, "info": self.commands_info[command]}
+        return {"error": f"Command '{command}' not found"}
+
+if __name__ == "__main__":
+    registry = MyRegistry()
+    adapter = MCPProxyAdapter(registry)
+    print("[EXT] Ping:", registry.execute("ping"))
+    print("[EXT] Help (all):", registry.execute("help"))
+    print("[EXT] Help (ping):", registry.execute("help", command="ping"))
+    print("[EXT] Help (notfound):", registry.execute("help", command="notfound")) 

examples/help_best_practices.py

@@ -0,0 +1,67 @@
+"""
+Best Practices: Integrating and Testing 'help' Command in MCPProxyAdapter
+
+This example demonstrates:
+- How to robustly integrate a project-level 'help' command
+- How to extend help with custom logic
+- How to test help scenarios (including fallback and error cases)
+- How to avoid common mistakes
+
+Run:
+    python examples/help_best_practices.py
+"""
+import os
+import sys
+sys.path.insert(0, os.path.abspath(os.path.dirname(os.path.dirname(__file__))))
+from typing import Any, Dict
+from mcp_proxy_adapter.adapter import MCPProxyAdapter
+from tests.test_mcp_proxy_adapter import MockRegistry
+
+# --- Setup registry and adapter ---
+registry = MockRegistry()
+adapter = MCPProxyAdapter(registry)
+
+def robust_help(command: str = None) -> Dict[str, Any]:
+    """
+    Best practice: always check for project help, handle errors, fallback to adapter help.
+    """
+    dispatcher = registry.dispatcher
+    if "help" in dispatcher.get_valid_commands():
+        try:
+            if command:
+                return dispatcher.help_command(command=command)
+            return dispatcher.help_command()
+        except Exception as e:
+            # Log error, fallback to adapter help
+            print(f"[WARN] Project help failed: {e}. Fallback to adapter help.")
+            return fallback_adapter_help(command)
+    else:
+        return fallback_adapter_help(command)
+
+def fallback_adapter_help(command: str = None) -> Dict[str, Any]:
+    """
+    Fallback: call adapter's help (simulate REST/JSON-RPC call).
+    """
+    dispatcher = registry.dispatcher
+    if not command:
+        return {"source": "adapter", "commands": dispatcher.get_valid_commands()}
+    if command in dispatcher.get_valid_commands():
+        return {"source": "adapter", "command": command, "info": {"description": "Adapter help for command"}}
+    return {"source": "adapter", "error": f"Command '{command}' not found (adapter)", "available_commands": dispatcher.get_valid_commands()}
+
+# --- Example test cases ---
+def test_help():
+    """Test all help scenarios."""
+    print("[TEST] Project help (no param):", robust_help())
+    print("[TEST] Project help (existing command):", robust_help("success"))
+    print("[TEST] Project help (nonexistent command, triggers fallback):", robust_help("not_a_command"))
+    # Simulate registry without help
+    registry_no_help = MockRegistry()
+    if "help" in registry_no_help.dispatcher.commands:
+        del registry_no_help.dispatcher.commands["help"]
+    global registry
+    registry = registry_no_help
+    print("[TEST] Adapter help (no project help present):", robust_help("success"))
+
+if __name__ == "__main__":
+    test_help() 

examples/help_usage.py

@@ -0,0 +1,64 @@
+"""
+Example: Using 'help' command with MCPProxyAdapter
+
+This script demonstrates how to:
+- Call the 'help' command (if present in the project)
+- Call 'help' with a parameter (for a specific command)
+- Handle errors and fallback to adapter help
+- Best practices for integrating and extending help
+
+Run:
+    python examples/help_usage.py
+"""
+import os
+import sys
+sys.path.insert(0, os.path.abspath(os.path.dirname(os.path.dirname(__file__))))
+from typing import Any, Dict
+
+# Assume MCPProxyAdapter and MockRegistry are available from src and tests
+from mcp_proxy_adapter.adapter import MCPProxyAdapter
+from tests.test_mcp_proxy_adapter import MockRegistry
+
+# --- Setup registry and adapter ---
+registry = MockRegistry()
+adapter = MCPProxyAdapter(registry)
+
+# --- Best practice: always check if 'help' is in commands ---
+def call_help(command: str = None) -> Dict[str, Any]:
+    """Call help command with or without parameter."""
+    dispatcher = registry.dispatcher
+    if "help" in dispatcher.get_valid_commands():
+        if command:
+            try:
+                return dispatcher.help_command(command=command)
+            except Exception as e:
+                print(f"Project help failed: {e}. Fallback to adapter help.")
+                return adapter_help(command)
+        else:
+            return dispatcher.help_command()
+    else:
+        return adapter_help(command)
+
+def adapter_help(command: str = None) -> Dict[str, Any]:
+    """Fallback: call adapter's help (simulate)."""
+    dispatcher = registry.dispatcher
+    if not command:
+        return {"source": "adapter", "commands": dispatcher.get_valid_commands()}
+    if command in dispatcher.get_valid_commands():
+        return {"source": "adapter", "command": command, "info": {"description": "Adapter help for command"}}
+    return {"source": "adapter", "error": f"Command '{command}' not found (adapter)", "available_commands": dispatcher.get_valid_commands()}
+
+if __name__ == "__main__":
+    print("=== Project help (no param) ===")
+    print(call_help())
+    print("\n=== Project help (existing command) ===")
+    print(call_help("success"))
+    print("\n=== Project help (nonexistent command, triggers fallback) ===")
+    print(call_help("not_a_command"))
+    print("\n=== Adapter help (no project help present) ===")
+    # Simulate registry without help
+    registry_no_help = MockRegistry()
+    if "help" in registry_no_help.dispatcher.commands:
+        del registry_no_help.dispatcher.commands["help"]
+    adapter_no_help = MCPProxyAdapter(registry_no_help)
+    print(adapter_help("success")) 

examples/mcp_proxy_client.py

@@ -0,0 +1,131 @@
+"""
+Client for testing interaction with OpenAPI server through MCP Proxy.
+
+This script demonstrates how a client can send JSON-RPC requests
+to MCP Proxy, which forwards them to the OpenAPI server.
+
+Usage:
+    python examples/mcp_proxy_client.py
+"""
+import os
+import sys
+import json
+import requests
+from typing import Dict, Any, Optional
+
+def send_jsonrpc_request(
+    endpoint: str, 
+    method: str, 
+    params: Optional[Dict[str, Any]] = None, 
+    request_id: int = 1
+) -> Dict[str, Any]:
+    """
+    Sends JSON-RPC request to specified endpoint.
+    
+    Args:
+        endpoint (str): Endpoint URL
+        method (str): Method name to call
+        params (Optional[Dict[str, Any]], optional): Method parameters. Defaults to None.
+        request_id (int, optional): Request ID. Defaults to 1.
+        
+    Returns:
+        Dict[str, Any]: Server response
+    """
+    # Form JSON-RPC request
+    payload = {
+        "jsonrpc": "2.0",
+        "method": method,
+        "id": request_id
+    }
+    
+    # Add parameters if they exist
+    if params:
+        payload["params"] = params
+    
+    # Send request
+    response = requests.post(endpoint, json=payload)
+    
+    # Return response in JSON format
+    return response.json()
+
+def print_response(response: Dict[str, Any]) -> None:
+    """
+    Prints response in formatted view.
+    
+    Args:
+        response (Dict[str, Any]): Server response
+    """
+    print("Response:")
+    print(json.dumps(response, indent=2, ensure_ascii=False))
+    print("-" * 50)
+
+def main():
+    """Main function for demonstrating work with MCP Proxy."""
+    # Base server URL
+    server_url = "http://localhost:8000"
+    
+    # JSON-RPC endpoint (should match cmd_endpoint in MCPProxyAdapter)
+    jsonrpc_endpoint = f"{server_url}/api/command"
+    
+    print("=== Testing JSON-RPC requests through MCP Proxy ===\n")
+    
+    # Example 1: Get all items
+    print("1. Getting all items:")
+    response = send_jsonrpc_request(jsonrpc_endpoint, "get_items")
+    print_response(response)
+    
+    # Example 2: Get item by ID
+    print("2. Getting item by ID:")
+    response = send_jsonrpc_request(jsonrpc_endpoint, "get_item", {"item_id": 1})
+    print_response(response)
+    
+    # Example 3: Create new item
+    print("3. Creating new item:")
+    new_item = {
+        "name": "Test Item",
+        "description": "Item for API testing",
+        "price": 123.45,
+        "is_available": True
+    }
+    response = send_jsonrpc_request(jsonrpc_endpoint, "create_item", {"item": new_item})
+    print_response(response)
+    
+    # Get created item ID for further operations
+    if "result" in response:
+        created_item_id = response["result"]["id"]
+    else:
+        # Use fixed ID in case of error
+        created_item_id = 4
+    
+    # Example 4: Update item
+    print(f"4. Updating item with ID {created_item_id}:")
+    updated_data = {
+        "name": "Updated Item",
+        "price": 199.99
+    }
+    response = send_jsonrpc_request(
+        jsonrpc_endpoint, 
+        "update_item", 
+        {"item_id": created_item_id, "updated_data": updated_data}
+    )
+    print_response(response)
+    
+    # Example 5: Search items
+    print("5. Searching items by keyword:")
+    response = send_jsonrpc_request(jsonrpc_endpoint, "search_items", {"keyword": "updated"})
+    print_response(response)
+    
+    # Example 6: Delete item
+    print(f"6. Deleting item with ID {created_item_id}:")
+    response = send_jsonrpc_request(jsonrpc_endpoint, "delete_item", {"item_id": created_item_id})
+    print_response(response)
+    
+    # Example 7: Check after deletion
+    print("7. Checking items list after deletion:")
+    response = send_jsonrpc_request(jsonrpc_endpoint, "get_items")
+    print_response(response)
+    
+    print("Testing completed.")
+
+if __name__ == "__main__":
+    main() 

examples/mcp_proxy_config.json

@@ -0,0 +1,175 @@
+{
+  "version": "1.0",
+  "tools": [
+    {
+      "name": "mcp_get_items",
+      "description": "Get list of all items",
+      "parameters": {
+        "type": "object",
+        "properties": {},
+        "required": []
+      }
+    },
+    {
+      "name": "mcp_get_item",
+      "description": "Get item by ID",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "item_id": {
+            "type": "integer",
+            "description": "Item ID to search for"
+          }
+        },
+        "required": [
+          "item_id"
+        ]
+      }
+    },
+    {
+      "name": "mcp_create_item",
+      "description": "Create new item",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "item": {
+            "type": "object",
+            "description": "Item data"
+          }
+        },
+        "required": [
+          "item"
+        ]
+      }
+    },
+    {
+      "name": "mcp_update_item",
+      "description": "Update item by ID",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "item_id": {
+            "type": "integer",
+            "description": "Item ID to update"
+          },
+          "updated_data": {
+            "type": "object",
+            "description": "Updated data"
+          }
+        },
+        "required": [
+          "item_id",
+          "updated_data"
+        ]
+      }
+    },
+    {
+      "name": "mcp_delete_item",
+      "description": "Delete item by ID",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "item_id": {
+            "type": "integer",
+            "description": "Item ID to delete"
+          }
+        },
+        "required": [
+          "item_id"
+        ]
+      }
+    },
+    {
+      "name": "mcp_search_items",
+      "description": "Search items by keyword",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "keyword": {
+            "type": "string",
+            "description": "Search keyword"
+          }
+        },
+        "required": [
+          "keyword"
+        ]
+      }
+    },
+    {
+      "name": "mcp_execute",
+      "description": "Universal command for executing queries",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "query": {
+            "type": "string",
+            "description": "Query to execute"
+          },
+          "subcommand": {
+            "type": "string",
+            "description": "Subcommand to execute"
+          }
+        },
+        "required": []
+      }
+    }
+  ],
+  "routes": [
+    {
+      "tool_name": "mcp_get_items",
+      "endpoint": "/cmd",
+      "method": "post",
+      "json_rpc": {
+        "method": "get_items"
+      }
+    },
+    {
+      "tool_name": "mcp_get_item",
+      "endpoint": "/cmd",
+      "method": "post",
+      "json_rpc": {
+        "method": "get_item"
+      }
+    },
+    {
+      "tool_name": "mcp_create_item",
+      "endpoint": "/cmd",
+      "method": "post",
+      "json_rpc": {
+        "method": "create_item"
+      }
+    },
+    {
+      "tool_name": "mcp_update_item",
+      "endpoint": "/cmd",
+      "method": "post",
+      "json_rpc": {
+        "method": "update_item"
+      }
+    },
+    {
+      "tool_name": "mcp_delete_item",
+      "endpoint": "/cmd",
+      "method": "post",
+      "json_rpc": {
+        "method": "delete_item"
+      }
+    },
+    {
+      "tool_name": "mcp_search_items",
+      "endpoint": "/cmd",
+      "method": "post",
+      "json_rpc": {
+        "method": "search_items"
+      }
+    },
+    {
+      "tool_name": "mcp_execute",
+      "endpoint": "/cmd",
+      "method": "post",
+      "json_rpc": {
+        "method": "execute"
+      }
+    }
+  ]
+}