task(BE-5757): Create central MCP server with auto-disocovery of plugin tools

Author: neelay-aign

CLAUDE.md

@@ -45,7 +45,7 @@ Every module has detailed CLAUDE.md documentation. For module-specific guidance,
 * [src/aignostics/wsi/CLAUDE.md](src/aignostics/wsi/CLAUDE.md) - Whole slide image processing
 * [src/aignostics/dataset/CLAUDE.md](src/aignostics/dataset/CLAUDE.md) - Dataset operations
 * [src/aignostics/bucket/CLAUDE.md](src/aignostics/bucket/CLAUDE.md) - Cloud storage management
-* [src/aignostics/utils/CLAUDE.md](src/aignostics/utils/CLAUDE.md) - Core infrastructure
+* [src/aignostics/utils/CLAUDE.md](src/aignostics/utils/CLAUDE.md) - Core infrastructure and MCP server
 * [src/aignostics/gui/CLAUDE.md](src/aignostics/gui/CLAUDE.md) - Desktop interface
 * [src/aignostics/notebook/CLAUDE.md](src/aignostics/notebook/CLAUDE.md) - Marimo notebook integration
 * [src/aignostics/qupath/CLAUDE.md](src/aignostics/qupath/CLAUDE.md) - QuPath bioimage analysis
@@ -151,9 +151,12 @@ Module/
 **utils** - Infrastructure module providing:
 
 * Dependency injection container (`locate_implementations`, `locate_subclasses`)
-* Structured logging (`get_logger`)
+* Structured logging (via `loguru.logger`)
 * Settings management (Pydantic-based)
 * Health check framework (`BaseService`, `Health`)
+* MCP server with auto-discovery of plugin tools (`mcp_create_server`, `mcp_run`, `mcp_list_tools`)
+* GUI navigation infrastructure (`BaseNavBuilder`, `NavItem`, `NavGroup`)
+* Enhanced user agent generation with CI/CD context (`user_agent`)
 
 ### API Layer
 
@@ -269,7 +272,7 @@ comprehensive view of the entire SDK's operational status.
 | **wsi** | ✅ | ✅ | ✅ | Medical image processing |
 | **dataset** | ✅ | ✅ | ✅ | Dataset downloads |
 | **bucket** | ✅ | ✅ | ✅ | Cloud storage |
-| **utils** | ✅ | ❌ | ❌ | Infrastructure |
+| **utils** | ✅ | ✅ | ❌ | Core Infrastructure |
 | **gui** | ✅ | ❌ | ✅ | Desktop launchpad |
 | **notebook** | ✅ | ❌ | ✅ | Marimo notebooks |
 | **qupath** | ✅ | ✅ | ✅ | QuPath integration |
@@ -333,6 +336,10 @@ aignostics qupath launch --project my_project.qpproj
 
 # System diagnostics
 aignostics system health
+
+# MCP server (AI agent integration)
+aignostics mcp run
+aignostics mcp list-tools
 ```
 
 ### GUI Launch

README.md

@@ -222,6 +222,15 @@ Choose your preferred interface for working with the Aignostics Platform. Each i
 | **Use when** | Building custom analysis pipeline in Python for repeated usage and processing large datasets (10s-1000s of slides) |
 | **Get started** | <a href="#example-notebooks-interact-with-the-aignostics-platform-from-your-python-notebook-environment">Run example notebooks</a> or <a href="#python-library-call-the-aignostics-platform-api-from-your-python-scripts">call the Aignostics Platform API from your Python scripts</a> |
 
+### 🤖 MCP Server (AI Agent Integration)
+
+| | |
+|---|---|
+| **What it is** | Model Context Protocol server that exposes SDK functionality to AI agents like Claude |
+| **Best for** | Users who want AI assistants to help with platform operations |
+| **Use when** | Working with Claude Desktop or other MCP-compatible AI tools to manage datasets, submit runs, or query results |
+| **Get started** | <a href="#mcp-server-integrate-with-ai-agents">Configure Claude Desktop for MCP integration</a> |
+
 > 💡 Launchpad and CLI handle authentication automatically. Python Library requires manual setup (see [authentication section](#example-notebooks-interact-with-the-aignostics-platform-from-your-python-notebook-environment)).
 
 ## Launchpad: Run your first computational pathology analysis in 10 minutes from your desktop
@@ -608,6 +617,56 @@ Self-signed URLs for files in google storage buckets can be generated using the
 [required credentials](https://cloud.google.com/docs/authentication/application-default-credentials)
 for the Google Storage Bucket**
 
+## MCP Server: Integrate with AI Agents
+
+The Python SDK includes an MCP (Model Context Protocol) server that exposes SDK functionality to AI agents like Claude. This enables AI assistants to help you interact with the Aignostics Platform through natural conversation.
+
+### Quick Start with Claude Desktop
+
+Add the following to your Claude Desktop configuration file:
+
+**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "aignostics": {
+      "command": "uvx",
+      "args": ["aignostics", "mcp", "run"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop after adding this configuration.
+
+### CLI Commands
+
+```bash
+# Using uvx (no installation required)
+uvx aignostics mcp run
+uvx aignostics mcp list-tools
+```
+
+### Using Plugins
+
+The MCP server supports plugins that extend its functionality with additional tools. To run the MCP server with a plugin installed:
+
+```bash
+# With a local plugin
+uv run --with /path/to/plugin aignostics mcp run
+
+# With a plugin from a git repository
+uvx --with git+ssh://git@github.com/org/plugin aignostics mcp run
+```
+
+Plugins register themselves via Python entry points and their tools are automatically discovered and namespaced by the MCP server.
+
+### What AI Agents Can Do
+
+Once configured, AI agents can help you with platform operations through natural language, with access to tools from the SDK and any installed plugins.
+
 ## Next Steps
 
 Now that you have an overview of the Aignostics Python SDK and its interfaces, here are some recommended next steps to deepen your understanding and get the most out of the platform:
@@ -866,9 +925,12 @@ Laboratory systems that can be integrated with the Aignostics Platform for workf
 
 ### M
 
-**Marimo**  
+**Marimo**
 Modern notebook environment supported by the Aignostics Platform as an alternative to Jupyter.
 
+**MCP (Model Context Protocol)**
+Protocol that enables AI agents like Claude to interact with external tools and services. The Aignostics SDK includes an MCP server that exposes platform functionality to AI assistants.
+
 **Metadata**  
 Descriptive information about whole slide images including dimensions, resolution, tissue type, and disease information required for processing.
 

pyproject.toml

@@ -138,12 +138,13 @@ dependencies = [
     "lxml>=6.0.2",                      # For python 3.14 pre-built wheels
     "filelock>=3.20.1",                 # CVE-2025-68146
     "marshmallow>=3.26.2",              # CVE-2025-68480
+    "fastmcp>=2.0.0,<3",                # MCP server - Major version 3 is in beta as of 26/01/2026 and has not been released on PyPI. Upgrade once a stable release is out.
 ]
 
 [project.optional-dependencies]
 pyinstaller = ["pyinstaller>=6.14.0,<7"]
 jupyter = [
-    "jupyter>=1.1.1,<2",    
+    "jupyter>=1.1.1,<2",
     # Transitive overrides
     # WARNING: one cannot negate or downgrade a dependency required here. use override-dependencies for that.
     "jupyter-core>=5.8.1",              # CVE-2025-30167

requirements/SHR-UTILS-1.md

@@ -0,0 +1,10 @@
+---
+itemId: SHR-UTILS-1
+itemTitle: Central MCP Server for SDK and Plugin Tool Access
+itemType: Requirement
+Requirement type: ENVIRONMENT
+---
+
+## Description
+
+Users shall be able to expose SDK and plugin functionality to AI agents via a central MCP server for use in AI-assisted development workflows.

requirements/SWR-UTILS-1-1.md

@@ -0,0 +1,10 @@
+---
+itemId: SWR-UTILS-1-1
+itemTitle: MCP Server with Auto-Discovery and CLI Commands
+itemHasParent: SHR-UTILS-1
+itemType: Requirement
+Requirement type: FUNCTIONAL
+Layer: System (backend logic)
+---
+
+System shall provide a central MCP server that automatically discovers plugin tools via entry-point-based service discovery, mounts them with namespace isolation to prevent tool name collisions, and exposes CLI commands (`mcp run` to start the stdio transport server, `mcp list-tools` to enumerate all registered tools).

specifications/SPEC-UTILS-SERVICE.md

@@ -3,7 +3,7 @@ itemId: SPEC-UTILS-SERVICE
 itemTitle: Utils Module Specification
 itemType: Software Item Spec
 itemIsRelatedTo: SPEC-GUI-SERVICE, SPEC-BUCKET-SERVICE, SPEC-DATASET-SERVICE, SPEC-NOTEBOOK-SERVICE, SPEC-PLATFORM-SERVICE, SPEC-QUPATH-SERVICE, SPEC-SYSTEM-SERVICE, SPEC-WSI-SERVICE
-itemFulfills: SWR-APPLICATION-1-1, SWR-APPLICATION-1-2, SWR-APPLICATION-2-1, SWR-APPLICATION-2-2, SWR-APPLICATION-2-3, SWR-APPLICATION-2-4, SWR-APPLICATION-2-5, SWR-APPLICATION-2-6, SWR-APPLICATION-2-7, SWR-APPLICATION-2-8, SWR-APPLICATION-2-9, SWR-APPLICATION-2-10, SWR-APPLICATION-2-11, SWR-APPLICATION-2-12, SWR-APPLICATION-2-13, SWR-APPLICATION-2-14, SWR-APPLICATION-2-15, SWR-APPLICATION-2-16, SWR-APPLICATION-3-1, SWR-APPLICATION-3-2, SWR-APPLICATION-3-3, SWR-BUCKET-1-1, SWR-BUCKET-1-2, SWR-BUCKET-1-3, SWR-BUCKET-1-4, SWR-BUCKET-1-5, SWR-BUCKET-1-6, SWR-BUCKET-1-7, SWR-BUCKET-1-8, SWR-BUCKET-1-9, SWR-DATASET-1-1, SWR-DATASET-1-2, SWR-DATASET-1-3, SWR-NOTEBOOK-1-1, SWR-VISUALIZATION-1-1, SWR-VISUALIZATION-1-2, SWR-VISUALIZATION-1-3, SWR-VISUALIZATION-1-4, SWR_SYSTEM_CLI_HEALTH_1, SWR_SYSTEM_GUI_HEALTH_1, SWR_SYSTEM_GUI_SETTINGS_1
+itemFulfills: SWR-APPLICATION-1-1, SWR-APPLICATION-1-2, SWR-APPLICATION-2-1, SWR-APPLICATION-2-2, SWR-APPLICATION-2-3, SWR-APPLICATION-2-4, SWR-APPLICATION-2-5, SWR-APPLICATION-2-6, SWR-APPLICATION-2-7, SWR-APPLICATION-2-8, SWR-APPLICATION-2-9, SWR-APPLICATION-2-10, SWR-APPLICATION-2-11, SWR-APPLICATION-2-12, SWR-APPLICATION-2-13, SWR-APPLICATION-2-14, SWR-APPLICATION-2-15, SWR-APPLICATION-2-16, SWR-APPLICATION-3-1, SWR-APPLICATION-3-2, SWR-APPLICATION-3-3, SWR-BUCKET-1-1, SWR-BUCKET-1-2, SWR-BUCKET-1-3, SWR-BUCKET-1-4, SWR-BUCKET-1-5, SWR-BUCKET-1-6, SWR-BUCKET-1-7, SWR-BUCKET-1-8, SWR-BUCKET-1-9, SWR-DATASET-1-1, SWR-DATASET-1-2, SWR-DATASET-1-3, SWR-NOTEBOOK-1-1, SWR-UTILS-1-1, SWR-VISUALIZATION-1-1, SWR-VISUALIZATION-1-2, SWR-VISUALIZATION-1-3, SWR-VISUALIZATION-1-4, SWR_SYSTEM_CLI_HEALTH_1, SWR_SYSTEM_GUI_HEALTH_1, SWR_SYSTEM_GUI_SETTINGS_1
 Layer: Infrastructure Service
 Version: 1.0.0
 Date: 2025-10-13
@@ -28,6 +28,7 @@ The Utils Module shall:
 - **[FR-07]** Implement settings management with validation, serialization, and sensitive data handling
 - **[FR-08]** Provide file system utilities for user data directory management and path sanitization
 - **[FR-09]** Support process information gathering and runtime environment detection
+- **[FR-10]** Provide a central MCP server with auto-discovery of plugin tools, namespace isolation, and CLI commands for running the server and listing available tools
 
 ### 1.3 Non-Functional Requirements
 
@@ -65,6 +66,7 @@ utils/
 ├── _console.py         # Rich console configuration
 ├── _logfire.py         # Logfire integration (optional)
 ├── _sentry.py          # Sentry integration (optional)
+├── _mcp.py             # MCP server with auto-discovery and plugin mounting
 ├── _notebook.py        # Marimo notebook utilities (optional)
 └── boot.py            # Application bootstrap and initialization
 ```
@@ -220,6 +222,8 @@ uvx aignostics [module-name] [subcommand] [options]
 | ---------------- | ----------------------------- | ------------------ | ---------------------- |
 | `prepare_cli()`  | Dynamic command registration  | Typer instance     | Configured CLI         |
 | Service commands | Module-specific functionality | Service parameters | Module-specific output |
+| `mcp run`        | Start MCP server (stdio)      | None               | Running MCP server     |
+| `mcp list-tools` | Enumerate registered tools    | None               | Tool name/description  |
 
 ### 4.3 GUI Interface
 
@@ -253,6 +257,7 @@ uvx aignostics [module-name] [subcommand] [options]
 | `nicegui`           | ^1.0        | GUI framework support              | Optional          | CLI-only mode              |
 | `logfire`           | ^0.41       | Observability and monitoring       | Optional          | Standard logging           |
 | `sentry-sdk`        | ^2.0        | Error tracking and performance     | Optional          | Local error handling       |
+| `fastmcp`           | >=2.0,<3    | MCP server framework               | Required          | N/A - MCP functionality    |
 | `marimo`            | ^0.8        | Notebook utilities                 | Optional          | Notebook features disabled |
 
 _Note: For exact version requirements, refer to `pyproject.toml` and dependency lock files._

src/aignostics/CLAUDE.md

@@ -11,7 +11,7 @@ This file provides a comprehensive overview of all modules in the Aignostics SDK
 | **wsi** | Whole slide image processing | ✅ | ✅ | ✅ |
 | **dataset** | IDC dataset downloads | ✅ | ✅ | ✅ |
 | **bucket** | Cloud storage operations | ✅ | ✅ | ✅ |
-| **utils** | Core utilities & DI | ❌ | ❌ | ✅ |
+| **utils** | Core utilities & DI | ✅ | ❌ | ✅ |
 | **gui** | Desktop launchpad | ❌ | ✅ | ✅ |
 | **notebook** | Marimo notebook server | ❌ | ✅ | ✅ |
 | **qupath** | QuPath integration | ✅ | ✅ | ✅ |
@@ -25,8 +25,8 @@ This file provides a comprehensive overview of all modules in the Aignostics SDK
 
 - **Core Features**:
   - OAuth 2.0 authentication, JWT token management, API client wrapper
-  - **SDK Metadata System** (NEW): Automatic tracking of execution context, user info, CI/CD environment
-  - JSON Schema validation for metadata with versioning (v0.0.1)
+  - **SDK Metadata System**: Automatic tracking of execution context, user info, CI/CD environment
+  - JSON Schema validation for metadata with versioning (Run v0.0.4, Item v0.0.3)
   - Operation caching for non-mutating API calls
 - **CLI**:
   - `user login`, `user logout`, `user whoami` for authentication
@@ -80,10 +80,11 @@ This file provides a comprehensive overview of all modules in the Aignostics SDK
 
 - **Core Features**:
   - Dependency injection, logging, settings, health checks
-  - **Enhanced User Agent** (NEW): Context-aware user agent with CI/CD tracking
+  - Enhanced user agent with CI/CD context tracking
+  - **MCP Server**: Central MCP server with auto-discovery of plugin tools (`mcp_create_server`, `mcp_run`, `mcp_list_tools`)
+  - **Navigation**: GUI sidebar navigation infrastructure (`BaseNavBuilder`, `NavItem`, `NavGroup`)
 - **Service Discovery**: `locate_implementations()`, `locate_subclasses()`
-- **User Agent**: Generates `{name}/{version} ({platform}; {test}; {github_run_url})`
-- **No CLI/GUI**: Infrastructure module
+- **User Agent**: Generates `{name}-python-sdk/{version} ({platform}; +{repo_url}; {test}; {github_run_url})`
 - **Used By**: All modules; platform module for SDK metadata
 
 ### 🖥️ gui
@@ -227,7 +228,7 @@ utils.locate_implementations(BaseService)
 
 - **Authentication**: Token cached by `platform`, used by all API calls
 - **Settings**: Managed by `utils`, consumed by all modules
-- **Logging**: Centralized through `utils.get_logger()`
+- **Logging**: Centralized through `loguru.logger`
 - **Health Checks**: All services implement `BaseService.health()`
 
 ## CLI Usage Examples

src/aignostics/cli.py

@@ -7,8 +7,8 @@
 import typer
 from loguru import logger
 
-from .constants import NOTEBOOK_DEFAULT, WINDOW_TITLE
-from .utils import (
+from aignostics.constants import NOTEBOOK_DEFAULT, WINDOW_TITLE
+from aignostics.utils import (
     __is_running_in_container__,
     __python_version__,
     __version__,
@@ -25,15 +25,15 @@
     @cli.command()
     def launchpad() -> None:
         """Open Aignostics Launchpad, the graphical user interface of the Aignostics Platform."""
-        from .utils import gui_run  # noqa: PLC0415
+        from aignostics.utils import gui_run  # noqa: PLC0415
 
         gui_run(native=True, with_api=False, title=WINDOW_TITLE, icon="🔬")
 
 
 if find_spec("marimo"):
     from typing import Annotated
 
-    from .utils import create_marimo_app
+    from aignostics.utils import create_marimo_app
 
     @cli.command()
     def notebook(
@@ -64,6 +64,61 @@ def notebook(
         uvicorn.run(create_marimo_app(notebook=notebook, override_if_exists=override_if_exists), host=host, port=port)
 
 
+# MCP (Model Context Protocol) server CLI
+mcp_cli = typer.Typer(name="mcp", help="MCP (Model Context Protocol) server for AI agent integration.")
+
+
+@mcp_cli.command("run")
+def mcp_run() -> None:
+    """Run the MCP server.
+
+    Starts an MCP server using `stdio` transport that exposes SDK functionality
+    to AI agents. The server automatically discovers and mounts tools from
+    the SDK and any installed plugins.
+
+    Examples:
+        uv run aignostics mcp run
+    """
+    from aignostics.utils import mcp_run  # noqa: PLC0415
+
+    mcp_run()
+
+
+@mcp_cli.command("list-tools")
+def mcp_list_tools() -> None:
+    """List all available MCP tools.
+
+    Shows all tools available in the MCP server, including tools from
+    the SDK and any installed plugins. Each tool is displayed with its
+    name and description.
+
+    Examples:
+        uv run aignostics mcp list-tools
+    """
+    import operator  # noqa: PLC0415
+
+    from rich.table import Table  # noqa: PLC0415
+
+    from aignostics.utils import mcp_list_tools  # noqa: PLC0415
+
+    tools = mcp_list_tools()
+
+    if not tools:
+        console.print("[dim]No tools discovered[/dim]")
+        return
+
+    table = Table(title="Available MCP Tools")
+    table.add_column("Name", style="cyan", no_wrap=True)
+    table.add_column("Description", style="white")
+
+    for tool in sorted(tools, key=operator.itemgetter("name")):
+        table.add_row(tool["name"], tool["description"])
+
+    console.print(table)
+
+
+cli.add_typer(mcp_cli)
+
 prepare_cli(
     cli, f"🔬 Aignostics Python SDK v{__version__} - built with love in Berlin 🐻 // Python v{__python_version__}"
 )