mcp-proxy-adapter 3.0.0__tar.gz → 3.0.2__tar.gz

mcp_proxy_adapter-3.0.2/MANIFEST.in

@@ -0,0 +1,28 @@
+include README.md
+include LICENSE
+include requirements.txt
+include pyproject.toml
+include code_index.yaml
+include mcp_proxy_adapter/py.typed
+
+# Основные модули пакета
+recursive-include mcp_proxy_adapter *.py *.json *.yaml
+recursive-include mcp_proxy_adapter/api *.py
+recursive-include mcp_proxy_adapter/commands *.py
+recursive-include mcp_proxy_adapter/core *.py
+recursive-include mcp_proxy_adapter/schemas *.json *.yaml
+
+# Документация
+recursive-include docs *.md
+
+# Примеры
+recursive-include examples *.py *.json *.yaml *.md *.txt *.yml Dockerfile
+
+# Тесты
+recursive-include tests *.py
+
+# Исключения
+global-exclude __pycache__
+global-exclude *.py[cod]
+global-exclude *.so
+global-exclude .DS_Store 

{mcp_proxy_adapter-3.0.0/mcp_proxy_adapter.egg-info → mcp_proxy_adapter-3.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcp_proxy_adapter
-Version: 3.0.0
+Version: 3.0.2
 Summary: Reliable microservice with unified JSON-RPC endpoint
 Home-page: https://github.com/yourusername/mcp-proxy-adapter
 Author: MCP Team

mcp_proxy_adapter-3.0.2/docs/EN/AUTOMATED_PUBLISHING.md

@@ -0,0 +1,121 @@
+# Automated Package Publishing
+
+## Introduction
+
+This document describes the automated process for publishing the `mcp_proxy_adapter` package to PyPI using the developed scripts.
+
+## Publishing Scripts
+
+The project includes the following scripts to automate the publishing process:
+
+1. `scripts/publish_and_test.py` - main script for publishing and testing
+2. `scripts/test_install.py` - script for verifying the correctness of package installation
+
+## Publishing Process
+
+### 1. Preparation for Publishing
+
+Before publishing, make sure to check:
+- All necessary code changes have been made
+- Tests pass successfully
+- Documentation is updated
+
+### 2. Automated Publishing
+
+To publish the package, use the `publish_and_test.py` script:
+
+```bash
+# Update version and publish to main PyPI
+python scripts/publish_and_test.py --version 3.0.1
+
+# Publish to TestPyPI
+python scripts/publish_and_test.py --test
+
+# Build package only without publishing
+python scripts/publish_and_test.py --build-only
+```
+
+### 3. What the Publishing Script Does
+
+The `publish_and_test.py` script performs the following actions:
+
+1. **Version Update** (when the `--version` parameter is specified):
+   - Updates the version in `mcp_proxy_adapter/version.py`
+   - Adds a new entry to the `CHANGELOG.md` and `CHANGELOG_ru.md` files
+
+2. **Package Building**:
+   - Cleans previous builds
+   - Creates `.tar.gz` and `.whl` archives
+
+3. **Package Publishing**:
+   - Uploads the package to PyPI or TestPyPI
+
+4. **Installation Testing**:
+   - Creates an isolated environment
+   - Installs the package
+   - Verifies the correctness of the installation
+   - Tests project creation
+
+### 4. Manual Testing
+
+For manual testing of package installation, you can use the `test_install.py` script:
+
+```bash
+python scripts/test_install.py
+```
+
+## Requirements
+
+The following tools are required to use the publishing scripts:
+
+1. Python 3.6 or higher
+2. `build` and `twine` modules:
+   ```bash
+   pip install build twine
+   ```
+3. Configured access to PyPI (`.pypirc` file or environment variables)
+
+## Configuring Access to PyPI
+
+### 1. Using a Configuration File
+
+Create a `~/.pypirc` file with the following content:
+
+```ini
+[distutils]
+index-servers =
+    pypi
+    testpypi
+
+[pypi]
+username = __token__
+password = pypi-API-token
+
+[testpypi]
+repository = https://test.pypi.org/legacy/
+username = __token__
+password = testpypi-API-token
+```
+
+### 2. Using Environment Variables
+
+```bash
+export TWINE_USERNAME=__token__
+export TWINE_PASSWORD=pypi-API-token
+```
+
+## Troubleshooting
+
+### Publishing Error
+
+If an error occurs when publishing the package, check:
+1. Correctness of PyPI credentials
+2. Uniqueness of the package version (you cannot re-upload an already published version)
+3. Compliance of the package name with PyPI requirements
+
+### Installation Error
+
+If the package is installed but errors occur during import:
+1. Check if all necessary files are included in the package (MANIFEST.in)
+2. Make sure dependencies are correctly specified in setup.py or pyproject.toml
+3. Try installing the package in debug mode: `pip install -v mcp_proxy_adapter` 

{mcp_proxy_adapter-3.0.0 → mcp_proxy_adapter-3.0.2}/docs/EN/DOCUMENTATION_MAP.md

@@ -17,14 +17,20 @@ The following files must exist in both language versions:
 |---------------|---------|---------|
 | Project Rules | [PROJECT_RULES.md](./PROJECT_RULES.md) | [PROJECT_RULES.md](../RU/PROJECT_RULES.md) |
 | Naming Standards | [NAMING_STANDARDS.md](./NAMING_STANDARDS.md) | [NAMING_STANDARDS.md](../RU/NAMING_STANDARDS.md) |
-| Command Checklist | [COMMAND_CHECKLIST.md](./COMMAND_CHECKLIST.md) | [COMMAND_CHECKLIST.md](../RU/COMMAND_CHECKLIST.md) |
+| Project Architecture | [BASIC_ARCHITECTURE.md](./BASIC_ARCHITECTURE.md) | [BASIC_ARCHITECTURE.md](../RU/BASIC_ARCHITECTURE.md) |
+| Project Structure | [PROJECT_STRUCTURE.md](./PROJECT_STRUCTURE.md) | [PROJECT_STRUCTURE.md](../RU/PROJECT_STRUCTURE.md) |
+| Project Ideology | [PROJECT_IDEOLOGY.md](./PROJECT_IDEOLOGY.md) | [PROJECT_IDEOLOGY.md](../RU/PROJECT_IDEOLOGY.md) |
+| API Schema | [API_SCHEMA.md](./API_SCHEMA.md) | [API_SCHEMA.md](../RU/API_SCHEMA.md) |
 | Documentation Standards | [DOCUMENTATION_STANDARDS.md](./DOCUMENTATION_STANDARDS.md) | [DOCUMENTATION_STANDARDS.md](../RU/DOCUMENTATION_STANDARDS.md) |
-| Glossary | [GLOSSARY.md](./GLOSSARY.md) | [GLOSSARY.md](../RU/GLOSSARY.md) |
 | Command Template | [COMMAND_TEMPLATE.md](./COMMAND_TEMPLATE.md) | [COMMAND_TEMPLATE.md](../RU/COMMAND_TEMPLATE.md) |
-| Configuration Principles | [CONFIGURATION_PRINCIPLES.md](./CONFIGURATION_PRINCIPLES.md) | [CONFIGURATION_PRINCIPLES.md](../RU/CONFIGURATION_PRINCIPLES.md) |
-| Project Extension Guide | [PROJECT_EXTENSION_GUIDE.md](./PROJECT_EXTENSION_GUIDE.md) | [PROJECT_EXTENSION_GUIDE.md](../RU/PROJECT_EXTENSION_GUIDE.md) |
+| Command Checklist | [COMMAND_CHECKLIST.md](./COMMAND_CHECKLIST.md) | [COMMAND_CHECKLIST.md](../RU/COMMAND_CHECKLIST.md) |
+| Logging | [LOGGING_SYSTEM.md](./LOGGING_SYSTEM.md) | [LOGGING_SYSTEM.md](../RU/LOGGING_SYSTEM.md) |
 | Error Handling | [ERROR_HANDLING.md](./ERROR_HANDLING.md) | [ERROR_HANDLING.md](../RU/ERROR_HANDLING.md) |
+| Command Results | [COMMAND_RESULTS.md](./COMMAND_RESULTS.md) | [COMMAND_RESULTS.md](../RU/COMMAND_RESULTS.md) |
+| Configuration Principles | [CONFIGURATION_PRINCIPLES.md](./CONFIGURATION_PRINCIPLES.md) | [CONFIGURATION_PRINCIPLES.md](../RU/CONFIGURATION_PRINCIPLES.md) |
+| Project Extension | [PROJECT_EXTENSION_GUIDE.md](./PROJECT_EXTENSION_GUIDE.md) | [PROJECT_EXTENSION_GUIDE.md](../RU/PROJECT_EXTENSION_GUIDE.md) |
 | Publishing to PyPI | [PUBLISHING_TO_PYPI.md](./PUBLISHING_TO_PYPI.md) | [PUBLISHING_TO_PYPI.md](../RU/PUBLISHING_TO_PYPI.md) |
+| Automated Publishing | [AUTOMATED_PUBLISHING.md](./AUTOMATED_PUBLISHING.md) | [AUTOMATED_PUBLISHING.md](../RU/AUTOMATED_PUBLISHING.md) |
 
 ### 2.2. Command Documentation
 

{mcp_proxy_adapter-3.0.0 → mcp_proxy_adapter-3.0.2}/docs/EN/OPENAPI_SCHEMA.md

@@ -484,4 +484,52 @@ classDiagram
 4. **Compatibility**
    - Full support for JSON-RPC 2.0
    - Compliance with OpenAPI 3.0 specification
-   - Backward compatibility with existing clients 
+   - Backward compatibility with existing clients 
+
+## Customizing OpenAPI Schema Fields
+
+You can override the `title`, `description`, and `version` fields of the OpenAPI schema without editing the base schema file. This is done by passing the corresponding parameters to the FastAPI application and using the `custom_openapi` function.
+
+### Example
+
+```python
+from fastapi import FastAPI
+from mcp_proxy_adapter.custom_openapi import custom_openapi
+
+app = FastAPI(
+    title="Custom Project Title",
+    description="Custom project description for OpenAPI schema.",
+    version="2.1.0"
+)
+
+# Use custom OpenAPI schema
+default_openapi = app.openapi
+app.openapi = lambda: custom_openapi(app)
+
+# Now /openapi.json will reflect the custom title, description, and version
+```
+
+**Advantages:**
+- No need to manually edit the base OpenAPI schema file.
+- Flexible for use in different projects.
+- Standard FastAPI fields are used for customization.
+
+### Test Example
+
+A test is provided to ensure that custom `title`, `description`, and `version` are correctly set in the OpenAPI schema:
+
+```python
+def test_custom_openapi_schema_fields():
+    from fastapi import FastAPI
+    from mcp_proxy_adapter.custom_openapi import custom_openapi
+
+    app = FastAPI(
+        title="Custom Title",
+        description="Custom Description",
+        version="9.9.9"
+    )
+    schema = custom_openapi(app)
+    assert schema["info"]["title"] == "Custom Title"
+    assert schema["info"]["description"] == "Custom Description"
+    assert schema["info"]["version"] == "9.9.9"
+``` 

mcp_proxy_adapter-3.0.2/docs/EN/development/COMMAND_METADATA_ENHANCEMENT.md

@@ -0,0 +1,350 @@
+# Enhancing Command Metadata
+
+## Problem
+
+Currently, the command registry stores command classes, but does not provide a convenient way to access command metadata without creating an instance of the command. Metadata about commands should be more readily available and structured to:
+
+1. Support better documentation 
+2. Provide AI tools with rich information about available commands
+3. Improve the help command's output
+4. Enable better introspection capabilities
+
+## Proposed Solution
+
+Enhance the Command class and CommandRegistry to support comprehensive metadata retrieval:
+
+1. Add a `get_metadata()` class method to the base Command class
+2. Update the CommandRegistry to provide access to command metadata
+3. Keep the existing command class storage for backward compatibility
+
+## Implementation Plan
+
+### 1. Enhance the Command Base Class
+
+Add a new `get_metadata()` class method to the Command base class:
+
+```python
+@classmethod
+def get_metadata(cls) -> Dict[str, Any]:
+    """
+    Returns comprehensive metadata about the command.
+    
+    This provides a single entry point for all command metadata.
+    
+    Returns:
+        Dict with command metadata
+    """
+    # Get docstring and format it
+    doc = cls.__doc__ or ""
+    description = inspect.cleandoc(doc) if doc else ""
+    
+    # Extract first line for summary
+    summary = description.split("\n")[0] if description else ""
+    
+    # Get parameter info
+    param_info = cls.get_param_info()
+    
+    # Generate example(s) based on parameters
+    examples = cls._generate_examples(param_info)
+    
+    return {
+        "name": cls.name,
+        "summary": summary,
+        "description": description,
+        "params": param_info,
+        "examples": examples,
+        "schema": cls.get_schema(),
+        "result_schema": cls.get_result_schema(),
+        "result_class": cls.result_class.__name__ if hasattr(cls, "result_class") else None,
+    }
+
+@classmethod
+def _generate_examples(cls, params: Dict[str, Dict[str, Any]]) -> List[Dict[str, Any]]:
+    """
+    Generate usage examples for the command based on its parameters.
+    
+    Args:
+        params: Command parameters information
+        
+    Returns:
+        List of examples
+    """
+    examples = []
+    
+    # Simple example without parameters if all parameters are optional
+    if not any(param.get("required", False) for param in params.values()):
+        examples.append({
+            "command": cls.name,
+            "description": f"Call the {cls.name} command without parameters"
+        })
+    
+    # Example with all required parameters
+    required_params = {k: v for k, v in params.items() if v.get("required", False)}
+    if required_params:
+        example_params = {}
+        for param_name, param_info in required_params.items():
+            # Generate appropriate example value based on parameter type
+            param_type = param_info.get("type", "")
+            if "str" in param_type.lower():
+                example_params[param_name] = f"example_{param_name}"
+            elif "int" in param_type.lower():
+                example_params[param_name] = 123
+            elif "float" in param_type.lower():
+                example_params[param_name] = 123.45
+            elif "bool" in param_type.lower():
+                example_params[param_name] = True
+            else:
+                example_params[param_name] = f"value_for_{param_name}"
+        
+        examples.append({
+            "command": cls.name,
+            "params": example_params,
+            "description": f"Call the {cls.name} command with required parameters"
+        })
+    
+    # Add an example with all parameters if there are optional ones
+    optional_params = {k: v for k, v in params.items() if not v.get("required", False)}
+    if optional_params and required_params:
+        full_example_params = dict(example_params) if 'example_params' in locals() else {}
+        
+        for param_name, param_info in optional_params.items():
+            # Get default value or generate appropriate example
+            if "default" in param_info:
+                full_example_params[param_name] = param_info["default"]
+            else:
+                # Generate appropriate example value based on parameter type
+                param_type = param_info.get("type", "")
+                if "str" in param_type.lower():
+                    full_example_params[param_name] = f"optional_{param_name}"
+                elif "int" in param_type.lower():
+                    full_example_params[param_name] = 456
+                elif "float" in param_type.lower():
+                    full_example_params[param_name] = 45.67
+                elif "bool" in param_type.lower():
+                    full_example_params[param_name] = False
+                else:
+                    full_example_params[param_name] = f"optional_value_for_{param_name}"
+        
+        examples.append({
+            "command": cls.name,
+            "params": full_example_params,
+            "description": f"Call the {cls.name} command with all parameters"
+        })
+    
+    return examples
+```
+
+### 2. Enhance the CommandRegistry
+
+Update the CommandRegistry to provide access to command metadata:
+
+```python
+def get_command_metadata(self, command_name: str) -> Dict[str, Any]:
+    """
+    Get comprehensive metadata for a command.
+    
+    Args:
+        command_name: Name of the command
+        
+    Returns:
+        Dict with command metadata
+        
+    Raises:
+        NotFoundError: If command is not found
+    """
+    command_class = self.get_command(command_name)
+    return command_class.get_metadata()
+
+def get_all_metadata(self) -> Dict[str, Dict[str, Any]]:
+    """
+    Get metadata for all registered commands.
+    
+    Returns:
+        Dict with command names as keys and metadata as values
+    """
+    metadata = {}
+    for name, command_class in self._commands.items():
+        metadata[name] = command_class.get_metadata()
+    return metadata
+```
+
+### 3. Update the Help Command
+
+Enhance the HelpCommand to use the new metadata:
+
+```python
+async def execute(self, cmdname: Optional[str] = None) -> HelpResult:
+    """
+    Execute help command.
+    
+    Args:
+        cmdname: Name of the command to get information about (optional)
+        
+    Returns:
+        HelpResult: Help command result
+        
+    Raises:
+        NotFoundError: If specified command not found
+    """
+    # If cmdname is provided, return information about specific command
+    if cmdname:
+        try:
+            # Get command metadata from registry
+            command_metadata = registry.get_command_metadata(cmdname)
+            return HelpResult(command_info=command_metadata)
+        except NotFoundError:
+            # If command not found, raise error
+            raise NotFoundError(f"Command '{cmdname}' not found")
+    
+    # Otherwise, return information about all available commands
+    # and tool metadata
+    
+    # Get metadata for all commands
+    all_metadata = registry.get_all_metadata()
+    
+    # Prepare response format with tool metadata
+    result = {
+        "tool_info": {
+            "name": "MCP-Proxy API Service",
+            "description": "JSON-RPC API for executing microservice commands",
+            "version": "1.0.0"
+        },
+        "help_usage": {
+            "description": "Get information about commands",
+            "examples": [
+                {"command": "help", "description": "List all available commands"},
+                {"command": "help", "params": {"cmdname": "command_name"}, "description": "Get detailed info about a specific command"}
+            ]
+        },
+        "commands": {}
+    }
+    
+    # Add command summaries
+    for name, metadata in all_metadata.items():
+        result["commands"][name] = {
+            "summary": metadata["summary"],
+            "params_count": len(metadata["params"])
+        }
+    
+    return HelpResult(commands_info=result)
+```
+
+### 4. Update the HelpResult Class
+
+```python
+class HelpResult(CommandResult):
+    """
+    Result of the help command execution.
+    """
+    
+    def __init__(self, commands_info: Optional[Dict[str, Any]] = None, command_info: Optional[Dict[str, Any]] = None):
+        """
+        Initialize help command result.
+        
+        Args:
+            commands_info: Information about all commands (for request without parameters)
+            command_info: Information about a specific command (for request with cmdname parameter)
+        """
+        self.commands_info = commands_info
+        self.command_info = command_info
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """
+        Convert result to dictionary.
+        
+        Returns:
+            Dict[str, Any]: Result as dictionary
+        """
+        if self.command_info:
+            return {
+                "cmdname": self.command_info["name"],
+                "info": {
+                    "description": self.command_info["description"],
+                    "summary": self.command_info["summary"],
+                    "params": self.command_info["params"],
+                    "examples": self.command_info["examples"]
+                }
+            }
+        
+        # For list of all commands, return as is (already formatted)
+        result = self.commands_info.copy()
+        
+        # Add total count and usage note
+        result["total"] = len(result["commands"])
+        result["note"] = "To get detailed information about a specific command, call help with parameter: POST /cmd {\"command\": \"help\", \"params\": {\"cmdname\": \"<command_name>\"}}. Only the 'cmdname' parameter is supported."
+        
+        return result
+```
+
+## Expected Results
+
+### 1. Detailed command information
+
+```json
+{
+  "cmdname": "echo",
+  "info": {
+    "description": "Command that echoes back input message.\n\nThis command demonstrates simple parameter handling.",
+    "summary": "Command that echoes back input message",
+    "params": {
+      "message": {
+        "name": "message",
+        "required": true,
+        "type": "str",
+        "description": "Message to echo back"
+      }
+    },
+    "examples": [
+      {
+        "command": "echo",
+        "params": {"message": "example_message"},
+        "description": "Call the echo command with required parameters"
+      }
+    ]
+  }
+}
+```
+
+### 2. Enhanced command list with metadata
+
+```json
+{
+  "tool_info": {
+    "name": "MCP-Proxy API Service",
+    "description": "JSON-RPC API for executing microservice commands",
+    "version": "1.0.0"
+  },
+  "help_usage": {
+    "description": "Get information about commands",
+    "examples": [
+      {"command": "help", "description": "List all available commands"},
+      {"command": "help", "params": {"cmdname": "command_name"}, "description": "Get detailed info about a specific command"}
+    ]
+  },
+  "commands": {
+    "help": {
+      "summary": "Command for getting help information about available commands",
+      "params_count": 1
+    },
+    "echo": {
+      "summary": "Command that echoes back input message",
+      "params_count": 1
+    },
+    "math": {
+      "summary": "Command for performing basic math operations",
+      "params_count": 3
+    }
+  },
+  "total": 3,
+  "note": "To get detailed information about a specific command, call help with parameter: POST /cmd {\"command\": \"help\", \"params\": {\"cmdname\": \"<command_name>\"}}. Only the 'cmdname' parameter is supported."
+}
+```
+
+## Benefits
+
+1. More comprehensive command metadata
+2. Better documentation capabilities
+3. Enhanced help command output with usage examples
+4. Improved API self-description
+5. Better support for AI tools integration
+6. Cleaner separation of metadata and implementation