mcp-proxy-adapter 2.0.2__py3-none-any.whl → 2.1.1__py3-none-any.whl

examples/openapi_server.py

@@ -0,0 +1,369 @@
+"""
+Example of creating an OpenAPI server using MCP Proxy Adapter.
+
+Usage:
+    python examples/openapi_server.py
+
+Server will be available at: http://localhost:8000
+"""
+import os
+import sys
+import logging
+from typing import Dict, List, Any
+
+# Add project root directory to sys.path
+sys.path.insert(0, os.path.abspath(os.path.dirname(os.path.dirname(__file__))))
+
+from fastapi import FastAPI, Query, Path, Body, Request
+from pydantic import BaseModel, Field
+import uvicorn
+
+# Import MCP Proxy Adapter
+from mcp_proxy_adapter.adapter import MCPProxyAdapter
+
+# Import models for JSON-RPC
+from mcp_proxy_adapter.models import JsonRpcRequest, JsonRpcResponse
+
+# Import MockRegistry from tests for example
+# (in a real project, CommandRegistry would be used)
+from tests.test_mcp_proxy_adapter import MockRegistry
+
+# Configure logging
+logging.basicConfig(level=logging.DEBUG)
+logger = logging.getLogger(__name__)
+
+# Data model definitions
+class Item(BaseModel):
+    """Data model for an item."""
+    id: int = Field(..., description="Unique item identifier")
+    name: str = Field(..., description="Item name")
+    description: str = Field(None, description="Item description")
+    price: float = Field(..., description="Item price")
+    is_available: bool = Field(True, description="Item availability")
+
+    model_config = {
+        "json_schema_extra": {
+            "example": {
+                "id": 1,
+                "name": "Super Product",
+                "description": "Best product on the market",
+                "price": 99.99,
+                "is_available": True
+            }
+        }
+    }
+
+# Example data
+items_db = [
+    {
+        "id": 1,
+        "name": "Smartphone X",
+        "description": "Latest smartphone with cutting-edge technology",
+        "price": 999.99,
+        "is_available": True
+    },
+    {
+        "id": 2,
+        "name": "Laptop Y",
+        "description": "Powerful laptop for professionals",
+        "price": 1499.99,
+        "is_available": True
+    },
+    {
+        "id": 3,
+        "name": "Tablet Z",
+        "description": "Compact tablet for creativity",
+        "price": 599.99,
+        "is_available": False
+    }
+]
+
+# Define commands for MockRegistry
+class MockDispatcher:
+    """Mock for command dispatcher in example."""
+    
+    def __init__(self):
+        self.commands = {
+            "get_items": self.get_items,
+            "get_item": self.get_item,
+            "create_item": self.create_item,
+            "update_item": self.update_item,
+            "delete_item": self.delete_item,
+            "search_items": self.search_items,
+            "execute": self.execute_command
+        }
+        self.commands_info = {
+            "get_items": {
+                "description": "Get list of all items",
+                "params": {}
+            },
+            "get_item": {
+                "description": "Get item by ID",
+                "params": {
+                    "item_id": {
+                        "type": "integer",
+                        "description": "Item ID to search for",
+                        "required": True
+                    }
+                }
+            },
+            "create_item": {
+                "description": "Create new item",
+                "params": {
+                    "item": {
+                        "type": "object",
+                        "description": "Item data",
+                        "required": True
+                    }
+                }
+            },
+            "update_item": {
+                "description": "Update item by ID",
+                "params": {
+                    "item_id": {
+                        "type": "integer",
+                        "description": "Item ID to update",
+                        "required": True
+                    },
+                    "updated_data": {
+                        "type": "object",
+                        "description": "Updated data",
+                        "required": True
+                    }
+                }
+            },
+            "delete_item": {
+                "description": "Delete item by ID",
+                "params": {
+                    "item_id": {
+                        "type": "integer",
+                        "description": "Item ID to delete",
+                        "required": True
+                    }
+                }
+            },
+            "search_items": {
+                "description": "Search items by keyword",
+                "params": {
+                    "keyword": {
+                        "type": "string",
+                        "description": "Search keyword",
+                        "required": True
+                    }
+                }
+            },
+            "execute": {
+                "description": "Universal command for executing queries",
+                "params": {
+                    "query": {
+                        "type": "string",
+                        "description": "Query to execute",
+                        "required": False
+                    },
+                    "subcommand": {
+                        "type": "string",
+                        "description": "Subcommand to execute",
+                        "required": False
+                    }
+                }
+            }
+        }
+    
+    def execute(self, command, **params):
+        """Executes command with specified parameters."""
+        if command not in self.commands:
+            raise KeyError(f"Unknown command: {command}")
+        return self.commands[command](**params)
+        
+    def execute_command(self, **params):
+        """Universal method for executing commands."""
+        query = params.get("query", "")
+        subcommand = params.get("subcommand", "")
+        
+        # Debug logging
+        logger.info(f"Executing universal command with query={query}, subcommand={subcommand}, params={params}")
+        
+        # Handle different command types
+        if query.lower() in ["list", "all", "items"]:
+            # Return list of all items
+            return self.get_items()
+        elif query.lower() == "search" and "keyword" in params:
+            # Search by keyword
+            return self.search_items(params["keyword"])
+        elif query.isdigit() or (isinstance(query, int) and query > 0):
+            # If query looks like an ID, return item by ID
+            try:
+                return self.get_item(int(query))
+            except ValueError:
+                return {"error": f"Item with ID {query} not found"}
+        else:
+            # By default return information about available commands
+            commands = list(self.commands.keys())
+            return {
+                "available_commands": commands,
+                "message": "Use one of the available commands or specify query for executing query",
+                "received_params": params
+            }
+    
+    def get_valid_commands(self):
+        """Returns list of available commands."""
+        return list(self.commands.keys())
+    
+    def get_command_info(self, command):
+        """Returns information about command."""
+        return self.commands_info.get(command)
+    
+    def get_commands_info(self):
+        """Returns information about all commands."""
+        return self.commands_info
+    
+    # Command implementations
+    def get_items(self):
+        """Get list of all items."""
+        return items_db
+    
+    def get_item(self, item_id):
+        """Get item by ID."""
+        for item in items_db:
+            if item["id"] == item_id:
+                return item
+        raise ValueError(f"Item with ID {item_id} not found")
+    
+    def create_item(self, item):
+        """Create new item."""
+        # Find maximum ID
+        max_id = max([i["id"] for i in items_db]) if items_db else 0
+        # Create new item with increased ID
+        new_item = {**item, "id": max_id + 1}
+        items_db.append(new_item)
+        return new_item
+    
+    def update_item(self, item_id, updated_data):
+        """Update item by ID."""
+        for i, item in enumerate(items_db):
+            if item["id"] == item_id:
+                # Update item, keeping original ID
+                updated_item = {**item, **updated_data, "id": item_id}
+                items_db[i] = updated_item
+                return updated_item
+        raise ValueError(f"Item with ID {item_id} not found")
+    
+    def delete_item(self, item_id):
+        """Delete item by ID."""
+        for i, item in enumerate(items_db):
+            if item["id"] == item_id:
+                del items_db[i]
+                return {"message": f"Item with ID {item_id} successfully deleted"}
+        raise ValueError(f"Item with ID {item_id} not found")
+    
+    def search_items(self, keyword):
+        """Search items by keyword."""
+        keyword = keyword.lower()
+        return [
+            item for item in items_db
+            if keyword in item["name"].lower() or 
+               (item["description"] and keyword in item["description"].lower())
+        ]
+
+class CustomMockRegistry(MockRegistry):
+    """Custom command registry for example."""
+    
+    def __init__(self):
+        """Initialization with custom dispatcher."""
+        self.dispatcher = MockDispatcher()
+        self.generators = []
+
+def main():
+    """Main function to start server."""
+    # Create command registry
+    registry = CustomMockRegistry()
+    
+    # Create FastAPI object
+    app = FastAPI(
+        title="OpenAPI Server Example",
+        description="Example OpenAPI server with MCP Proxy Adapter integration",
+        version="1.0.0"
+    )
+    
+    # Configure CORS
+    from fastapi.middleware.cors import CORSMiddleware
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=["*"],  # Allow requests from all sources
+        allow_credentials=True,
+        allow_methods=["*"],  # Allow all methods
+        allow_headers=["*"],  # Allow all headers
+    )
+    
+    # Create MCP Proxy adapter with explicit endpoint
+    adapter = MCPProxyAdapter(registry, cmd_endpoint="/cmd")
+    
+    # Register adapter endpoints
+    adapter.register_endpoints(app)
+    
+    # Save MCP Proxy configuration to file
+    config_path = os.path.join(os.path.dirname(__file__), "mcp_proxy_config.json")
+    adapter.save_config_to_file(config_path)
+    logger.info(f"MCP Proxy configuration saved to {config_path}")
+    
+    # Define REST endpoints for example (not related to MCP Proxy)
+    @app.get("/")
+    def read_root():
+        """Root endpoint."""
+        return {
+            "message": "OpenAPI Server Example with MCP Proxy Adapter integration",
+            "endpoints": {
+                "items": "/items",
+                "item": "/items/{item_id}",
+                "search": "/items/search",
+                "mcp_proxy": "/cmd"
+            }
+        }
+    
+    @app.get("/items", response_model=List[Item])
+    def read_items():
+        """Get all items."""
+        return items_db
+    
+    @app.get("/items/{item_id}", response_model=Item)
+    def read_item(item_id: int = Path(..., description="Item ID", gt=0)):
+        """Get item by ID."""
+        try:
+            return registry.dispatcher.get_item(item_id)
+        except ValueError as e:
+            return {"error": str(e)}
+    
+    @app.post("/items", response_model=Item)
+    def create_new_item(item: Item = Body(..., description="Data of new item")):
+        """Create new item."""
+        return registry.dispatcher.create_item(item.model_dump())
+    
+    @app.put("/items/{item_id}", response_model=Item)
+    def update_existing_item(
+        item_id: int = Path(..., description="Item ID to update", gt=0),
+        item: Item = Body(..., description="Updated item data")
+    ):
+        """Update item by ID."""
+        try:
+            return registry.dispatcher.update_item(item_id, item.model_dump())
+        except ValueError as e:
+            return {"error": str(e)}
+    
+    @app.delete("/items/{item_id}")
+    def delete_existing_item(item_id: int = Path(..., description="Item ID to delete", gt=0)):
+        """Delete item by ID."""
+        try:
+            return registry.dispatcher.delete_item(item_id)
+        except ValueError as e:
+            return {"error": str(e)}
+    
+    @app.get("/items/search", response_model=List[Item])
+    def search_items_by_keyword(keyword: str = Query(..., description="Search keyword")):
+        """Search items by keyword."""
+        return registry.dispatcher.search_items(keyword)
+    
+    # Start server
+    uvicorn.run(app, host="0.0.0.0", port=8000)
+
+if __name__ == "__main__":
+    main() 

examples/project_structure_example.py

@@ -0,0 +1,47 @@
+"""
+Project Structure Example for MCPProxyAdapter
+
+- How to organize your project for clean integration
+- Where to place registry, commands, adapter
+- How to register endpoints in FastAPI
+
+Run:
+    python examples/project_structure_example.py
+"""
+import os
+import sys
+sys.path.insert(0, os.path.abspath(os.path.dirname(os.path.dirname(__file__))))
+from fastapi import FastAPI
+from mcp_proxy_adapter.adapter import MCPProxyAdapter
+
+# --- Command registry and commands ---
+class MyRegistry:
+    def __init__(self):
+        self.dispatcher = self
+        self.commands = {"hello": self.hello}
+        self.commands_info = {"hello": {"description": "Say hello", "params": {}}}
+    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, command, **params):
+        if command == "hello":
+            return {"message": "Hello, world!"}
+        raise KeyError(f"Unknown command: {command}")
+    def add_generator(self, generator):
+        pass
+    def hello(self):
+        """Say hello."""
+        return {"message": "Hello, world!"}
+
+# --- FastAPI app and adapter ---
+app = FastAPI()
+registry = MyRegistry()
+adapter = MCPProxyAdapter(registry)
+adapter.register_endpoints(app)
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(app, host="0.0.0.0", port=8000) 

examples/testing_example.py

@@ -0,0 +1,53 @@
+"""
+Testing Example for MCPProxyAdapter
+
+- How to write unit and integration tests for commands
+- How to test help and error handling
+- Best practices for test structure
+
+Run:
+    python examples/testing_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 = {"echo": self.echo}
+        self.commands_info = {"echo": {"description": "Echo input string", "params": {"text": {"type": "string", "description": "Text to echo", "required": True}}}}
+    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, command, **params):
+        if command == "echo":
+            return self.echo(**params)
+        raise KeyError(f"Unknown command: {command}")
+    def add_generator(self, generator):
+        pass
+    def echo(self, text: str) -> str:
+        """Echo input string."""
+        return text
+
+def test_echo():
+    registry = MyRegistry()
+    adapter = MCPProxyAdapter(registry)
+    # Unit test
+    assert registry.execute("echo", text="hi") == "hi"
+    # Integration test (simulate JSON-RPC)
+    class Request:
+        method = "echo"
+        params = {"text": "hello"}
+        id = 1
+    response = adapter.router.routes[0].endpoint(Request())
+    # Not a real FastAPI call, just for illustration
+    print("[TEST] Echo command passed.")
+
+if __name__ == "__main__":
+    test_echo()
+    print("All tests passed.") 

mcp_proxy_adapter/__init__.py

@@ -7,7 +7,7 @@ for AI models.
 """
 
 # Package version
-__version__ = '2.0.0'
+__version__ = '1.0.0'
 
 # Public API
 from .adapter import MCPProxyAdapter, configure_logger

mcp_proxy_adapter/models.py

@@ -6,42 +6,42 @@ from pydantic import BaseModel, Field
 
 class JsonRpcRequest(BaseModel):
     """Base model for JSON-RPC requests."""
-    jsonrpc: str = Field(default="2.0", description="JSON-RPC version")
+    jsonrpc: str = Field("2.0", description="JSON-RPC version")
     method: str = Field(..., description="Method name to call")
-    params: Dict[str, Any] = Field(default_factory=dict, description="Method parameters")
-    id: Optional[Union[str, int]] = Field(default=None, description="Request identifier")
+    params: Dict[str, Any] = Field({}, description="Method parameters")
+    id: Optional[Union[str, int]] = Field(None, description="Request identifier")
 
 class JsonRpcResponse(BaseModel):
     """Base model for JSON-RPC responses."""
-    jsonrpc: str = Field(default="2.0", description="JSON-RPC version")
-    result: Optional[Any] = Field(default=None, description="Method execution result")
-    error: Optional[Dict[str, Any]] = Field(default=None, description="Error information")
-    id: Optional[Union[str, int]] = Field(default=None, description="Request identifier")
+    jsonrpc: str = Field("2.0", description="JSON-RPC version")
+    result: Optional[Any] = Field(None, description="Method execution result")
+    error: Optional[Dict[str, Any]] = Field(None, description="Error information")
+    id: Optional[Union[str, int]] = Field(None, description="Request identifier")
     
 class CommandInfo(BaseModel):
     """Command information model."""
     name: str = Field(..., description="Command name")
-    description: str = Field(default="", description="Command description")
-    summary: Optional[str] = Field(default=None, description="Brief description")
-    parameters: Dict[str, Dict[str, Any]] = Field(default_factory=dict, description="Command parameters")
-    returns: Optional[Dict[str, Any]] = Field(default=None, description="Return value information")
+    description: str = Field("", description="Command description")
+    summary: Optional[str] = Field(None, description="Brief description")
+    parameters: Dict[str, Dict[str, Any]] = Field({}, description="Command parameters")
+    returns: Optional[Dict[str, Any]] = Field(None, description="Return value information")
 
 class CommandParameter(BaseModel):
     """Command parameter model."""
     type: str = Field(..., description="Parameter type")
-    description: str = Field(default="", description="Parameter description")
-    required: bool = Field(default=False, description="Whether the parameter is required")
-    default: Optional[Any] = Field(default=None, description="Default value")
-    enum: Optional[List[Any]] = Field(default=None, description="Possible values for enumeration")
+    description: str = Field("", description="Parameter description")
+    required: bool = Field(False, description="Whether the parameter is required")
+    default: Optional[Any] = Field(None, description="Default value")
+    enum: Optional[List[Any]] = Field(None, description="Possible values for enumeration")
 
 class MCPProxyTool(BaseModel):
     """Tool model for MCPProxy."""
     name: str = Field(..., description="Tool name") 
-    description: str = Field(default="", description="Tool description")
+    description: str = Field("", description="Tool description")
     parameters: Dict[str, Any] = Field(..., description="Tool parameters schema")
 
 class MCPProxyConfig(BaseModel):
     """Configuration model for MCPProxy."""
-    version: str = Field(default="1.0", description="Configuration version")
-    tools: List[MCPProxyTool] = Field(default_factory=list, description="List of tools")
-    routes: List[Dict[str, Any]] = Field(default_factory=list, description="Routes configuration") 
+    version: str = Field("1.0", description="Configuration version")
+    tools: List[MCPProxyTool] = Field([], description="List of tools")
+    routes: List[Dict[str, Any]] = Field([], description="Routes configuration") 

{mcp_proxy_adapter-2.0.2.dist-info → mcp_proxy_adapter-2.1.1.dist-info}/METADATA

@@ -1,15 +1,14 @@
 Metadata-Version: 2.4
 Name: mcp-proxy-adapter
-Version: 2.0.2
+Version: 2.1.1
 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: BugTracker, https://github.com/vasilyvz/mcp-proxy-adapter/issues
-Project-URL: Documentation, https://github.com/vasilyvz/mcp_proxy_adapter#readme
-Project-URL: Source, 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
@@ -22,7 +21,7 @@ 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<3.0.0,>=2.0.0
+Requires-Dist: pydantic>=2.0.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
@@ -262,11 +261,46 @@ MIT
 ## Documentation
 See [docs/](docs/) for detailed guides, architecture, and examples.
 
-## CI/CD & PyPI automation
-
-This project uses GitHub Actions for continuous integration and automated publishing to PyPI.
-
-- All tests are run on every push and pull request.
-- On push of a new tag (vX.Y.Z), the package is built and published to PyPI automatically.
-
-See `.github/workflows/publish.yml` for details. 
+## 📦 Примеры (examples/)
+
+- `help_usage.py` — базовое использование help-команды
+- `help_best_practices.py` — best practices для help
+- `project_structure_example.py` — структура проекта с MCPProxyAdapter
+- `docstring_and_schema_example.py` — как документировать команды для схемы
+- `testing_example.py` — как тестировать команды и интеграцию
+- `extension_example.py` — как расширять и кастомизировать команды и help
+
+## ✅ Чеклист для добавления новой команды
+
+1. **Реализовать функцию-команду** с подробным docstring (EN)
+2. **Добавить описание параметров** (type, description, required)
+3. **Добавить описание возврата** (docstring, тип)
+4. **Зарегистрировать команду** в registry/dispatcher
+5. **Добавить описание в get_commands_info** (использовать docstring)
+6. **Покрыть тестами** (unit/integration, edge-cases, ошибки)
+7. **Добавить пример использования** в examples/
+8. **Проверить интеграцию с help** (и с параметром, и без)
+9. **Проверить генерацию схемы/OpenAPI**
+10. **Документировать в README.md** (EN/RU)
+
+## 📦 Examples (EN)
+
+- `help_usage.py` — basic help command usage
+- `help_best_practices.py` — best practices for help
+- `project_structure_example.py` — project structure with MCPProxyAdapter
+- `docstring_and_schema_example.py` — how to document commands for schema
+- `testing_example.py` — how to test commands and integration
+- `extension_example.py` — how to extend/customize commands and help
+
+## ✅ Checklist for adding a new command
+
+1. **Implement the command function** with detailed docstring (EN)
+2. **Describe parameters** (type, description, required)
+3. **Describe return value** (docstring, type)
+4. **Register the command** in registry/dispatcher
+5. **Add description to get_commands_info** (use docstring)
+6. **Cover with tests** (unit/integration, edge-cases, errors)
+7. **Add usage example** to examples/
+8. **Check help integration** (with/without param)
+9. **Check schema/OpenAPI generation**
+10. **Document in README.md** (EN/RU)