fastapi-startkit 0.29.0__tar.gz → 0.30.0__tar.gz

{fastapi_startkit-0.29.0 → fastapi_startkit-0.30.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: fastapi-startkit
-Version: 0.29.0
+Version: 0.30.0
 Summary: Fastapi Starter kit components
 Author: Bedram Tamang
 Author-email: Bedram Tamang <tmgbedu@gmail.com>

{fastapi_startkit-0.29.0 → fastapi_startkit-0.30.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fastapi-startkit"
-version = "0.29.0"
+version = "0.30.0"
 description = "Fastapi Starter kit components"
 authors = [
     {name = "Bedram Tamang", email = "tmgbedu@gmail.com"}

fastapi_startkit-0.30.0/src/fastapi_startkit/mcp/__init__.py

@@ -0,0 +1,25 @@
+"""FastAPI Startkit MCP module.
+
+Provides class-based building blocks for Model Context Protocol (MCP) servers
+that can be mounted directly on any FastAPI application.
+"""
+
+from .argument import Argument
+from .prompt import Prompt
+from .request import JsonRpcRequest
+from .resource import Resource
+from .response import Response
+from .server import Server
+from .tool import Tool
+from .providers.mcp_provider import McpProvider
+
+__all__ = [
+    "Argument",
+    "JsonRpcRequest",
+    "McpProvider",
+    "Prompt",
+    "Resource",
+    "Response",
+    "Server",
+    "Tool",
+]

fastapi_startkit-0.30.0/src/fastapi_startkit/mcp/argument.py

@@ -0,0 +1,20 @@
+"""Argument dataclass for MCP prompt arguments."""
+
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+@dataclass
+class Argument:
+    """Represents a single argument accepted by a Prompt."""
+
+    name: str
+    description: Optional[str] = field(default=None)
+    required: bool = field(default=False)
+
+    def to_json(self) -> dict:
+        """Serialise to MCP-compatible JSON."""
+        data: dict = {"name": self.name, "required": self.required}
+        if self.description is not None:
+            data["description"] = self.description
+        return data

fastapi_startkit-0.30.0/src/fastapi_startkit/mcp/prompt.py

@@ -0,0 +1,45 @@
+"""Abstract base class for MCP prompts."""
+
+from abc import ABC, abstractmethod
+from typing import Optional
+
+from .argument import Argument
+from .response import Response
+
+
+class Prompt(ABC):
+    """Base class for MCP prompts.
+
+    Subclasses must set ``name`` and implement ``handle()``.
+    Override ``arguments()`` to declare accepted arguments.
+    Override ``should_register()`` to conditionally skip registration.
+    """
+
+    name: str
+    description: Optional[str] = None
+    title: Optional[str] = None
+
+    def arguments(self) -> list[Argument]:
+        """Return the list of arguments this prompt accepts."""
+        return []
+
+    def should_register(self) -> bool:
+        """Return False to prevent this prompt from being registered."""
+        return True
+
+    @abstractmethod
+    async def handle(self, arguments: dict) -> Response:
+        """Render the prompt with the given arguments and return a Response."""
+        raise NotImplementedError
+
+    def to_json(self) -> dict:
+        """Serialise to the MCP prompts/list format."""
+        data: dict = {"name": self.name}
+        if self.description is not None:
+            data["description"] = self.description
+        if self.title is not None:
+            data["title"] = self.title
+        args = self.arguments()
+        if args:
+            data["arguments"] = [arg.to_json() for arg in args]
+        return data

fastapi_startkit-0.30.0/src/fastapi_startkit/mcp/protocol.py

@@ -0,0 +1,143 @@
+"""Internal JSON-RPC 2.0 dispatcher for MCP."""
+
+from typing import Any, Optional, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .server import Server
+
+
+MCP_PROTOCOL_VERSION = "2024-11-05"
+
+
+class Protocol:
+    """Dispatches JSON-RPC 2.0 method calls to MCP handlers.
+
+    Handles the following methods:
+    - initialize
+    - tools/list
+    - tools/call
+    - prompts/list
+    - prompts/get
+    - resources/list
+    - resources/read
+    """
+
+    def __init__(self, server: "Server") -> None:
+        self._server = server
+
+    # ------------------------------------------------------------------
+    # Public dispatch entry point
+    # ------------------------------------------------------------------
+
+    async def dispatch(self, method: str, params: Optional[dict], request_id: Any) -> dict:
+        """Dispatch a JSON-RPC method and return a full JSON-RPC response dict."""
+        handler = {
+            "initialize": self._initialize,
+            "tools/list": self._tools_list,
+            "tools/call": self._tools_call,
+            "prompts/list": self._prompts_list,
+            "prompts/get": self._prompts_get,
+            "resources/list": self._resources_list,
+            "resources/read": self._resources_read,
+        }.get(method)
+
+        if handler is None:
+            return self._error(request_id, -32601, f"Method not found: {method}")
+
+        try:
+            result = await handler(params or {})
+            return {"jsonrpc": "2.0", "id": request_id, "result": result}
+        except Exception as exc:  # pragma: no cover
+            return self._error(request_id, -32000, str(exc))
+
+    # ------------------------------------------------------------------
+    # Handlers
+    # ------------------------------------------------------------------
+
+    async def _initialize(self, params: dict) -> dict:
+        server = self._server
+        result: dict = {
+            "protocolVersion": MCP_PROTOCOL_VERSION,
+            "serverInfo": {"name": server.name, "version": "1.0"},
+            "capabilities": {
+                "tools": {"listChanged": False},
+                "prompts": {"listChanged": False},
+                "resources": {"listChanged": False},
+            },
+        }
+        if getattr(server, "description", None):
+            result["description"] = server.description
+        if getattr(server, "instructions", None):
+            result["instructions"] = server.instructions
+        return result
+
+    async def _tools_list(self, params: dict) -> dict:
+        tools = self._server.tools() or []
+        return {"tools": [t().to_json() for t in tools]}
+
+    async def _tools_call(self, params: dict) -> dict:
+        name = params.get("name")
+        arguments = params.get("arguments") or {}
+        tools = self._server.tools() or []
+        for tool_cls in tools:
+            tool = tool_cls()
+            if tool.name == name:
+                response = await tool.handle(arguments)
+                return {"content": response.to_content()}
+        return self._error_result(-32602, f"Tool not found: {name}")
+
+    async def _prompts_list(self, params: dict) -> dict:
+        prompts = self._server.prompts() or []
+        registered = [p().to_json() for p in prompts if p().should_register()]
+        return {"prompts": registered}
+
+    async def _prompts_get(self, params: dict) -> dict:
+        name = params.get("name")
+        arguments = params.get("arguments") or {}
+        prompts = self._server.prompts() or []
+        for prompt_cls in prompts:
+            prompt = prompt_cls()
+            if prompt.name == name and prompt.should_register():
+                response = await prompt.handle(arguments)
+                messages = [{"role": "user", "content": item} for item in response.to_content()]
+                return {"messages": messages}
+        return self._error_result(-32602, f"Prompt not found: {name}")
+
+    async def _resources_list(self, params: dict) -> dict:
+        resources = self._server.resources() or []
+        return {"resources": [r().to_json() for r in resources]}
+
+    async def _resources_read(self, params: dict) -> dict:
+        uri = params.get("uri")
+        resources = self._server.resources() or []
+        for resource_cls in resources:
+            resource = resource_cls()
+            if resource.uri == uri:
+                content = await resource.read()
+                return {
+                    "contents": [
+                        {
+                            "uri": resource.uri,
+                            "mimeType": resource.mime_type,
+                            "text": content,
+                        }
+                    ]
+                }
+        return self._error_result(-32602, f"Resource not found: {uri}")
+
+    # ------------------------------------------------------------------
+    # Helpers
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _error(request_id: Any, code: int, message: str) -> dict:
+        return {
+            "jsonrpc": "2.0",
+            "id": request_id,
+            "error": {"code": code, "message": message},
+        }
+
+    @staticmethod
+    def _error_result(code: int, message: str) -> dict:
+        """Return an error payload as a *result* (for tool/prompt/resource not found)."""
+        return {"error": {"code": code, "message": message}}

fastapi_startkit-0.30.0/src/fastapi_startkit/mcp/providers/mcp_provider.py

@@ -0,0 +1,19 @@
+from fastapi_startkit.providers import Provider
+
+
+class McpProvider(Provider):
+    """Provider that bootstraps the MCP component for fastapi-startkit.
+
+    Register it alongside ``FastAPIProvider`` to make MCP available in
+    your application::
+
+        app = Application(providers=[FastAPIProvider, McpProvider])
+    """
+
+    provider_key = "mcp"
+
+    def register(self) -> None:
+        """Register MCP bindings into the container."""
+
+    def boot(self) -> None:
+        """Boot the MCP component."""

fastapi_startkit-0.30.0/src/fastapi_startkit/mcp/request.py

@@ -0,0 +1,19 @@
+"""JSON-RPC 2.0 request model."""
+
+from typing import Any, Optional, Union
+
+from pydantic import BaseModel
+
+
+class JsonRpcRequest(BaseModel):
+    """Represents a JSON-RPC 2.0 request or notification."""
+
+    jsonrpc: str = "2.0"
+    method: str
+    params: Optional[dict[str, Any]] = None
+    id: Optional[Union[str, int]] = None
+
+    @property
+    def is_notification(self) -> bool:
+        """Return True when the request has no id (i.e. it is a notification)."""
+        return self.id is None

fastapi_startkit-0.30.0/src/fastapi_startkit/mcp/resource.py

@@ -0,0 +1,32 @@
+"""Abstract base class for MCP resources."""
+
+from abc import ABC, abstractmethod
+from typing import Optional
+
+
+class Resource(ABC):
+    """Base class for MCP resources.
+
+    Subclasses must set ``uri`` and ``name``, and implement ``read()``.
+    """
+
+    uri: str
+    name: str
+    description: Optional[str] = None
+    mime_type: str = "text/plain"
+
+    @abstractmethod
+    async def read(self, **kwargs) -> str:
+        """Return the resource content as a string."""
+        raise NotImplementedError
+
+    def to_json(self) -> dict:
+        """Serialise to the MCP resources/list format."""
+        data: dict = {
+            "uri": self.uri,
+            "name": self.name,
+            "mimeType": self.mime_type,
+        }
+        if self.description is not None:
+            data["description"] = self.description
+        return data

fastapi_startkit-0.30.0/src/fastapi_startkit/mcp/response.py

@@ -0,0 +1,30 @@
+"""Response wrapper for MCP tool and prompt outputs."""
+
+import json
+from typing import Any
+
+
+class Response:
+    """Wraps tool/prompt output into MCP content format."""
+
+    def __init__(self, content: list[dict]) -> None:
+        self._content = content
+
+    @classmethod
+    def text(cls, value: str) -> "Response":
+        """Create a plain-text response."""
+        return cls([{"type": "text", "text": value}])
+
+    @classmethod
+    def structure(cls, data: dict[str, Any]) -> "Response":
+        """Create a structured (resource-type) response."""
+        return cls([{"type": "resource", "resource": {"text": json.dumps(data), "mimeType": "application/json"}}])
+
+    @classmethod
+    def empty(cls) -> "Response":
+        """Create an empty response with no content."""
+        return cls([])
+
+    def to_content(self) -> list[dict]:
+        """Return the raw content list."""
+        return self._content

fastapi_startkit-0.30.0/src/fastapi_startkit/mcp/server.py

@@ -0,0 +1,79 @@
+"""MCP Server base class."""
+
+from typing import Optional, Type
+
+from fastapi import APIRouter, Request
+from fastapi.responses import JSONResponse, Response as StarletteResponse
+
+from .protocol import Protocol
+from .request import JsonRpcRequest
+from .tool import Tool
+from .prompt import Prompt
+from .resource import Resource
+
+
+class Server:
+    """Base class for MCP servers.
+
+    Subclasses must set ``name`` and override ``tools()``, ``prompts()``,
+    and/or ``resources()`` to register capabilities.
+
+    Usage::
+
+        class MyServer(Server):
+            name = "my-server"
+
+            def tools(self):
+                return [AddTool]
+
+        server = MyServer()
+        app.include_router(server.router("/mcp"))
+    """
+
+    name: str
+    description: Optional[str] = None
+    instructions: Optional[str] = None
+
+    def tools(self) -> Optional[list[Type[Tool]]]:
+        """Return a list of Tool classes to register, or None."""
+        return None
+
+    def prompts(self) -> Optional[list[Type[Prompt]]]:
+        """Return a list of Prompt classes to register, or None."""
+        return None
+
+    def resources(self) -> Optional[list[Type[Resource]]]:
+        """Return a list of Resource classes to register, or None."""
+        return None
+
+    def router(self, prefix: str = "/mcp") -> APIRouter:
+        """Build and return a FastAPI APIRouter for this server.
+
+        The router exposes:
+        - ``POST {prefix}`` — JSON-RPC 2.0 endpoint
+        - ``GET {prefix}``  — returns 405 with ``Allow: POST``
+        """
+        protocol = Protocol(self)
+        api_router = APIRouter(prefix=prefix)
+
+        @api_router.post("")
+        async def handle_post(request: Request) -> StarletteResponse:
+            body = await request.json()
+            rpc = JsonRpcRequest(**body)
+
+            if rpc.is_notification:
+                # Fire-and-forget: dispatch but return 202 immediately
+                await protocol.dispatch(rpc.method, rpc.params, rpc.id)
+                return StarletteResponse(status_code=202)
+
+            result = await protocol.dispatch(rpc.method, rpc.params, rpc.id)
+            return JSONResponse(content=result)
+
+        @api_router.get("")
+        async def handle_get() -> StarletteResponse:
+            return StarletteResponse(
+                status_code=405,
+                headers={"Allow": "POST"},
+            )
+
+        return api_router

fastapi_startkit-0.30.0/src/fastapi_startkit/mcp/tool.py

@@ -0,0 +1,54 @@
+"""Abstract base class for MCP tools."""
+
+from abc import ABC, abstractmethod
+from typing import Optional, Type
+
+from pydantic import BaseModel
+
+from .response import Response
+
+
+class Tool(ABC):
+    """Base class for MCP tools.
+
+    Subclasses must set ``name`` and ``description``, and implement ``handle()``.
+    Optionally override ``schema()`` to declare the input schema and
+    ``output_schema()`` to declare the output schema.
+    """
+
+    name: str
+    description: str
+
+    def schema(self) -> Optional[Type[BaseModel]]:
+        """Return a Pydantic BaseModel subclass describing the input, or None."""
+        return None
+
+    def output_schema(self) -> Optional[Type[BaseModel]]:
+        """Return a Pydantic BaseModel subclass describing the output, or None."""
+        return None
+
+    @abstractmethod
+    async def handle(self, arguments: dict) -> Response:
+        """Execute the tool with the given arguments and return a Response."""
+        raise NotImplementedError
+
+    def to_json(self) -> dict:
+        """Serialise to the MCP tools/list format."""
+        input_schema: dict
+        schema_cls = self.schema()
+        if schema_cls is not None:
+            input_schema = schema_cls.model_json_schema()
+        else:
+            input_schema = {"type": "object", "properties": {}}
+
+        data: dict = {
+            "name": self.name,
+            "description": self.description,
+            "inputSchema": input_schema,
+        }
+
+        output_schema_cls = self.output_schema()
+        if output_schema_cls is not None:
+            data["outputSchema"] = output_schema_cls.model_json_schema()
+
+        return data