mcp-proxy-adapter 2.0.1__tar.gz → 2.1.0__tar.gz

{mcp_proxy_adapter-2.0.1 → mcp_proxy_adapter-2.1.0}/MANIFEST.in

@@ -6,7 +6,6 @@ include code_index.yaml
 recursive-include docs *.md
 recursive-include examples *.py *.json
 recursive-include tests *.py
-recursive-include src *
 global-exclude __pycache__
 global-exclude *.py[cod]
 global-exclude *.so

{mcp_proxy_adapter-2.0.1/src/mcp_proxy_adapter.egg-info → mcp_proxy_adapter-2.1.0}/PKG-INFO

@@ -1,15 +1,14 @@
 Metadata-Version: 2.4
 Name: mcp-proxy-adapter
-Version: 2.0.1
+Version: 2.1.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: 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,>=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
@@ -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) 

{mcp_proxy_adapter-2.0.1 → mcp_proxy_adapter-2.1.0}/README.md

@@ -229,11 +229,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) 

mcp_proxy_adapter-2.1.0/examples/docstring_and_schema_example.py

@@ -0,0 +1,60 @@
+"""
+Docstring and Schema Example for MCPProxyAdapter
+
+- How to write docstrings for commands
+- How docstrings are used in OpenAPI/schema
+- Best practices for documenting parameters and return values
+
+Run:
+    python examples/docstring_and_schema_example.py
+"""
+import os
+import sys
+sys.path.insert(0, os.path.abspath(os.path.dirname(os.path.dirname(__file__))))
+from src.adapter import MCPProxyAdapter
+
+class MyRegistry:
+    def __init__(self):
+        self.dispatcher = self
+        self.commands = {"sum": self.sum_numbers}
+        self.commands_info = {
+            "sum": {
+                "description": self.sum_numbers.__doc__,
+                "params": {
+                    "a": {"type": "integer", "description": "First number", "required": True},
+                    "b": {"type": "integer", "description": "Second number", "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 == "sum":
+            return self.sum_numbers(**params)
+        raise KeyError(f"Unknown command: {command}")
+    def add_generator(self, generator):
+        pass
+    def sum_numbers(self, a: int, b: int) -> int:
+        """
+        Returns the sum of two numbers.
+        
+        Args:
+            a (int): First number
+            b (int): Second number
+        
+        Returns:
+            int: The sum of a and b
+        """
+        return a + b
+
+if __name__ == "__main__":
+    registry = MyRegistry()
+    adapter = MCPProxyAdapter(registry)
+    # Print OpenAPI schema (simulated)
+    schema = adapter.generate_mcp_proxy_config()
+    print("=== Tool description from docstring ===")
+    print(schema.tools[0].description) 

mcp_proxy_adapter-2.1.0/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 src.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")) 

mcp_proxy_adapter-2.1.0/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 src.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() 

mcp_proxy_adapter-2.1.0/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 src.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")) 

mcp_proxy_adapter-2.1.0/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 src.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) 

mcp_proxy_adapter-2.1.0/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 src.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-2.0.1 → mcp_proxy_adapter-2.1.0}/pyproject.toml

@@ -1,10 +1,10 @@
 [build-system]
-requires = ["setuptools", "wheel"]
+requires = ["setuptools>=42", "wheel"]
 build-backend = "setuptools.build_meta"
 
 [project]
 name = "mcp-proxy-adapter"
-version = "2.0.1"
+version = "2.1.0"
 description = "Adapter for exposing Command Registry commands as tools for AI models via MCP Proxy."
 readme = "README.md"
 requires-python = ">=3.9"
@@ -24,17 +24,16 @@ classifiers = [
 ]
 dependencies = [
     "fastapi>=0.95.0,<1.0.0",
-    "pydantic>=2.0.0,<3.0.0",
+    "pydantic>=1.10.0,<2.0.0",
     "uvicorn>=0.22.0,<1.0.0",
     "docstring-parser>=0.15,<1.0.0",
     "typing-extensions>=4.5.0,<5.0.0",
 ]
 
 [project.urls]
-Homepage = "https://github.com/vasilyvz/mcp-proxy-adapter"
-BugTracker = "https://github.com/vasilyvz/mcp-proxy-adapter/issues"
-Documentation = "https://github.com/vasilyvz/mcp_proxy_adapter#readme"
-Source = "https://github.com/vasilyvz/mcp_proxy_adapter"
+"Homepage" = "https://github.com/vasilyvz/mcp-proxy-adapter"
+"Bug Tracker" = "https://github.com/vasilyvz/mcp-proxy-adapter/issues"
+"Documentation" = "https://github.com/vasilyvz/mcp-proxy-adapter/tree/main/docs"
 
 [tool.setuptools]
 package-dir = {"" = "src"}
@@ -42,9 +41,9 @@ package-dir = {"" = "src"}
 [tool.setuptools.packages.find]
 where = ["src"]
 
+[tool.setuptools.package-data]
+"examples" = ["*.py", "*.json"]
+
 [tool.pytest.ini_options]
-addopts = "-ra -q"
-filterwarnings = [
-    "ignore::DeprecationWarning",
-    "ignore::PendingDeprecationWarning"
-] 
+asyncio_mode = "strict"
+asyncio_default_fixture_loop_scope = "function" 

mcp_proxy_adapter-2.1.0/requirements.txt

@@ -0,0 +1,5 @@
+fastapi>=0.95.0,<1.0.0
+pydantic>=1.10.0,<2.0.0
+uvicorn>=0.22.0,<1.0.0
+docstring-parser>=0.15,<1.0.0
+typing-extensions>=4.5.0,<5.0.0 

{mcp_proxy_adapter-2.0.1 → mcp_proxy_adapter-2.1.0}/setup.py

@@ -10,14 +10,11 @@ with open(os.path.join(here, 'README.md'), encoding='utf-8') as f:
 
 # Read requirements.txt
 with open(os.path.join(here, 'requirements.txt'), encoding='utf-8') as f:
-    requirements = [
-        line.replace('pydantic>=1.10.0,<2.0.0', 'pydantic>=2.0.0,<3.0.0')
-        for line in f.read().splitlines()
-    ]
+    requirements = f.read().splitlines()
 
 setup(
     name="mcp-proxy-adapter",
-    version="2.0.0",
+    version="2.1.0",
     description="Adapter for exposing Command Registry commands as tools for AI models via MCP Proxy.",
     long_description=long_description,
     long_description_content_type="text/markdown",
@@ -42,6 +39,9 @@ setup(
     project_urls={
         "Bug Reports": "https://github.com/vasilyvz/mcp-proxy-adapter/issues",
         "Source": "https://github.com/vasilyvz/mcp-proxy-adapter",
-        "Documentation": "https://github.com/vasilyvz/mcp_proxy_adapter#readme",
+    },
+    include_package_data=True,
+    package_data={
+        "examples": ["*.py", "*.json"],
     },
 )