Merge pull request #412 from aignostics/task/BE-5766-create-papi-heta-tools

task(BE-5766): Introduce PAPI-HETA tools

Author: neelay-aign

README.md

@@ -621,7 +621,17 @@ for the Google Storage Bucket**
 
 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
+### Quick Start with Claude Desktop (macOS)
+
+Run the following command to automatically configure Claude Desktop:
+
+```bash
+uvx aignostics mcp install
+```
+
+This command adds the Aignostics MCP server to your Claude Desktop configuration file at `~/Library/Application Support/Claude/claude_desktop_config.json`. Restart Claude Desktop after running this command.
+
+**Manual configuration (Windows or custom setup):**
 
 Add the following to your Claude Desktop configuration file:
 
@@ -644,8 +654,13 @@ Restart Claude Desktop after adding this configuration.
 ### CLI Commands
 
 ```bash
-# Using uvx (no installation required)
+# Configure Claude Desktop (macOS)
+uvx aignostics mcp install
+
+# Run the MCP server manually
 uvx aignostics mcp run
+
+# List available tools
 uvx aignostics mcp list-tools
 ```
 

pyproject.toml

@@ -138,7 +138,7 @@ 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.
+    "fastmcp @ git+https://github.com/jlowin/fastmcp.git@c8e2c621ef9e568f698e99085ed5d9e5d96678c6",  # MCP server - Pinned to commit with meta field preservation fix
 ]
 
 [project.optional-dependencies]

src/aignostics/cli.py

@@ -3,6 +3,7 @@
 import sys
 from importlib.util import find_spec
 from pathlib import Path
+from typing import Annotated
 
 import typer
 from loguru import logger
@@ -31,8 +32,6 @@ def launchpad() -> None:
 
 
 if find_spec("marimo"):
-    from typing import Annotated
-
     from aignostics.utils import create_marimo_app
 
     @cli.command()
@@ -68,20 +67,99 @@ def notebook(
 mcp_cli = typer.Typer(name="mcp", help="MCP (Model Context Protocol) server for AI agent integration.")
 
 
+@mcp_cli.command("install")
+def mcp_install() -> None:
+    """Configure Claude Desktop to use the Aignostics MCP server.
+
+    This command automatically adds the Aignostics MCP server configuration
+    to your Claude Desktop config file on macOS. After running this command,
+    restart Claude Desktop to load the MCP server.
+
+    The configuration uses uvx, so no local installation is required.
+
+    Examples:
+        aignostics mcp install
+
+    Raises:
+        Exit: If not on macOS, if uvx is not found, or if user cancels.
+    """
+    import json  # noqa: PLC0415
+    import platform  # noqa: PLC0415
+    import shutil  # noqa: PLC0415
+
+    if platform.system() != "Darwin":
+        console.print("[red]Error:[/red] This command is only supported on macOS.", style="error")
+        raise typer.Exit(1)
+
+    # Claude Desktop config path on macOS
+    config_path = Path.home() / "Library" / "Application Support" / "Claude" / "claude_desktop_config.json"
+
+    # Find uvx binary
+    uvx_path = shutil.which("uvx")
+    if not uvx_path:
+        console.print("[red]Error:[/red] Could not find 'uvx' binary. Please install uv first.", style="error")
+        raise typer.Exit(1)
+
+    # Build the server configuration using uvx
+    server_config = {
+        "command": uvx_path,
+        "args": ["aignostics", "mcp", "run"],
+    }
+
+    # Load existing config or create new one
+    if config_path.exists():
+        with config_path.open() as f:
+            config = json.load(f)
+        console.print(f"[dim]Found existing config at {config_path}[/dim]")
+    else:
+        config = {}
+        # Ensure parent directory exists
+        config_path.parent.mkdir(parents=True, exist_ok=True)
+        console.print(f"[dim]Creating new config at {config_path}[/dim]")
+
+    # Initialize mcpServers if not present
+    if "mcpServers" not in config:
+        config["mcpServers"] = {}
+
+    # Check if aignostics is already configured
+    if "aignostics" in config["mcpServers"]:
+        existing = config["mcpServers"]["aignostics"]
+        console.print("[yellow]Warning:[/yellow] Aignostics MCP server is already configured:")
+        console.print(f"  command: {existing.get('command')}")
+        console.print(f"  args: {existing.get('args')}")
+        if not typer.confirm("Do you want to overwrite the existing configuration?"):
+            console.print("[dim]Configuration unchanged.[/dim]")
+            raise typer.Exit(0)
+
+    # Add or update the aignostics server config
+    config["mcpServers"]["aignostics"] = server_config
+
+    # Write the config back
+    with config_path.open("w") as f:
+        json.dump(config, f, indent=2)
+
+    console.print("\n[green]✓[/green] Claude Desktop configured successfully!")
+    console.print(f"\n[bold]Configuration written to:[/bold] {config_path}")
+    console.print("\n[bold]Server configuration:[/bold]")
+    console.print(f"  command: {server_config['command']}")
+    console.print(f"  args: {server_config['args']}")
+    console.print("\n[yellow]→[/yellow] Please restart Claude Desktop to load the MCP server.")
+
+
 @mcp_cli.command("run")
 def mcp_run() -> None:
-    """Run the MCP server.
+    """Run the MCP server with all tools including MCP Apps.
 
-    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.
+    Starts an MCP server using stdio transport that exposes SDK functionality
+    to AI agents. The server discovers and mounts all available MCP servers,
+    including those with MCP Apps for interactive visualizations.
 
     Examples:
         uv run aignostics mcp run
     """
-    from aignostics.utils import mcp_run  # noqa: PLC0415
+    from aignostics.utils import mcp_run_server  # noqa: PLC0415
 
-    mcp_run()
+    mcp_run_server()
 
 
 @mcp_cli.command("list-tools")