mcp-proxy-adapter 1.0.0__py3-none-any.whl

mcp_proxy_adapter-1.0.0.dist-info/METADATA

@@ -0,0 +1,262 @@
+Metadata-Version: 2.4
+Name: mcp-proxy-adapter
+Version: 1.0.0
+Summary: Adapter for exposing Command Registry commands as tools for AI models via MCP Proxy.
+Home-page: https://github.com/vasilyvz/mcp-proxy-adapter
+Author: Vasiliy VZ
+Author-email: Vasiliy VZ <vasilyvz@example.com>
+License: MIT
+Project-URL: Homepage, https://github.com/vasilyvz/mcp-proxy-adapter
+Project-URL: Bug Tracker, https://github.com/vasilyvz/mcp-proxy-adapter/issues
+Project-URL: Documentation, https://github.com/vasilyvz/mcp-proxy-adapter/tree/main/docs
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.9, <4
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi<1.0.0,>=0.95.0
+Requires-Dist: pydantic<2.0.0,>=1.10.0
+Requires-Dist: uvicorn<1.0.0,>=0.22.0
+Requires-Dist: docstring-parser<1.0.0,>=0.15
+Requires-Dist: typing-extensions<5.0.0,>=4.5.0
+Dynamic: author
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-python
+
+# MCP Proxy Adapter
+
+Adapter for integrating [Command Registry](docs/README.md) with MCP Proxy, allowing you to use commands as tools for AI models.
+
+## Overview
+
+MCP Proxy Adapter transforms commands registered in the Command Registry into a format compatible with MCP Proxy. This enables:
+
+1. Using existing commands as tools for AI models
+2. Creating a hybrid REST/JSON-RPC API for command execution
+3. Automatic generation of OpenAPI schemas optimized for MCP Proxy
+4. Managing tool metadata for better AI system integration
+
+## Installation
+
+```bash
+pip install mcp-proxy-adapter
+```
+
+## Quick Start
+
+```python
+from mcp_proxy_adapter import MCPProxyAdapter, CommandRegistry
+from fastapi import FastAPI
+
+# Create a command registry instance
+registry = CommandRegistry()
+
+# Register commands
+@registry.command
+def calculate_total(prices: list[float], discount: float = 0.0) -> float:
+    """
+    Calculates the total price with discount.
+    Args:
+        prices: List of item prices
+        discount: Discount percentage (0-100)
+    Returns:
+        Total price with discount
+    """
+    subtotal = sum(prices)
+    return subtotal * (1 - discount / 100)
+
+# Create FastAPI app
+app = FastAPI()
+
+# Create and configure MCP Proxy adapter
+adapter = MCPProxyAdapter(registry)
+
+# Register endpoints in FastAPI app
+adapter.register_endpoints(app)
+
+# Generate and save MCP Proxy config
+adapter.save_config_to_file("mcp_proxy_config.json")
+```
+
+## Supported Request Formats
+
+The adapter supports three request formats for command execution:
+
+### 1. JSON-RPC format
+
+```json
+{
+  "jsonrpc": "2.0",
+  "method": "command_name",
+  "params": {
+    "param1": "value1",
+    "param2": "value2"
+  },
+  "id": 1
+}
+```
+
+Example request to `/cmd` endpoint:
+
+```bash
+curl -X POST -H "Content-Type: application/json" -d '{
+  "jsonrpc": "2.0",
+  "method": "calculate_total",
+  "params": {
+    "prices": [100, 200, 300],
+    "discount": 10
+  },
+  "id": 1
+}' http://localhost:8000/cmd
+```
+
+Response:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "result": 540.0,
+  "id": 1
+}
+```
+
+### 2. MCP Proxy format
+
+```json
+{
+  "command": "command_name",
+  "params": {
+    "param1": "value1",
+    "param2": "value2"
+  }
+}
+```
+
+Example request:
+
+```bash
+curl -X POST -H "Content-Type: application/json" -d '{
+  "command": "calculate_total",
+  "params": {
+    "prices": [100, 200, 300],
+    "discount": 10
+  }
+}' http://localhost:8000/cmd
+```
+
+Response:
+
+```json
+{
+  "result": 540.0
+}
+```
+
+### 3. Params-only format
+
+```json
+{
+  "params": {
+    "command": "command_name",
+    "param1": "value1",
+    "param2": "value2"
+  }
+}
+```
+
+or
+
+```json
+{
+  "params": {
+    "query": "command_name",
+    "param1": "value1",
+    "param2": "value2"
+  }
+}
+```
+
+Example request:
+
+```bash
+curl -X POST -H "Content-Type: application/json" -d '{
+  "params": {
+    "command": "calculate_total",
+    "prices": [100, 200, 300],
+    "discount": 10
+  }
+}' http://localhost:8000/cmd
+```
+
+Response:
+
+```json
+{
+  "result": 540.0
+}
+```
+
+## Full Example: Integration with FastAPI
+
+```python
+import logging
+from fastapi import FastAPI, APIRouter
+from mcp_proxy_adapter import CommandRegistry, MCPProxyAdapter, configure_logger
+
+# Configure logging
+logging.basicConfig(level=logging.INFO)
+project_logger = logging.getLogger("my_project")
+
+# Create FastAPI app
+app = FastAPI(title="My API with MCP Proxy Integration")
+
+# Create existing API router
+router = APIRouter()
+
+@router.get("/items")
+async def get_items():
+    """Returns a list of items."""
+    return [
+        {"id": 1, "name": "Smartphone X", "price": 999.99},
+        {"id": 2, "name": "Laptop Y", "price": 1499.99},
+    ]
+
+app.include_router(router)
+
+# Register commands
+registry = CommandRegistry()
+
+@registry.command
+def get_discounted_price(price: float, discount: float = 0.0) -> float:
+    """
+    Returns the price after applying a discount.
+    """
+    return price * (1 - discount / 100)
+
+# Create and register MCP Proxy adapter
+adapter = MCPProxyAdapter(registry)
+adapter.register_endpoints(app)
+
+# Save MCP Proxy config
+adapter.save_config_to_file("mcp_proxy_config.json")
+```
+
+## Features
+- Universal JSON-RPC endpoint for command execution
+- Automatic OpenAPI schema generation and optimization for MCP Proxy
+- Tool metadata for AI models
+- Customizable endpoints and logging
+- Full test coverage and examples
+
+## License
+MIT
+
+## Documentation
+See [docs/](docs/) for detailed guides, architecture, and examples. 

mcp_proxy_adapter-1.0.0.dist-info/RECORD

@@ -0,0 +1,28 @@
+adapters/__init__.py,sha256=7QraK1j5y29KFSRF4mVxTiWC2Y3IYZLd6GhxUCtjyhg,790
+analyzers/__init__.py,sha256=2rcYZDP-bXq078MQpxP32lAwYYyRhOwAQGBcefBfBzY,368
+analyzers/docstring_analyzer.py,sha256=T3FLJEo_uChShfiEKRl8GpVoHvh5HiudZkxnj4KixfA,7541
+analyzers/type_analyzer.py,sha256=6Wac7osKwF03waFSwQ8ZM0Wqn_zAP2D-I4WMEpR0hQM,5230
+cli/__init__.py,sha256=vJ0VTT7D4KRIOi9nQSgBLub7xywq68i2R1zYQkdA0Uk,416
+cli/__main__.py,sha256=qtjEOB4vkeMASjTppyRFok4IFihRrVOqjk6vLx8OW1g,2400
+cli/command_runner.py,sha256=4d0BZKRG9k4CLk3ZE26jfSxwwrls2e-KsflRoVimfyE,8328
+dispatchers/__init__.py,sha256=FWgimgInGphIjCEnvA3-ZExiapUzYAVis2H9C5IWivU,365
+dispatchers/base_dispatcher.py,sha256=S5_Xri058jAmOWeit1tedB_GMZQ9RLcNcYabA83ZF6k,2288
+dispatchers/json_rpc_dispatcher.py,sha256=ffu1M32E1AdC7IB44mlbV2L56eJQMsp-7fYi_r4rmHc,6331
+generators/__init__.py,sha256=KC8p2HcIBqdyCY1wHnN_c1EfbnPM39YhZLNBDcuv3vA,538
+generators/endpoint_generator.py,sha256=fhEInY3JPwdc5EENesN9VrrONwVZMpsledVpubouJLA,6513
+generators/openapi_generator.py,sha256=0Iqsn0fRr10sTWUK9-MU5MXOXKDHccxKYnmaiQPkKFw,9773
+generators/rest_api_generator.py,sha256=Zg9HVeIuspowXd6aBlyho4UXz-te_Hd4egGzjjIVF48,9159
+mcp_proxy_adapter-1.0.0.dist-info/licenses/LICENSE,sha256=OkApFEwdgMCt_mbvUI-eIwKMSTe38K3XnU2DT5ub-wI,1072
+openapi_schema/__init__.py,sha256=S_lEg-VtlgDdhFxB_u9ZUM1dWKbzW_L_FM-6OCT4EXM,1334
+openapi_schema/command_registry.py,sha256=VqqdsVCcd5neqZ-bsfeKTHeLBeputwUZHxvNxVuvqZs,12075
+openapi_schema/rest_schema.py,sha256=nfF9axtmEA-B-Rw8TCnpmRf6Br3MfQ3TJVx-QHUHoy8,24103
+openapi_schema/rpc_generator.py,sha256=5FGMqjMXcaW0Ej6oey5mgiIxtEKTtA87dc-_kWLWqb0,13640
+openapi_schema/rpc_schema.py,sha256=pebSNt9rKyP2dyHpbjSllak6pQe5AnllReKHhR3UIaI,20162
+validators/__init__.py,sha256=s6zd5oZ3V2pXtzONoH3CiZYLzSVtCoLXpETMFUQfwWY,403
+validators/base_validator.py,sha256=qTEcXnfGqsgKKtc-lnttLiPTuq6vOHfDpZrQ5oP5Fi0,602
+validators/docstring_validator.py,sha256=Onpq2iNJ1qF4ejkJJIlBkLROuSNIVALHVmXIgkCpaFI,2934
+validators/metadata_validator.py,sha256=uCrn38-VYYn89l6f5CC_GoTAHAweaOW2Z6Esro1rtGw,3155
+mcp_proxy_adapter-1.0.0.dist-info/METADATA,sha256=3wKs5p9EEFQCzWRmNySoQny1B4EmoUBFy2HOptUd2R4,5702
+mcp_proxy_adapter-1.0.0.dist-info/WHEEL,sha256=ooBFpIzZCPdw3uqIQsOo4qqbA4ZRPxHnOH7peeONza0,91
+mcp_proxy_adapter-1.0.0.dist-info/top_level.txt,sha256=SlVzE4ry_0xTgDmO2uiaI7ihb9MpR62izN4MH_t1BTU,72
+mcp_proxy_adapter-1.0.0.dist-info/RECORD,,

mcp_proxy_adapter-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

mcp_proxy_adapter-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023-2024 Vasiliy VZ
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE. 

mcp_proxy_adapter-1.0.0.dist-info/top_level.txt

@@ -0,0 +1,7 @@
+adapters
+analyzers
+cli
+dispatchers
+generators
+openapi_schema
+validators

openapi_schema/__init__.py

@@ -0,0 +1,38 @@
+"""
+Combined OpenAPI schema for REST and RPC API.
+Provides the get_openapi_schema function that returns the complete OpenAPI schema.
+"""
+from typing import Dict, Any
+
+from .rest_schema import get_rest_schema
+from .rpc_generator import generate_rpc_schema
+
+__all__ = ["get_openapi_schema"]
+
+
+def get_openapi_schema() -> Dict[str, Any]:
+    """
+    Gets the complete OpenAPI schema that includes both REST and RPC interfaces.
+    
+    Returns:
+        Dict[str, Any]: Complete OpenAPI schema
+    """
+    # Get the base REST schema
+    openapi_schema = get_rest_schema()
+    
+    # Generate RPC schema based on REST schema
+    rpc_schema = generate_rpc_schema(openapi_schema)
+    
+    # Add /cmd endpoint from RPC schema to the general schema
+    openapi_schema["paths"].update(rpc_schema["paths"])
+    
+    # Merge schema components
+    for component_type, components in rpc_schema["components"].items():
+        if component_type not in openapi_schema["components"]:
+            openapi_schema["components"][component_type] = {}
+        for component_name, component in components.items():
+            # Avoid component duplication
+            if component_name not in openapi_schema["components"][component_type]:
+                openapi_schema["components"][component_type][component_name] = component
+    
+    return openapi_schema 

openapi_schema/command_registry.py

@@ -0,0 +1,312 @@
+"""
+Command registry for automatic OpenAPI schema generation.
+Describes all available API commands, their parameters and response formats.
+"""
+from typing import Dict, Any, List, Optional, Type, Union, get_type_hints
+import inspect
+import docstring_parser
+from pydantic import BaseModel, Field, create_model
+
+class CommandParameter:
+    """Description of a command parameter"""
+    def __init__(self, name: str, type_hint: Type, default=None, description: str = None, required: bool = False):
+        self.name = name
+        self.type_hint = type_hint
+        self.default = default
+        self.description = description
+        self.required = required
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Converts parameter to dictionary for JSON Schema"""
+        result = {
+            "name": self.name,
+            "type": self._get_type_name(),
+            "description": self.description or f"Parameter {self.name}",
+            "required": self.required
+        }
+        
+        if self.default is not None and self.default is not inspect.Parameter.empty:
+            result["default"] = self.default
+            
+        return result
+    
+    def _get_type_name(self) -> str:
+        """Gets type name for JSON Schema"""
+        if self.type_hint == str:
+            return "string"
+        elif self.type_hint == int:
+            return "integer"
+        elif self.type_hint == float:
+            return "number"
+        elif self.type_hint == bool:
+            return "boolean"
+        elif self.type_hint == list or self.type_hint == List:
+            return "array"
+        elif self.type_hint == dict or self.type_hint == Dict:
+            return "object"
+        else:
+            return "object"
+
+
+class CommandInfo:
+    """Information about a command"""
+    def __init__(self, name: str, handler_func, description: str = None, summary: str = None):
+        self.name = name
+        self.handler_func = handler_func
+        self.description = description or ""
+        self.summary = summary or name.replace("_", " ").capitalize()
+        self.parameters: List[CommandParameter] = []
+        self._parse_parameters()
+    
+    def _parse_parameters(self):
+        """Extracts parameter information from function signature"""
+        sig = inspect.signature(self.handler_func)
+        type_hints = get_type_hints(self.handler_func)
+        docstring = docstring_parser.parse(self.handler_func.__doc__ or "")
+        
+        # Create dictionary for finding parameter descriptions in docstring
+        param_descriptions = {param.arg_name: param.description for param in docstring.params}
+        
+        for name, param in sig.parameters.items():
+            # Ignore self parameter for class methods
+            if name == 'self':
+                continue
+                
+            # Determine parameter type
+            param_type = type_hints.get(name, Any)
+            
+            # Determine if parameter is required
+            required = param.default == inspect.Parameter.empty
+            
+            # Add parameter
+            self.parameters.append(CommandParameter(
+                name=name,
+                type_hint=param_type,
+                default=None if param.default == inspect.Parameter.empty else param.default,
+                description=param_descriptions.get(name),
+                required=required
+            ))
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Converts command information to dictionary for OpenAPI schema"""
+        return {
+            "name": self.name,
+            "summary": self.summary,
+            "description": self.description,
+            "parameters": [param.to_dict() for param in self.parameters]
+        }
+
+
+class CommandRegistry:
+    """API command registry"""
+    def __init__(self):
+        self.commands: Dict[str, CommandInfo] = {}
+    
+    def register(self, name: str, handler_func = None, description: str = None, summary: str = None):
+        """
+        Registers a command in the registry.
+        Can be used as a decorator.
+        
+        Args:
+            name: Command name
+            handler_func: Command handler function
+            description: Command description
+            summary: Brief command summary
+        """
+        def decorator(func):
+            self.commands[name] = CommandInfo(
+                name=name,
+                handler_func=func,
+                description=description or func.__doc__,
+                summary=summary
+            )
+            return func
+        
+        if handler_func is not None:
+            return decorator(handler_func)
+        return decorator
+    
+    def get_command(self, name: str) -> Optional[CommandInfo]:
+        """Gets information about a command by its name"""
+        return self.commands.get(name)
+    
+    def get_all_commands(self) -> List[CommandInfo]:
+        """Gets list of all registered commands"""
+        return list(self.commands.values())
+    
+    def generate_openapi_components(self) -> Dict[str, Any]:
+        """
+        Generates OpenAPI schema components based on registered commands.
+        
+        Returns:
+            Dict[str, Any]: OpenAPI schema components
+        """
+        components = {
+            "schemas": {}
+        }
+        
+        # Add common schemas for CommandRequest and JsonRpcResponse
+        components["schemas"]["CommandRequest"] = {
+            "type": "object",
+            "required": ["command", "jsonrpc"],
+            "properties": {
+                "jsonrpc": {
+                    "type": "string",
+                    "description": "JSON-RPC protocol version",
+                    "enum": ["2.0"],
+                    "default": "2.0"
+                },
+                "id": {
+                    "type": ["string", "number", "null"],
+                    "description": "Request identifier, used to match requests and responses"
+                },
+                "command": {
+                    "type": "string",
+                    "title": "Command",
+                    "description": "Command name to execute",
+                    "enum": list(self.commands.keys())
+                },
+                "params": {
+                    "title": "Params",
+                    "description": "Command parameters",
+                    "oneOf": []
+                }
+            }
+        }
+        
+        components["schemas"]["JsonRpcResponse"] = {
+            "type": "object",
+            "required": ["jsonrpc", "success"],
+            "properties": {
+                "jsonrpc": {
+                    "type": "string",
+                    "description": "JSON-RPC protocol version",
+                    "enum": ["2.0"],
+                    "default": "2.0"
+                },
+                "success": {
+                    "type": "boolean",
+                    "description": "Operation success indicator",
+                    "default": False
+                },
+                "result": {
+                    "description": "Operation result. Present only on successful execution (success=True). Result format depends on the executed command."
+                },
+                "error": {
+                    "description": "Error information. Present only when error occurs (success=false).",
+                    "type": "object",
+                    "required": ["code", "message"],
+                    "properties": {
+                        "code": {
+                            "type": "integer",
+                            "description": "Error code (internal code, not HTTP status)",
+                            "example": 400
+                        },
+                        "message": {
+                            "type": "string",
+                            "description": "Error message description",
+                            "example": "Record does not exist: ID 12345"
+                        }
+                    }
+                },
+                "id": {
+                    "type": ["string", "number", "null"],
+                    "description": "Request identifier (if specified in request)"
+                }
+            },
+            "example": {
+                "jsonrpc": "2.0",
+                "success": True,
+                "result": {"id": "550e8400-e29b-41d4-a716-446655440000"},
+                "id": "request-1"
+            }
+        }
+        
+        # Create schemas for each command's parameters
+        for command_name, command_info in self.commands.items():
+            param_schema_name = f"{command_name.title().replace('_', '')}Params"
+            
+            # Create command parameter schema
+            param_schema = {
+                "type": "object",
+                "title": param_schema_name,
+                "description": f"Parameters for command {command_name}",
+                "properties": {},
+                "required": []
+            }
+            
+            # Add properties for each parameter
+            for param in command_info.parameters:
+                param_type = param._get_type_name()
+                param_schema["properties"][param.name] = {
+                    "type": param_type,
+                    "description": param.description or f"Parameter {param.name}"
+                }
+                
+                if param.default is not None and param.default is not inspect.Parameter.empty:
+                    param_schema["properties"][param.name]["default"] = param.default
+                
+                if param.required:
+                    param_schema["required"].append(param.name)
+            
+            # Add parameter schema to components
+            components["schemas"][param_schema_name] = param_schema
+            
+            # Add reference to parameter schema in oneOf list of CommandRequest
+            components["schemas"]["CommandRequest"]["properties"]["params"]["oneOf"].append({
+                "$ref": f"#/components/schemas/{param_schema_name}"
+            })
+        
+        # Add null as possible value for parameters
+        components["schemas"]["CommandRequest"]["properties"]["params"]["oneOf"].append({
+            "type": "null"
+        })
+        
+        return components
+    
+    def generate_examples(self) -> Dict[str, Any]:
+        """
+        Generates command usage examples for OpenAPI schema.
+        
+        Returns:
+            Dict[str, Any]: Command usage examples
+        """
+        examples = {}
+        
+        for command_name, command_info in self.commands.items():
+            # Create base request example
+            example = {
+                "summary": command_info.summary,
+                "value": {
+                    "jsonrpc": "2.0",
+                    "command": command_name,
+                    "params": {},
+                    "id": command_name
+                }
+            }
+            
+            # Fill example with default parameters or examples
+            for param in command_info.parameters:
+                if param.default is not None and param.default is not inspect.Parameter.empty:
+                    example["value"]["params"][param.name] = param.default
+                elif param.type_hint == str:
+                    example["value"]["params"][param.name] = f"example_{param.name}"
+                elif param.type_hint == int:
+                    example["value"]["params"][param.name] = 1
+                elif param.type_hint == float:
+                    example["value"]["params"][param.name] = 1.0
+                elif param.type_hint == bool:
+                    example["value"]["params"][param.name] = True
+                elif param.type_hint == list or param.type_hint == List:
+                    example["value"]["params"][param.name] = []
+                elif param.type_hint == dict or param.type_hint == Dict:
+                    example["value"]["params"][param.name] = {}
+            
+            # Add example to examples dictionary
+            examples[f"{command_name}_example"] = example
+            
+        return examples
+
+
+# Create global command registry instance
+registry = CommandRegistry()