hexastack-mcp 0.0.0__tar.gz

hexastack_mcp-0.0.0/PKG-INFO

@@ -0,0 +1,168 @@
+Metadata-Version: 2.3
+Name: hexastack-mcp
+Version: 0.0.0
+Summary: Model Context Protocol (MCP) adapter and AI agent tool integration for Hexastack
+Author: Richard West
+Author-email: Richard West <dopplereffect.us@gmail.com>
+Requires-Dist: hexastack-core
+Requires-Dist: hexastack-cqrs
+Requires-Dist: mcp>=1.3.0
+Requires-Dist: fastapi>=0.141.1 ; extra == 'fastapi'
+Requires-Dist: hexastack-fastapi ; extra == 'fastapi'
+Requires-Python: >=3.13
+Provides-Extra: fastapi
+Description-Content-Type: text/markdown
+
+# hexastack-mcp
+
+> Model Context Protocol (MCP) adapter and AI agent tool integration for Hexastack.
+
+[![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)
+
+---
+
+## 1. Overview & Capabilities
+
+`hexastack-mcp` exposes Hexastack application services directly to AI agents (Claude Desktop, Cursor, Antigravity, custom LLM agents) via the official Anthropic Model Context Protocol:
+
+- **Automatic CQRS Tool Generation (`@mcp_tool`)**: Decorates CQRS Command and Query models, converting them into structured LLM tools with JSON Schema validation.
+- **Resource URI Providers (`@mcp_resource`)**: Exposes read endpoints and system diagnostics as readable MCP resources (`hexastack://schema`, `hexastack://info`).
+- **Prompt Templates (`@mcp_prompt`)**: Configures reusable workflow prompts for LLM clients.
+- **Multiple Transports**:
+  - **Standard I/O (`stdio`)**: Local process communication for desktop assistants and subprocess agents.
+  - **Server-Sent Events (`sse`)**: HTTP SSE transport via FastAPI for remote agent networks.
+- **Single-Pass Reflection**: Discovers decorated tools and resources in Phase 3 module scanning via `create_mcp_visitor`.
+
+---
+
+## 2. Package Anatomy & Key Components
+
+```
+hexastack_mcp/
+├── domain/          # McpToolMetadata, McpResourceMetadata, McpPromptMetadata, McpError
+├── adapters/        # stdio runner, sse/FastAPI router, FastMCP server wrapper
+└── infra/
+    ├── bootstrap.py # McpBootstrapper (order=40)
+    ├── config.py    # HexastackMcpConfig
+    ├── decorators.py# @mcp_tool, @mcp_resource, @mcp_prompt
+    ├── autodiscovery.py # create_mcp_visitor
+    └── registries/  # server.py (McpServerRegistry)
+```
+
+### Key Exports
+
+| Category | Exports |
+|---|---|
+| **Adapters** | `run_stdio_server`, `create_sse_router`, `mount_mcp_sse` |
+| **Bootstrap** | `McpBootstrapper` (order=40), `HexastackMcpConfig` |
+| **Decorators** | `@mcp_tool`, `@mcp_resource`, `@mcp_prompt` |
+| **Registries** | `McpServerRegistry`, `get_mcp_registry` |
+
+---
+
+## 3. Monorepo & Sibling Relationships
+
+```mermaid
+graph TD
+    subgraph Agents ["AI Agent Clients (Claude, Cursor, Antigravity)"]
+        STDIO_CLIENT["Local Desktop / Subprocess (stdio)"]
+        SSE_CLIENT["Remote Agent Network (SSE / HTTP)"]
+    end
+
+    subgraph McpAdapter ["hexastack-mcp"]
+        SERVER["FastMCP / MCP Server"]
+        REG["McpServerRegistry (Tools, Resources, Prompts)"]
+        DISPATCH["CQRS Tool Dispatcher"]
+    end
+
+    subgraph CQRSExecution ["hexastack-cqrs"]
+        CBUS["CommandBusPort"]
+        QBUS["QueryBusPort"]
+    end
+
+    subgraph WebIntegration ["hexastack-fastapi (Optional)"]
+        FASTAPI_APP["FastAPI Application (SSE Endpoint)"]
+    end
+
+    STDIO_CLIENT --> SERVER
+    SSE_CLIENT --> FASTAPI_APP
+    FASTAPI_APP --> SERVER
+    SERVER --> REG
+    REG --> DISPATCH
+    DISPATCH -->|dispatches commands| CBUS
+    DISPATCH -->|dispatches queries| QBUS
+```
+
+### Explicit Dependencies (Direct)
+- `hexastack-core`: DI container, configuration registry, base exceptions.
+- `hexastack-cqrs`: `CommandBusPort` and `QueryBusPort` for message dispatching.
+- `mcp>=1.3.0`: Official Anthropic Model Context Protocol SDK.
+
+### Implied / Behavioral Relationships (DI-Mediated)
+- **FastAPI SSE Integration**: `McpBootstrapper` (order=40) attaches SSE endpoints to the active `FastAPI` instance when `hexastack-fastapi` is present and `auto_mount_fastapi=true`.
+- **CQRS Dispatching**: When an LLM executes an MCP tool, the adapter resolves `CommandBusPort` or `QueryBusPort` to run the command through the full middleware pipeline.
+
+### Optional Integrations (Extras)
+- `[fastapi]`: Installs `hexastack-fastapi` and `fastapi>=0.141.1` for remote SSE transport over HTTP.
+
+---
+
+## 4. Installation
+
+```bash
+# Standalone stdio transport
+pip install hexastack-mcp
+
+# With FastAPI remote SSE transport
+pip install "hexastack-mcp[fastapi]"
+
+# Via umbrella package
+pip install "hexastack[mcp]"
+```
+
+---
+
+## 5. Configuration Reference
+
+```toml
+[hexastack.mcp]
+server_name = "Hexastack MCP Server"
+server_version = "0.1.0"
+sse_path = "/sse" # Route prefix for SSE transport
+auto_mount_fastapi = true # Auto-mount SSE router into FastAPI on bootstrap
+```
+
+---
+
+## 6. Quickstart Example
+
+```python
+from dataclasses import dataclass
+from hexastack_core.infra.bootstrap import bootstrap
+from hexastack_cqrs.domain.query import Query
+from hexastack_cqrs.infra.decorators import query_handler
+from hexastack_mcp.infra.decorators import mcp_tool
+
+
+# 1. Define CQRS Query & Handler
+@dataclass(frozen=True)
+class CheckSystemStatusQuery(Query):
+    service: str = "database"
+
+
+@query_handler(CheckSystemStatusQuery)
+class CheckSystemStatusHandler:
+    def __call__(self, qry: CheckSystemStatusQuery) -> dict[str, str]:
+        return {"service": qry.service, "status": "HEALTHY"}
+
+
+# 2. Expose as MCP Tool for AI Agents
+mcp_tool(
+    name="check_status",
+    description="Check the real-time operational status of internal subsystems.",
+)(CheckSystemStatusQuery)
+
+# 3. Bootstrap Runtime and Run MCP Server
+runtime = bootstrap(packages_to_scan=[__name__])
+mcp_server = runtime.get("mcp_server")
+```

hexastack_mcp-0.0.0/README.md

@@ -0,0 +1,153 @@
+# hexastack-mcp
+
+> Model Context Protocol (MCP) adapter and AI agent tool integration for Hexastack.
+
+[![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)
+
+---
+
+## 1. Overview & Capabilities
+
+`hexastack-mcp` exposes Hexastack application services directly to AI agents (Claude Desktop, Cursor, Antigravity, custom LLM agents) via the official Anthropic Model Context Protocol:
+
+- **Automatic CQRS Tool Generation (`@mcp_tool`)**: Decorates CQRS Command and Query models, converting them into structured LLM tools with JSON Schema validation.
+- **Resource URI Providers (`@mcp_resource`)**: Exposes read endpoints and system diagnostics as readable MCP resources (`hexastack://schema`, `hexastack://info`).
+- **Prompt Templates (`@mcp_prompt`)**: Configures reusable workflow prompts for LLM clients.
+- **Multiple Transports**:
+  - **Standard I/O (`stdio`)**: Local process communication for desktop assistants and subprocess agents.
+  - **Server-Sent Events (`sse`)**: HTTP SSE transport via FastAPI for remote agent networks.
+- **Single-Pass Reflection**: Discovers decorated tools and resources in Phase 3 module scanning via `create_mcp_visitor`.
+
+---
+
+## 2. Package Anatomy & Key Components
+
+```
+hexastack_mcp/
+├── domain/          # McpToolMetadata, McpResourceMetadata, McpPromptMetadata, McpError
+├── adapters/        # stdio runner, sse/FastAPI router, FastMCP server wrapper
+└── infra/
+    ├── bootstrap.py # McpBootstrapper (order=40)
+    ├── config.py    # HexastackMcpConfig
+    ├── decorators.py# @mcp_tool, @mcp_resource, @mcp_prompt
+    ├── autodiscovery.py # create_mcp_visitor
+    └── registries/  # server.py (McpServerRegistry)
+```
+
+### Key Exports
+
+| Category | Exports |
+|---|---|
+| **Adapters** | `run_stdio_server`, `create_sse_router`, `mount_mcp_sse` |
+| **Bootstrap** | `McpBootstrapper` (order=40), `HexastackMcpConfig` |
+| **Decorators** | `@mcp_tool`, `@mcp_resource`, `@mcp_prompt` |
+| **Registries** | `McpServerRegistry`, `get_mcp_registry` |
+
+---
+
+## 3. Monorepo & Sibling Relationships
+
+```mermaid
+graph TD
+    subgraph Agents ["AI Agent Clients (Claude, Cursor, Antigravity)"]
+        STDIO_CLIENT["Local Desktop / Subprocess (stdio)"]
+        SSE_CLIENT["Remote Agent Network (SSE / HTTP)"]
+    end
+
+    subgraph McpAdapter ["hexastack-mcp"]
+        SERVER["FastMCP / MCP Server"]
+        REG["McpServerRegistry (Tools, Resources, Prompts)"]
+        DISPATCH["CQRS Tool Dispatcher"]
+    end
+
+    subgraph CQRSExecution ["hexastack-cqrs"]
+        CBUS["CommandBusPort"]
+        QBUS["QueryBusPort"]
+    end
+
+    subgraph WebIntegration ["hexastack-fastapi (Optional)"]
+        FASTAPI_APP["FastAPI Application (SSE Endpoint)"]
+    end
+
+    STDIO_CLIENT --> SERVER
+    SSE_CLIENT --> FASTAPI_APP
+    FASTAPI_APP --> SERVER
+    SERVER --> REG
+    REG --> DISPATCH
+    DISPATCH -->|dispatches commands| CBUS
+    DISPATCH -->|dispatches queries| QBUS
+```
+
+### Explicit Dependencies (Direct)
+- `hexastack-core`: DI container, configuration registry, base exceptions.
+- `hexastack-cqrs`: `CommandBusPort` and `QueryBusPort` for message dispatching.
+- `mcp>=1.3.0`: Official Anthropic Model Context Protocol SDK.
+
+### Implied / Behavioral Relationships (DI-Mediated)
+- **FastAPI SSE Integration**: `McpBootstrapper` (order=40) attaches SSE endpoints to the active `FastAPI` instance when `hexastack-fastapi` is present and `auto_mount_fastapi=true`.
+- **CQRS Dispatching**: When an LLM executes an MCP tool, the adapter resolves `CommandBusPort` or `QueryBusPort` to run the command through the full middleware pipeline.
+
+### Optional Integrations (Extras)
+- `[fastapi]`: Installs `hexastack-fastapi` and `fastapi>=0.141.1` for remote SSE transport over HTTP.
+
+---
+
+## 4. Installation
+
+```bash
+# Standalone stdio transport
+pip install hexastack-mcp
+
+# With FastAPI remote SSE transport
+pip install "hexastack-mcp[fastapi]"
+
+# Via umbrella package
+pip install "hexastack[mcp]"
+```
+
+---
+
+## 5. Configuration Reference
+
+```toml
+[hexastack.mcp]
+server_name = "Hexastack MCP Server"
+server_version = "0.1.0"
+sse_path = "/sse" # Route prefix for SSE transport
+auto_mount_fastapi = true # Auto-mount SSE router into FastAPI on bootstrap
+```
+
+---
+
+## 6. Quickstart Example
+
+```python
+from dataclasses import dataclass
+from hexastack_core.infra.bootstrap import bootstrap
+from hexastack_cqrs.domain.query import Query
+from hexastack_cqrs.infra.decorators import query_handler
+from hexastack_mcp.infra.decorators import mcp_tool
+
+
+# 1. Define CQRS Query & Handler
+@dataclass(frozen=True)
+class CheckSystemStatusQuery(Query):
+    service: str = "database"
+
+
+@query_handler(CheckSystemStatusQuery)
+class CheckSystemStatusHandler:
+    def __call__(self, qry: CheckSystemStatusQuery) -> dict[str, str]:
+        return {"service": qry.service, "status": "HEALTHY"}
+
+
+# 2. Expose as MCP Tool for AI Agents
+mcp_tool(
+    name="check_status",
+    description="Check the real-time operational status of internal subsystems.",
+)(CheckSystemStatusQuery)
+
+# 3. Bootstrap Runtime and Run MCP Server
+runtime = bootstrap(packages_to_scan=[__name__])
+mcp_server = runtime.get("mcp_server")
+```

hexastack_mcp-0.0.0/pyproject.toml

@@ -0,0 +1,58 @@
+[project]
+name = "hexastack-mcp"
+version = "0.0.0"
+description = "Model Context Protocol (MCP) adapter and AI agent tool integration for Hexastack"
+readme = "README.md"
+requires-python = ">=3.13"
+dependencies = [
+    "hexastack-core",
+    "hexastack-cqrs",
+    "mcp>=1.3.0",
+]
+
+[[project.authors]]
+name = "Richard West"
+email = "dopplereffect.us@gmail.com"
+
+[project.optional-dependencies]
+fastapi = [
+    "fastapi>=0.141.1",
+    "hexastack-fastapi",
+]
+
+[project.entry-points."hexastack.bootstrappers"]
+mcp = "hexastack_mcp.infra.bootstrap:McpBootstrapper"
+
+[build-system]
+requires = ["uv_build>=0.12.3,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.uv.sources.hexastack-core]
+workspace = true
+
+[tool.uv.sources.hexastack-cqrs]
+workspace = true
+
+[tool.uv.sources.hexastack-fastapi]
+workspace = true
+
+[tool.importlinter]
+root_packages = ["hexastack_mcp"]
+
+[[tool.importlinter.contracts]]
+name = "Hexagonal architecture layer hierarchy"
+type = "layers"
+containers = ["hexastack_mcp"]
+layers = [
+    "adapters",
+    "domain",
+]
+
+[[tool.importlinter.contracts]]
+name = "Forbidden imports for domain"
+type = "forbidden"
+source_modules = ["hexastack_mcp.domain"]
+forbidden_modules = [
+    "hexastack_mcp.adapters",
+    "hexastack_mcp.infra",
+]

hexastack_mcp-0.0.0/pyproject.toml.orig

@@ -0,0 +1,53 @@
+[project]
+name = "hexastack-mcp"
+version = "0.0.0"
+description = "Model Context Protocol (MCP) adapter and AI agent tool integration for Hexastack"
+readme = "README.md"
+authors = [
+    { name = "Richard West", email = "dopplereffect.us@gmail.com" }
+]
+requires-python = ">=3.13"
+dependencies = [
+    "hexastack-core",
+    "hexastack-cqrs",
+    "mcp>=1.3.0",
+]
+
+[project.optional-dependencies]
+fastapi = [
+    "fastapi>=0.141.1",
+    "hexastack-fastapi",
+]
+
+[project.entry-points."hexastack.bootstrappers"]
+mcp = "hexastack_mcp.infra.bootstrap:McpBootstrapper"
+
+[build-system]
+requires = ["uv_build>=0.12.3,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.uv.sources]
+hexastack-core = { workspace = true }
+hexastack-cqrs = { workspace = true }
+hexastack-fastapi = { workspace = true }
+
+[tool.importlinter]
+root_packages = ["hexastack_mcp"]
+
+[[tool.importlinter.contracts]]
+name = "Hexagonal architecture layer hierarchy"
+type = "layers"
+containers = ["hexastack_mcp"]
+layers = [
+    "adapters",
+    "domain",
+]
+
+[[tool.importlinter.contracts]]
+name = "Forbidden imports for domain"
+type = "forbidden"
+source_modules = ["hexastack_mcp.domain"]
+forbidden_modules = [
+    "hexastack_mcp.adapters",
+    "hexastack_mcp.infra",
+]

hexastack_mcp-0.0.0/src/hexastack_mcp/__init__.py

@@ -0,0 +1,7 @@
+from hexastack_mcp import adapters, domain, infra
+
+__all__ = [
+    "adapters",
+    "domain",
+    "infra",
+]

hexastack_mcp-0.0.0/src/hexastack_mcp/adapters/fastapi.py

@@ -0,0 +1,58 @@
+from typing import Any
+
+from mcp.server.fastmcp import FastMCP as McpServer
+from mcp.server.transport_security import TransportSecuritySettings
+from starlette.applications import Starlette
+
+__all__ = [
+    "create_mcp_sse_app",
+    "mount_mcp_sse",
+]
+
+
+def create_mcp_sse_app(
+    server: McpServer,
+    sse_path: str = "/sse",
+    message_path: str = "/messages/",
+    transport_security: TransportSecuritySettings | None = None,
+) -> Starlette:
+    """Create a Starlette ASGI application handling MCP SSE transport.
+
+    Args:
+        server: Configured McpServer instance.
+        sse_path: Endpoint path for SSE streams.
+        message_path: Endpoint path for posting messages.
+        transport_security: Optional TransportSecuritySettings instance.
+
+    Returns:
+        Starlette ASGI application.
+    """
+    return server.sse_app()
+
+
+def mount_mcp_sse(
+    app: Any,
+    server: McpServer,
+    path_prefix: str = "/mcp",
+    sse_path: str = "/sse",
+    transport_security: TransportSecuritySettings | None = None,
+) -> None:
+    """Mount MCP SSE endpoints onto a FastAPI/Starlette application.
+
+    Notes/Architectural Intent:
+        Enables remote LLM orchestration frameworks to connect to Hexastack
+        services over HTTP SSE streams.
+
+    Args:
+        app: Target FastAPI or Starlette application.
+        server: Configured McpServer instance.
+        path_prefix: Route prefix where the SSE sub-app is mounted.
+        sse_path: SSE stream path within the sub-app.
+        transport_security: Optional TransportSecuritySettings instance.
+    """
+    sse_app = create_mcp_sse_app(
+        server,
+        sse_path=sse_path,
+        transport_security=transport_security,
+    )
+    app.mount(path_prefix, sse_app)

hexastack_mcp-0.0.0/src/hexastack_mcp/adapters/stdio.py

@@ -0,0 +1,30 @@
+import asyncio
+
+from mcp.server.fastmcp import FastMCP as McpServer
+
+__all__ = [
+    "run_stdio_async",
+    "run_stdio_server",
+]
+
+
+async def run_stdio_async(server: McpServer) -> None:
+    """Asynchronously execute the MCP stdio communication loop.
+
+    Args:
+        server: Configured McpServer instance.
+    """
+    await server.run_stdio_async()
+
+
+def run_stdio_server(server: McpServer) -> None:
+    """Synchronously execute the MCP stdio communication loop via asyncio.run().
+
+    Notes/Architectural Intent:
+        Standard entrypoint for CLI stdio execution when orchestrated by
+        Claude Desktop, Cursor, or external LLM tool executors.
+
+    Args:
+        server: Configured McpServer instance.
+    """
+    asyncio.run(run_stdio_async(server))

hexastack_mcp-0.0.0/src/hexastack_mcp/domain/exceptions.py

@@ -0,0 +1,29 @@
+from hexastack_core.domain.exceptions import HexastackError
+
+
+class McpError(HexastackError):
+    """Base exception for all Model Context Protocol (MCP) adapter errors.
+
+    Notes/Architectural Intent:
+        Maintains consistency across the unified Hexastack exception tree.
+    """
+
+
+class ToolExecutionError(McpError):
+    """Exception raised when an MCP tool execution fails.
+
+    Notes/Architectural Intent:
+        Carries context when command or query dispatching from an MCP client
+        encounters an error.
+    """
+
+
+class ResourceNotFoundError(McpError):
+    """Exception raised when a requested MCP resource URI is not found."""
+
+
+__all__ = [
+    "McpError",
+    "ResourceNotFoundError",
+    "ToolExecutionError",
+]

hexastack_mcp-0.0.0/src/hexastack_mcp/domain/metadata.py

@@ -0,0 +1,45 @@
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True)
+class McpToolMetadata:
+    """Metadata for exposing a Command, Query, or function as an MCP Tool.
+
+    Notes/Architectural Intent:
+        Parsed by McpServerRegistry and single-pass autodiscovery visitors
+        to register MCP tools on the FastMCP/MCP server.
+    """
+
+    name: str
+    description: str | None = None
+    kind: str = "command"  # "command", "query", or "function"
+    target: Any | None = None
+
+
+@dataclass(frozen=True)
+class McpResourceMetadata:
+    """Metadata for exposing data or endpoints as an MCP Resource."""
+
+    uri: str
+    name: str
+    description: str | None = None
+    mime_type: str = "application/json"
+    handler: Callable[..., Any] | None = None
+
+
+@dataclass(frozen=True)
+class McpPromptMetadata:
+    """Metadata for exposing prompt templates to AI agents."""
+
+    name: str
+    description: str | None = None
+    handler: Callable[..., Any] | None = None
+
+
+__all__ = [
+    "McpPromptMetadata",
+    "McpResourceMetadata",
+    "McpToolMetadata",
+]

hexastack_mcp-0.0.0/src/hexastack_mcp/infra/autodiscovery.py

@@ -0,0 +1,75 @@
+from collections.abc import Sequence
+from types import ModuleType
+from typing import Any
+
+from hexastack_core.infra.autodiscovery import (
+    DiscoveryVisitor,
+    scan_modules,
+)
+from hexastack_mcp.domain.metadata import (
+    McpPromptMetadata,
+    McpResourceMetadata,
+    McpToolMetadata,
+)
+from hexastack_mcp.infra.decorators import (
+    _MCP_PROMPT_ATTR,
+    _MCP_RESOURCE_ATTR,
+    _MCP_TOOL_ATTR,
+)
+from hexastack_mcp.infra.registries.server import McpServerRegistry
+
+__all__ = [
+    "autodiscover_mcp_elements",
+    "create_mcp_visitor",
+]
+
+
+def autodiscover_mcp_elements(
+    packages_to_scan: Sequence[str | ModuleType],
+    registry: McpServerRegistry,
+) -> McpServerRegistry:
+    """Discover decorated MCP tools, resources, and prompts from packages.
+
+    Args:
+        packages_to_scan: Sequence of package names or module objects to inspect.
+        registry: Target McpServerRegistry instance.
+
+    Returns:
+        The populated McpServerRegistry instance.
+    """
+    visitor = create_mcp_visitor(registry)
+    scan_modules(packages_to_scan, [visitor])
+    return registry
+
+
+def create_mcp_visitor(
+    registry: McpServerRegistry,
+) -> DiscoveryVisitor:
+    """Create a DiscoveryVisitor callback for single-pass MCP element discovery.
+
+    Notes/Architectural Intent:
+        Inspects discovered classes and functions for MCP tool, resource, and prompt
+        decorator metadata, registering them into the supplied server registry
+        during single-pass reflection.
+
+    Args:
+        registry: Target McpServerRegistry instance.
+
+    Returns:
+        DiscoveryVisitor callable accepting (member, module).
+    """
+
+    def visitor(obj: Any, module: ModuleType) -> None:
+        tool_meta: McpToolMetadata | None = getattr(obj, _MCP_TOOL_ATTR, None)
+        if tool_meta is not None:
+            registry.register_tool(tool_meta)
+
+        res_meta: McpResourceMetadata | None = getattr(obj, _MCP_RESOURCE_ATTR, None)
+        if res_meta is not None:
+            registry.register_resource(res_meta)
+
+        prompt_meta: McpPromptMetadata | None = getattr(obj, _MCP_PROMPT_ATTR, None)
+        if prompt_meta is not None:
+            registry.register_prompt(prompt_meta)
+
+    return visitor

hexastack_mcp-0.0.0/src/hexastack_mcp/infra/bootstrap.py

@@ -0,0 +1,108 @@
+import importlib.util
+from dataclasses import dataclass
+
+from mcp.server.fastmcp import FastMCP as McpServer
+from mcp.server.transport_security import TransportSecuritySettings
+
+from hexastack_core.infra.bootstrap import (
+    BootstrapContext,
+)
+from hexastack_core.infra.registries.config import ConfigRegistry
+from hexastack_core.ports.bootstrap import BootstrapperPort
+from hexastack_mcp.infra.autodiscovery import create_mcp_visitor
+from hexastack_mcp.infra.config import (
+    HexastackMcpConfig,
+    register_mcp_config,
+)
+from hexastack_mcp.infra.decorators import get_mcp_registry
+from hexastack_mcp.infra.registries.server import McpServerRegistry
+
+
+@dataclass(frozen=True)
+class McpBootstrapResult:
+    """Dataclass holding initialized MCP server and configuration."""
+
+    config: HexastackMcpConfig
+    server: McpServer
+    registry: McpServerRegistry
+
+
+class McpBootstrapper(BootstrapperPort):
+    """Bootstrap extension configuring Anthropic Model Context Protocol (MCP) server.
+
+    Notes/Architectural Intent:
+        Implements BootstrapperPort with order=40 (executing after CQRS order=20
+        and FastAPI order=30), registering the autodiscovery visitor, assembling
+        the McpServer instance with CQRS tool wrappers, and mounting SSE endpoints
+        onto FastAPI when present.
+    """
+
+    name: str = "mcp"
+    order: int = 40
+
+    def configure(self, context: BootstrapContext) -> None:
+        """Phase 2: Register visitor, assemble McpServer, and mount SSE endpoints.
+
+        Args:
+            context: BootstrapContext containing DI container, config, and properties.
+
+        Returns:
+            None.
+        """
+        cfg = context.get_config("mcp", HexastackMcpConfig)
+
+        registry = get_mcp_registry()
+
+        # Register visitor for single-pass reflective scanning (Phase 3)
+        visitor = create_mcp_visitor(registry)
+        context.register_visitor(visitor)
+
+        # 1. Build McpServer instance from registry and container
+        server = registry.build_server(config=cfg, container=context.container)
+
+        # 2. Register Server and Registry into DI container
+        context.container.add_instance(server, declared_class=McpServer)
+        context.container.add_instance(registry)
+
+        # 3. Mount onto FastAPI app if available and configured
+        if cfg.auto_mount_fastapi and importlib.util.find_spec("fastapi") is not None:
+            fastapi_app = context.properties.get("app")
+            if fastapi_app is not None:
+                from hexastack_mcp.adapters.fastapi import mount_mcp_sse
+
+                sec = TransportSecuritySettings(
+                    enable_dns_rebinding_protection=cfg.enable_dns_rebinding_protection,
+                    allowed_hosts=cfg.allowed_hosts,
+                )
+                mount_mcp_sse(
+                    app=fastapi_app,
+                    server=server,
+                    path_prefix=cfg.sse_path,
+                    transport_security=sec,
+                )
+
+        # 4. Store in context properties
+        result = McpBootstrapResult(
+            config=cfg,
+            server=server,
+            registry=registry,
+        )
+        context.properties["mcp_result"] = result
+        context.properties["mcp_server"] = server
+
+    def register_config(self, registry: ConfigRegistry) -> None:
+        """Phase 1: Register MCP configuration schema under 'mcp'.
+
+        Args:
+            registry: Target ConfigRegistry instance.
+
+        Returns:
+            None.
+        """
+        register_mcp_config(registry)
+
+
+__all__ = [
+    "McpBootstrapper",
+    "McpBootstrapResult",
+]

hexastack_mcp-0.0.0/src/hexastack_mcp/infra/config.py

@@ -0,0 +1,70 @@
+from pydantic import BaseModel, Field
+
+from hexastack_core.infra.decorators import config_section
+from hexastack_core.infra.registries.config import ConfigRegistry
+
+
+@config_section("mcp")
+class HexastackMcpConfig(BaseModel):
+    """Configuration schema for Hexastack Model Context Protocol (MCP) server.
+
+    Notes/Architectural Intent:
+        Controls server naming, SSE routing paths, transport security,
+        and automatic FastAPI endpoint mounting.
+    """
+
+    server_name: str = Field(
+        default="Hexastack MCP Server",
+        description="Name of the MCP server announced to AI clients.",
+    )
+    server_version: str = Field(
+        default="0.1.0",
+        description="Version string of the MCP server.",
+    )
+    sse_path: str = Field(
+        default="/sse",
+        description="Route path for SSE transport when mounted on FastAPI.",
+    )
+    auto_mount_fastapi: bool = Field(
+        default=True,
+        description="Automatically mount SSE routes onto FastAPI application during bootstrap.",
+    )
+    instructions: str | None = Field(
+        default="Hexastack domain service tools and resources for AI assistants.",
+        description="System prompt / instructions sent to MCP client on initialization.",
+    )
+    enable_dns_rebinding_protection: bool = Field(
+        default=True,
+        description="Enable DNS rebinding protection for incoming SSE requests.",
+    )
+    allowed_hosts: list[str] = Field(
+        default_factory=lambda: [
+            "127.0.0.1:*",
+            "localhost:*",
+            "testserver:*",
+            "testserver",
+            "127.0.0.1",
+            "localhost",
+            "[::1]:*",
+            "::1",
+        ],
+        description="Allowed Host header values for SSE transport security.",
+    )
+
+
+__all__ = [
+    "HexastackMcpConfig",
+    "register_mcp_config",
+]
+
+
+def register_mcp_config(registry: ConfigRegistry) -> None:
+    """Register MCP configuration schema under 'mcp'.
+
+    Args:
+        registry: Target ConfigRegistry instance.
+
+    Returns:
+        None.
+    """
+    registry.register_config_section("mcp", HexastackMcpConfig)

hexastack_mcp-0.0.0/src/hexastack_mcp/infra/decorators.py

@@ -0,0 +1,132 @@
+from collections.abc import Callable
+from typing import Any
+
+from hexastack_mcp.domain.metadata import (
+    McpPromptMetadata,
+    McpResourceMetadata,
+    McpToolMetadata,
+)
+from hexastack_mcp.infra.registries.server import McpServerRegistry
+
+_MCP_TOOL_ATTR = "__hexastack_mcp_tool__"
+_MCP_RESOURCE_ATTR = "__hexastack_mcp_resource__"
+_MCP_PROMPT_ATTR = "__hexastack_mcp_prompt__"
+
+_default_registry = McpServerRegistry()
+
+
+__all__ = [
+    "get_mcp_registry",
+    "mcp_prompt",
+    "mcp_resource",
+    "mcp_tool",
+]
+
+
+def get_mcp_registry() -> McpServerRegistry:
+    """Return the global default McpServerRegistry instance.
+
+    Returns:
+        McpServerRegistry instance.
+    """
+    return _default_registry
+
+
+def mcp_prompt(
+    name: str | None = None,
+    *,
+    description: str | None = None,
+) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+    """Decorator exposing a function as an MCP Prompt template.
+
+    Args:
+        name: Name of the prompt.
+        description: Description of the prompt template.
+
+    Returns:
+        Decorator function.
+    """
+
+    def decorator(fn: Callable[..., Any]) -> Callable[..., Any]:
+        prompt_name = name or getattr(fn, "__name__", "prompt")
+        meta = McpPromptMetadata(
+            name=prompt_name,
+            description=description or getattr(fn, "__doc__", None),
+            handler=fn,
+        )
+        setattr(fn, _MCP_PROMPT_ATTR, meta)
+        _default_registry.register_prompt(meta)
+        return fn
+
+    return decorator
+
+
+def mcp_resource(
+    uri: str,
+    name: str | None = None,
+    *,
+    description: str | None = None,
+    mime_type: str = "application/json",
+) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+    """Decorator exposing a function as a readable MCP Resource.
+
+    Args:
+        uri: MCP resource URI template (e.g. 'hexastack://info').
+        name: Optional resource display name.
+        description: Optional resource description.
+        mime_type: MIME type of the returned payload.
+
+    Returns:
+        Decorator function.
+    """
+
+    def decorator(fn: Callable[..., Any]) -> Callable[..., Any]:
+        res_name = name or getattr(fn, "__name__", "resource")
+        meta = McpResourceMetadata(
+            uri=uri,
+            name=res_name,
+            description=description or getattr(fn, "__doc__", None),
+            mime_type=mime_type,
+            handler=fn,
+        )
+        setattr(fn, _MCP_RESOURCE_ATTR, meta)
+        _default_registry.register_resource(meta)
+        return fn
+
+    return decorator
+
+
+def mcp_tool(
+    name: str | None = None,
+    *,
+    description: str | None = None,
+    kind: str = "command",
+) -> Callable[[Any], Any]:
+    """Decorator exposing a Command class, Query class, or function as an MCP Tool.
+
+    Notes/Architectural Intent:
+        Attaches discovery metadata for single-pass module scanning and registers
+        the tool in the default McpServerRegistry.
+
+    Args:
+        name: Name of the tool presented to AI agents. Defaults to kebab/snake class name.
+        description: Description of tool utility.
+        kind: 'command', 'query', or 'function'.
+
+    Returns:
+        Decorator function.
+    """
+
+    def decorator(target: Any) -> Any:
+        tool_name = name or getattr(target, "__name__", "tool")
+        meta = McpToolMetadata(
+            name=tool_name,
+            description=description or getattr(target, "__doc__", None),
+            kind=kind,
+            target=target,
+        )
+        setattr(target, _MCP_TOOL_ATTR, meta)
+        _default_registry.register_tool(meta)
+        return target
+
+    return decorator

hexastack_mcp-0.0.0/src/hexastack_mcp/infra/registries/server.py

@@ -0,0 +1,256 @@
+import inspect
+import json
+import platform
+import sys
+from collections.abc import Callable
+from typing import Any
+
+from mcp.server.fastmcp import FastMCP as McpServer
+from rodi import Container
+
+from hexastack_core.domain.command import Command
+from hexastack_core.utils.inspection import inspect_model_parameters
+from hexastack_cqrs.ports.buses import (
+    CommandBusPort,
+    QueryBusPort,
+)
+from hexastack_mcp.domain.exceptions import ToolExecutionError
+from hexastack_mcp.domain.metadata import (
+    McpPromptMetadata,
+    McpResourceMetadata,
+    McpToolMetadata,
+)
+from hexastack_mcp.infra.config import HexastackMcpConfig
+
+
+class McpServerRegistry:
+    """Registry maintaining registered MCP tools, resources, and prompt templates.
+
+    Notes/Architectural Intent:
+        Compiles declarative tool and resource definitions into an McpServer
+        (FastMCP) instance, binding CQRS dispatchers from the rodi DI Container.
+    """
+
+    def __init__(self) -> None:
+        """Initialize empty MCP registry."""
+        self._tools: list[McpToolMetadata] = []
+        self._resources: list[McpResourceMetadata] = []
+        self._prompts: list[McpPromptMetadata] = []
+
+    def _create_cqrs_tool_wrapper(
+        self,
+        target_cls: type[Any],
+        kind: str,
+        container: Container,
+    ) -> Callable[..., Any]:
+        """Synthesize a typed callable from a Command or Query class for MCP schema generation."""
+        parameters = inspect_model_parameters(target_cls)
+
+        async def dynamic_mcp_tool(**kwargs: Any) -> Any:
+            try:
+                instance = target_cls(**kwargs)
+                return await self._dispatch_cqrs_instance(
+                    instance, target_cls, kind, container
+                )
+            except Exception as exc:
+                raise ToolExecutionError(
+                    f"Execution of MCP tool '{target_cls.__name__}' failed: {exc}"
+                ) from exc
+
+        # Set dynamic signature & annotations
+        setattr(  # noqa: B010
+            dynamic_mcp_tool,
+            "__signature__",
+            inspect.Signature(parameters=parameters),
+        )
+        dynamic_mcp_tool.__annotations__ = {p.name: p.annotation for p in parameters}
+        dynamic_mcp_tool.__name__ = target_cls.__name__
+        dynamic_mcp_tool.__doc__ = target_cls.__doc__
+        return dynamic_mcp_tool
+
+    async def _dispatch_cqrs_instance(
+        self,
+        instance: Any,
+        target_cls: type[Any],
+        kind: str,
+        container: Container,
+    ) -> Any:
+        """Resolve bus from container and dispatch command/query instance."""
+        if kind == "command" or issubclass(target_cls, Command):
+            cbus = container.resolve(CommandBusPort)
+            result = cbus.dispatch(instance)
+        else:
+            qbus = container.resolve(QueryBusPort)
+            result = qbus.dispatch(instance)
+
+        if inspect.isawaitable(result):
+            result = await result
+        return result
+
+    def _mount_prompts(self, server: McpServer) -> None:
+        """Register all prompt templates onto McpServer instance."""
+        for prompt_meta in self._prompts:
+            if prompt_meta.handler is not None:
+                server.prompt(
+                    name=prompt_meta.name,
+                    description=prompt_meta.description,
+                )(prompt_meta.handler)
+
+    def _mount_resources(self, server: McpServer) -> None:
+        """Register all resource endpoints onto McpServer instance."""
+        for res_meta in self._resources:
+            if res_meta.handler is not None:
+                server.resource(
+                    uri=res_meta.uri,
+                    name=res_meta.name,
+                    description=res_meta.description,
+                    mime_type=res_meta.mime_type,
+                )(res_meta.handler)
+
+    def _mount_tools(self, server: McpServer, container: Container) -> None:
+        """Register all tool wrappers onto McpServer instance."""
+        for tool_meta in self._tools:
+            if inspect.isclass(tool_meta.target):
+                tool_fn = self._create_cqrs_tool_wrapper(
+                    target_cls=tool_meta.target,
+                    kind=tool_meta.kind,
+                    container=container,
+                )
+                server.add_tool(
+                    tool_fn,
+                    name=tool_meta.name,
+                    description=tool_meta.description or tool_fn.__doc__,
+                )
+            elif callable(tool_meta.target):
+                server.add_tool(
+                    tool_meta.target,
+                    name=tool_meta.name,
+                    description=tool_meta.description or tool_meta.target.__doc__,
+                )
+
+    def _register_diagnostic_resources(
+        self, server: McpServer, config: HexastackMcpConfig
+    ) -> None:
+        """Register built-in system and registry diagnostic resources."""
+
+        @server.resource(
+            uri="hexastack://info",
+            name="system_info",
+            description="System platform and Hexastack framework runtime diagnostic information.",
+            mime_type="application/json",
+        )
+        def get_system_info_resource() -> str:
+            return json.dumps(
+                {
+                    "platform": platform.platform(),
+                    "python_version": sys.version,
+                    "server_name": config.server_name,
+                    "tools_count": len(self._tools),
+                    "resources_count": len(self._resources),
+                    "prompts_count": len(self._prompts),
+                },
+                indent=2,
+            )
+
+        @server.resource(
+            uri="hexastack://registry",
+            name="registry_manifest",
+            description="Manifest of all registered tools, resources, and prompt templates in Hexastack.",
+            mime_type="application/json",
+        )
+        def get_registry_manifest_resource() -> str:
+            return json.dumps(
+                {
+                    "tools": [
+                        {
+                            "name": t.name,
+                            "description": t.description,
+                            "kind": t.kind,
+                        }
+                        for t in self._tools
+                    ],
+                    "resources": [
+                        {
+                            "uri": r.uri,
+                            "name": r.name,
+                            "description": r.description,
+                        }
+                        for r in self._resources
+                    ],
+                    "prompts": [
+                        {"name": p.name, "description": p.description}
+                        for p in self._prompts
+                    ],
+                },
+                indent=2,
+            )
+
+    def build_server(
+        self,
+        config: HexastackMcpConfig,
+        container: Container,
+    ) -> McpServer:
+        """Construct and populate an McpServer instance from registered elements.
+
+        Args:
+            config: HexastackMcpConfig options.
+            container: Active rodi DI container for dependency resolution.
+
+        Returns:
+            Configured McpServer instance.
+        """
+        server = McpServer(
+            name=config.server_name,
+            instructions=config.instructions,
+        )
+
+        self._register_diagnostic_resources(server, config)
+        self._mount_tools(server, container)
+        self._mount_resources(server)
+        self._mount_prompts(server)
+
+        return server
+
+    @property
+    def prompts(self) -> list[McpPromptMetadata]:
+        return list(self._prompts)
+
+    def register_prompt(self, meta: McpPromptMetadata) -> None:
+        """Register prompt template metadata.
+
+        Args:
+            meta: McpPromptMetadata instance.
+        """
+        if meta not in self._prompts:
+            self._prompts.append(meta)
+
+    def register_resource(self, meta: McpResourceMetadata) -> None:
+        """Register resource metadata.
+
+        Args:
+            meta: McpResourceMetadata instance.
+        """
+        if meta not in self._resources:
+            self._resources.append(meta)
+
+    def register_tool(self, meta: McpToolMetadata) -> None:
+        """Register tool metadata.
+
+        Args:
+            meta: McpToolMetadata instance.
+        """
+        if meta not in self._tools:
+            self._tools.append(meta)
+
+    @property
+    def resources(self) -> list[McpResourceMetadata]:
+        return list(self._resources)
+
+    @property
+    def tools(self) -> list[McpToolMetadata]:
+        return list(self._tools)
+
+
+__all__ = [
+    "McpServerRegistry",
+]