add MCP server

demo/health.py

@@ -3,8 +3,13 @@ from __future__ import annotations
 import html
 import importlib.util
 import re
+import os
 import shutil
 import subprocess
+import asyncio
+import sys
+from pathlib import Path
+import logging
 from dataclasses import dataclass
 from itertools import zip_longest
 from typing import Iterable
@@ -96,8 +101,56 @@ def _check_yt_dlp_python() -> ToolStatus:
     return ToolStatus(label, False, "yt_dlp_ejs missing (JS sites will fail)")
 
 
+def _check_mcp_health() -> ToolStatus:
+    label = "MCP server"
+    try:
+        from fastmcp import Client  # type: ignore
+        from fastmcp.client.transports import StdioTransport  # type: ignore
+    except Exception as exc:  # pragma: no cover - defensive
+        return ToolStatus(label, False, f"fastmcp missing: {exc}")
+
+    repo_root = Path(__file__).resolve().parents[1]
+    mcp_src = repo_root / "mcp" / "src"
+    existing_py_path = os.environ.get("PYTHONPATH", "")
+    py_path = (
+        f"{mcp_src}{os.pathsep}{existing_py_path}"
+        if existing_py_path
+        else str(mcp_src)
+    )
+
+    transport = StdioTransport(
+        command=sys.executable,
+        args=["-m", "aileen3_mcp.server"],
+        env={"PYTHONPATH": py_path},
+    )
+
+    async def probe() -> ToolStatus:
+        try:
+            async with Client(transport) as client:
+                result = await client.call_tool("health", {})
+        except Exception as exc:
+            logging.warning("MCP health probe failed: %s", exc)
+            return ToolStatus(label, False, f"Probe failed: {exc}")
+
+        # FastMCP returns a CallToolResult; unwrap to the underlying payload if present.
+        payload = getattr(result, "data", None) or getattr(result, "structured_content", None) or result
+
+        if isinstance(payload, dict):
+            ok = bool(payload.get("ok", False))
+            detail = str(payload.get("detail", "no detail"))
+        else:
+            ok = False
+            detail = str(payload)
+
+        if not ok:
+            logging.warning("MCP health probe reported not-ok: %s", detail)
+        return ToolStatus(label, ok, detail)
+
+    return asyncio.run(probe())
+
+
 def run_health_report() -> HealthReport:
-    tool_statuses = [_check_deno(), _check_yt_dlp_python()]
+    tool_statuses = [_check_deno(), _check_yt_dlp_python(), _check_mcp_health()]
     ok = all(status.ok for status in tool_statuses)
     if ok:
         summary = "All systems look good—ready for notebook-style experimentation."

demo/requirements.txt

@@ -1,2 +1,3 @@
 gradio>=6.0.0.dev0
 yt-dlp[default]>=2025.11.12
+fastmcp>=0.1.11

mcp/README.md

@@ -0,0 +1,15 @@
+# Aileen3 MCP Server
+
+Lightweight MCP server exposing a health check tool for local use by the demo app.
+
+## Quick start
+
+```bash
+python -m pip install -e ./mcp
+aileen3-mcp  # starts the stdio MCP server
+```
+
+The server provides a single `health` tool that reports an `"ok": true` payload and a short message.
+
+## ToDo
+* write proper project description: add to README.md and pyproject.toml

mcp/pyproject.toml

@@ -0,0 +1,17 @@
+[project]
+name = "aileen3-mcp"
+version = "0.1.0"
+description = "Aileen 3 Core MCP server."
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [
+    { name = "Nils Durner" },
+]
+dependencies = ["fastmcp>=0.1.11"]
+
+[project.scripts]
+aileen3-mcp = "aileen3_mcp.server:main"
+
+[build-system]
+requires = ["setuptools>=64", "wheel"]
+build-backend = "setuptools.build_meta"

mcp/src/aileen3_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""Aileen3 MCP server package."""
+
+__all__ = ["server"]

mcp/src/aileen3_mcp/server.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+import logging
+from dataclasses import asdict, dataclass
+
+from fastmcp import FastMCP
+
+log = logging.getLogger(__name__)
+
+
+@dataclass
+class HealthResult:
+    ok: bool
+    detail: str
+
+
+def make_app() -> FastMCP:
+    """Create the MCP application with a health tool."""
+    app = FastMCP("aileen3-mcp")
+
+    @app.tool()
+    def health() -> dict:
+        """Return a basic health payload."""
+        result = HealthResult(ok=True, detail="aileen3-mcp ready")
+        log.debug("Health probe returning %s", result)
+        return asdict(result)
+
+    return app
+
+
+def main() -> None:
+    logging.basicConfig(level=logging.INFO)
+    app = make_app()
+    app.run()  # stdio transport by default
+
+
+if __name__ == "__main__":
+    main()