Add project code

Author: peteski22

Makefile

@@ -0,0 +1,34 @@
+.PHONY: help
+help: ## Show this help message
+	@echo "Available targets:"
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[36m%-20s\033[0m %s\n", $$1, $$2}'
+
+.PHONY: ensure-scripts-exec
+ensure-scripts-exec: ## Make scripts executable
+	chmod +x scripts/*
+
+.PHONY: setup
+setup: ensure-scripts-exec ## Setup development environment (installs uv and syncs dependencies)
+	./scripts/setup_uv.sh
+
+.PHONY: test
+test: ## Run tests with pytest
+	uv run pytest tests/ -v
+
+.PHONY: lint
+lint: ## Run pre-commit hooks on all files
+	uv run pre-commit run --all-files
+
+.PHONY: generate-protos
+generate-protos: ensure-scripts-exec ## Download proto files and generate Python code
+	./scripts/generate_protos.sh
+
+.PHONY: clean
+clean: ## Clean generated files and caches
+	rm -rf tmp/
+	find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true
+	find . -type f -name "*.pyc" -delete
+	find . -type d -name ".pytest_cache" -exec rm -rf {} + 2>/dev/null || true
+	find . -type d -name ".ruff_cache" -exec rm -rf {} + 2>/dev/null || true
+	find . -type d -name "*.egg-info" -exec rm -rf {} + 2>/dev/null || true
+	rm -rf build/ dist/

pyproject.toml

@@ -0,0 +1,50 @@
+[project]
+name = "mcpd-plugins"
+dynamic = ["version"]
+description = "mcpd plugins Python SDK"
+readme = "README.md"
+license = { text = "Apache-2.0" }
+requires-python = ">=3.11"
+dependencies = [
+    "grpcio>=1.68.0",
+    "protobuf>=5.29.0",
+]
+
+[dependency-groups]
+dev = [
+    "grpcio-tools>=1.68.0",
+    "debugpy>=1.8.14",
+]
+lint = [
+    "pre-commit>=4.2.0",
+    "ruff>=0.11.13",
+]
+tests = [
+    "pytest>=8.3.5",
+    "pytest-asyncio>=0.25.2",
+    "setuptools>=80.9.0",
+    "setuptools-scm>=8.3.1",
+]
+all = [
+    { include-group = "dev" },
+    { include-group = "lint" },
+    { include-group = "tests" },
+]
+
+[build-system]
+requires = ["setuptools>=48", "setuptools_scm[toml]>=6.3.1"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+exclude = ["tests", "tests.*"]
+namespaces = false
+
+[tool.setuptools.package-data]
+mcpd_plugins = ["py.typed"]
+
+[tool.setuptools_scm]
+write_to = "src/mcpd_plugins/_version.py"

src/mcpd_plugins/__init__.py

@@ -0,0 +1,50 @@
+"""mcpd-plugins: Python SDK for building mcpd plugins.
+
+This SDK provides a simple way to create plugins for the mcpd plugin system using gRPC.
+Plugins extend the BasePlugin class and override only the methods they need.
+
+Example:
+    ```python
+    import asyncio
+    from mcpd_plugins import BasePlugin, serve
+    from mcpd_plugins.v1.plugins.plugin_pb2 import Capabilities, Flow, Metadata
+
+    class MyPlugin(BasePlugin):
+        async def GetMetadata(self, request, context):
+            return Metadata(
+                name="my-plugin",
+                version="1.0.0",
+                description="A simple example plugin"
+            )
+
+        async def GetCapabilities(self, request, context):
+            return Capabilities(flows=[Flow.FLOW_REQUEST])
+
+        async def HandleRequest(self, request, context):
+            # Add custom header
+            response = HTTPResponse(**{"continue": True})
+            response.headers["X-My-Plugin"] = "processed"
+            return response
+
+    if __name__ == "__main__":
+        asyncio.run(serve(MyPlugin()))
+    ```
+"""
+
+from mcpd_plugins.base_plugin import BasePlugin
+from mcpd_plugins.exceptions import ConfigurationError, PluginError, ServerError
+from mcpd_plugins.server import serve
+
+try:
+    from mcpd_plugins._version import version as __version__
+except ImportError:
+    __version__ = "0.0.0+unknown"
+
+__all__ = [
+    "BasePlugin",
+    "serve",
+    "PluginError",
+    "ConfigurationError",
+    "ServerError",
+    "__version__",
+]

src/mcpd_plugins/base_plugin.py

@@ -0,0 +1,154 @@
+"""BasePlugin class providing default implementations for all plugin methods."""
+
+from google.protobuf.empty_pb2 import Empty
+from grpc import ServicerContext
+
+from mcpd_plugins.v1.plugins.plugin_pb2 import (
+    Capabilities,
+    HTTPRequest,
+    HTTPResponse,
+    Metadata,
+    PluginConfig,
+)
+from mcpd_plugins.v1.plugins.plugin_pb2_grpc import PluginServicer
+
+
+class BasePlugin(PluginServicer):
+    """Base class for mcpd plugins with sensible default implementations.
+
+    Developers should extend this class and override only the methods they need.
+    All methods are async (using async/await pattern) to support asynchronous operations.
+
+    Example:
+        ```python
+        class MyPlugin(BasePlugin):
+            async def GetMetadata(self, request: Empty, context: ServicerContext) -> Metadata:
+                return Metadata(
+                    name="my-plugin",
+                    version="1.0.0",
+                    description="My custom plugin"
+                )
+
+            async def HandleRequest(self, request: HTTPRequest, context: ServicerContext) -> HTTPResponse:
+                # Process the request
+                response = HTTPResponse(**{"continue": True})
+                response.headers["X-My-Plugin"] = "processed"
+                return response
+        ```
+    """
+
+    async def Configure(self, request: PluginConfig, context: ServicerContext) -> Empty:
+        """Configure the plugin with the provided settings.
+
+        Default implementation does nothing. Override to handle configuration.
+
+        Args:
+            request: Configuration settings from the host.
+            context: gRPC context for the request.
+
+        Returns:
+            Empty message indicating successful configuration.
+        """
+        return Empty()
+
+    async def Stop(self, request: Empty, context: ServicerContext) -> Empty:
+        """Stop the plugin and clean up resources.
+
+        Default implementation does nothing. Override to handle cleanup.
+
+        Args:
+            request: Empty request message.
+            context: gRPC context for the request.
+
+        Returns:
+            Empty message indicating successful shutdown.
+        """
+        return Empty()
+
+    async def GetMetadata(self, request: Empty, context: ServicerContext) -> Metadata:
+        """Get plugin metadata (name, version, description).
+
+        Default implementation returns basic metadata. Override to provide actual values.
+
+        Args:
+            request: Empty request message.
+            context: gRPC context for the request.
+
+        Returns:
+            Metadata containing plugin information.
+        """
+        return Metadata(
+            name="base-plugin",
+            version="0.0.0",
+            description="Base plugin implementation",
+        )
+
+    async def GetCapabilities(self, request: Empty, context: ServicerContext) -> Capabilities:
+        """Get plugin capabilities (supported flows).
+
+        Default implementation returns no capabilities. Must override to declare supported flows.
+
+        Args:
+            request: Empty request message.
+            context: gRPC context for the request.
+
+        Returns:
+            Capabilities message listing supported flows.
+        """
+        return Capabilities()
+
+    async def CheckHealth(self, request: Empty, context: ServicerContext) -> Empty:
+        """Health check endpoint.
+
+        Default implementation returns healthy status. Override if custom health checks needed.
+
+        Args:
+            request: Empty request message.
+            context: gRPC context for the request.
+
+        Returns:
+            Empty message indicating healthy status.
+        """
+        return Empty()
+
+    async def CheckReady(self, request: Empty, context: ServicerContext) -> Empty:
+        """Readiness check endpoint.
+
+        Default implementation returns ready status. Override if custom readiness checks needed.
+
+        Args:
+            request: Empty request message.
+            context: gRPC context for the request.
+
+        Returns:
+            Empty message indicating ready status.
+        """
+        return Empty()
+
+    async def HandleRequest(self, request: HTTPRequest, context: ServicerContext) -> HTTPResponse:
+        """Handle incoming HTTP request.
+
+        Default implementation passes through unchanged (continue=True).
+
+        Args:
+            request: The incoming HTTP request to process.
+            context: gRPC context for the request.
+
+        Returns:
+            HTTPResponse indicating how to proceed (continue, modify, or reject).
+        """
+        return HTTPResponse(**{"continue": True})
+
+    async def HandleResponse(self, request: HTTPResponse, context: ServicerContext) -> HTTPResponse:
+        """Handle outgoing HTTP response.
+
+        Default implementation passes through unchanged (continue=True).
+
+        Args:
+            request: The outgoing HTTP response to process.
+            context: gRPC context for the request.
+
+        Returns:
+            HTTPResponse indicating how to proceed (continue or modify).
+        """
+        return HTTPResponse(**{"continue": True})

src/mcpd_plugins/exceptions.py

@@ -0,0 +1,19 @@
+"""Custom exception classes for mcpd-plugins SDK."""
+
+
+class PluginError(Exception):
+    """Base exception class for all plugin-related errors."""
+
+    pass
+
+
+class ConfigurationError(PluginError):
+    """Exception raised for configuration-related errors."""
+
+    pass
+
+
+class ServerError(PluginError):
+    """Exception raised for server startup or shutdown errors."""
+
+    pass