mcp-server-core 0.2.2__tar.gz → 0.3.0__tar.gz

{mcp_server_core-0.2.2/mcp_server_core.egg-info → mcp_server_core-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcp-server-core
-Version: 0.2.2
+Version: 0.3.0
 Summary: Universal MCP Server Framework: Streamable HTTP ASGI, Cloudflare Tunnel, OAuth 2.1 & Process Supervisor
 Author: yimmr
 License-Expression: MIT
@@ -19,6 +19,9 @@ Requires-Dist: uvicorn>=0.27.0
 Requires-Dist: pywin32>=306; platform_system == "Windows"
 Provides-Extra: test
 Requires-Dist: httpx>=0.27.0; extra == "test"
+Provides-Extra: tray
+Requires-Dist: pystray>=0.19.5; extra == "tray"
+Requires-Dist: pillow>=10.0.0; extra == "tray"
 Dynamic: license-file
 
 # MCP Server Core 🚀

mcp_server_core-0.3.0/mcp_framework/launcher.py

@@ -0,0 +1 @@
+from mcp_server_core.launcher import *  # noqa: F401, F403

mcp_server_core-0.3.0/mcp_framework/response.py

@@ -0,0 +1 @@
+from mcp_server_core.response import *  # noqa: F401, F403

mcp_server_core-0.3.0/mcp_framework/tray.py

@@ -0,0 +1 @@
+from mcp_server_core.tray import *  # noqa: F401, F403

{mcp_server_core-0.2.2 → mcp_server_core-0.3.0}/mcp_server_core/__init__.py

@@ -25,6 +25,8 @@ from .process import (
     kill_stale_server_process,
     stop_mcp_service,
 )
+from .launcher import launch_service
+from .response import ToolResultListDict
 from .server import (
     build_mcp_server_app,
     record_pid,
@@ -33,6 +35,7 @@ from .server import (
     serve_http,
     serve_stdio,
 )
+from .tray import BaseTrayApp, ServerProcessSupervisor
 from .tunnel import (
     CloudflareTunnel,
     TunnelHeartbeatMonitor,
@@ -64,6 +67,10 @@ __all__ = [
     "get_client_ip",
     "get_server_public_url",
     "verify_pkce",
+    "launch_service",
+    "ToolResultListDict",
+    "BaseTrayApp",
+    "ServerProcessSupervisor",
     "build_mcp_server_app",
     "record_pid",
     "cleanup_pid",

mcp_server_core-0.3.0/mcp_server_core/launcher.py

@@ -0,0 +1,103 @@
+"""Unified MCP Service Launcher and Process Lifecycle CLI."""
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+from typing import Any, Callable
+
+from .env import DeploymentEnvConfig, get_runtime_dir
+from .process import check_service_status, stop_mcp_service
+from .tunnel import ensure_tunnel_running, start_tunnel_heartbeat_monitor
+
+
+def launch_service(
+    service_name: str,
+    server_runner: Callable[[], Any],
+    default_port: int = 8788,
+    root_dir: Path | str | None = None,
+    mutex_name: str | None = None,
+) -> None:
+    """Launch an MCP service in console mode with tunnel supervisor and single-instance guards.
+
+    Handles:
+    - sys.platform Windows console UTF-8 safety
+    - `--stop`: Terminate running server on port
+    - `--test`: Pre-flight check and exit
+    - Single-instance detection with helpful console alerts
+    - Background shared Cloudflare Tunnel check & heartbeat monitor
+    - Seamless delegation to server_runner with `--no-tunnel`
+    """
+    if sys.platform == "win32":
+        try:
+            sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+            sys.stderr.reconfigure(encoding="utf-8", errors="replace")
+        except Exception:
+            pass
+
+    cwd = Path(root_dir).resolve() if root_dir else Path.cwd().resolve()
+    os.chdir(cwd)
+
+    try:
+        env_cfg = DeploymentEnvConfig.load(cwd)
+        port = env_cfg.port or default_port
+        key_configured = bool(env_cfg.api_key)
+        secret_key = env_cfg.api_key if "--show-key" in sys.argv else ("已配置（不显示密钥）" if key_configured else "未配置")
+        public_endpoint = env_cfg.upstream_url or f"http://127.0.0.1:{port}/mcp"
+    except Exception:
+        port = default_port
+        api_key_env = os.getenv("MCP_API_KEY", "")
+        key_configured = bool(api_key_env)
+        secret_key = api_key_env if "--show-key" in sys.argv else ("已配置（不显示密钥）" if key_configured else "未配置")
+        public_endpoint = os.getenv("TUNNEL_PUBLIC_URL", f"http://127.0.0.1:{port}/mcp")
+
+    local_endpoint = f"http://127.0.0.1:{port}/mcp"
+    active_mutex = mutex_name or f"Local\\{service_name.replace(' ', '_')}_{port}"
+
+    if "--stop" in sys.argv:
+        print(f"[*] 正在停止 {service_name} (端口 {port})...")
+        res = stop_mcp_service(port, cwd)
+        if res.get("killed_pids"):
+            print(f"[SUCCESS] {service_name} 服务已成功停止 (已终结进程: {res['killed_pids']})！")
+        else:
+            print(f"[INFO] 未检测到端口 {port} 上正在运行的 {service_name} 服务。")
+        sys.exit(0)
+
+    is_running, mode_desc, running_pid = check_service_status(port, cwd, active_mutex)
+    if is_running:
+        print("\n" + "=" * 70)
+        print(f"  【提示】{service_name} 服务已在运行中（或正在启动），请勿重复启动！")
+        print("=" * 70)
+        print(f"  * 运行模式:       {mode_desc}")
+        if running_pid:
+            print(f"  * 进程 PID:       {running_pid}")
+        print(f"  * 专属公网端点:   {public_endpoint}")
+        print(f"  * 安全访问密钥:   {secret_key}")
+        print(f"  * 本地监听地址:   {local_endpoint}")
+        print("-" * 70)
+        print("  如需停止服务，请直接运行 stop.bat 或右键右下角托盘图标退出")
+        print("=" * 70 + "\n")
+        try:
+            input("按 Enter 键退出...")
+        except Exception:
+            pass
+        sys.exit(0)
+
+    # 1. Ensure shared tunnel is active & start self-healing heartbeat monitor
+    print(f"[*] 检查并确保共享穿透隧道在线...")
+    try:
+        ensure_tunnel_running()
+        if public_endpoint:
+            start_tunnel_heartbeat_monitor(public_url=public_endpoint, check_interval=30.0)
+    except Exception as e:
+        print(f"[!] 隧道自检提示: {e}")
+
+    if "--test" in sys.argv:
+        print(f"[OK] {service_name} launcher pre-flight check passed!")
+        sys.exit(0)
+
+    # 2. Run child server runner
+    print(f"[*] 正在启动 {service_name} (端口 {port})...\n")
+    if "--no-tunnel" not in sys.argv:
+        sys.argv = [sys.argv[0], "--no-tunnel"] + [arg for arg in sys.argv[1:] if arg != "--no-tunnel"]
+    server_runner()

mcp_server_core-0.3.0/mcp_server_core/response.py

@@ -0,0 +1,59 @@
+"""Structured response containers and protocol helpers for MCP tools."""
+from __future__ import annotations
+
+from typing import Any
+
+
+class ToolResultListDict(dict):
+    """Structured container that ensures atomic, single-block MCP response serialization while preserving list semantics.
+
+    FastMCP converts any returned Python list into multiple separate TextContent blocks
+    in the MCP protocol response. When intermediate MCP gateways or LLM clients parse
+    the response, many gateways only inspect the last TextContent block, resulting in
+    truncation (e.g. only returning the last project, file, or item).
+
+    ToolResultListDict inherits from dict so FastMCP serializes the ENTIRE structure
+    into a single TextContent JSON payload:
+    {"status": "success", "count": N, "total": N, "<key>": items, "entries": items}
+
+    Simultaneously, for Python unit tests and backward compatibility, it implements
+    list-like iteration (__iter__), indexing (__getitem__ for int), length (__len__),
+    and membership (__contains__).
+    """
+
+    def __init__(
+        self,
+        items: list[Any],
+        key: str = "items",
+        status: str = "success",
+        **extra: Any,
+    ) -> None:
+        super().__init__()
+        self["status"] = status
+        self["total"] = len(items)
+        self["count"] = len(items)
+        self[key] = items
+        if key != "entries":
+            self["entries"] = items
+        for k, v in extra.items():
+            self[k] = v
+        self._items = items
+
+    def __iter__(self):
+        return iter(self._items)
+
+    def __len__(self) -> int:
+        return len(self._items)
+
+    def __getitem__(self, item: Any) -> Any:
+        if isinstance(item, int):
+            return self._items[item]
+        return super().__getitem__(item)
+
+    def __contains__(self, item: Any) -> bool:
+        try:
+            if super().__contains__(item):
+                return True
+        except TypeError:
+            pass
+        return item in self._items

{mcp_server_core-0.2.2 → mcp_server_core-0.3.0}/mcp_server_core/server.py

@@ -154,8 +154,10 @@ async def serve_http(
         print(f"  * 官方 MCP 门户:   {portal_url}  (ChatGPT 统一端点)")
     if upstream_mcp_url:
         print(f"  * 内部隧道回源:    {upstream_mcp_url}")
+    show_key = "--show-key" in sys.argv
     if env_cfg.require_auth:
-        print(f"  * 安全访问密钥:    {env_cfg.api_key}")
+        key_display = env_cfg.api_key if show_key else "已配置 (运行传 --show-key 查看明文)"
+        print(f"  * 安全访问密钥:    {key_display}")
     print("-" * 76)
 
     print("  【远程 Agent 配置指引 (Remote Agent Connection Guide)】")
@@ -164,19 +166,22 @@ async def serve_http(
         print(f"  [ChatGPT Developer Mode / Custom Actions 连接指南]:")
         print(f"    * 服务器 URL:       {primary_endpoint}")
         print(f"    * 身份验证类型:     Bearer Token 或 OAuth")
-        print(f"    * 访问密钥:         {env_cfg.api_key}")
+        key_hint = env_cfg.api_key if show_key else "请从本机安全配置获取 (日志不显示明文)"
+        print(f"    * 访问密钥:         {key_hint}")
         print(f"    * 备用直连回源地址: {upstream_mcp_url}\n")
 
         if env_cfg.require_auth:
+            token_display = env_cfg.api_key if show_key else "<MCP_API_KEY>"
             print(f"  [通用远程 Agent (网页端/Cursor/Claude Desktop/API)]: ")
-            print(f"    * 单 URL 快捷接入:  {primary_endpoint}?token={env_cfg.api_key}")
-            print(f"    * Header 接入:      Authorization: Bearer {env_cfg.api_key}")
+            print(f"    * 单 URL 快捷接入:  {primary_endpoint}?token={token_display}")
+            print(f"    * Header 接入:      Authorization: Bearer {token_display}")
         else:
             print(f"  URL: {primary_endpoint}")
     else:
         if env_cfg.require_auth:
+            token_display = env_cfg.api_key if show_key else "<MCP_API_KEY>"
             print(f"  URL:    {local_mcp_url}")
-            print(f"  Header: Authorization: Bearer {env_cfg.api_key}")
+            print(f"  Header: Authorization: Bearer {token_display}")
         else:
             print(f"  URL:    {local_mcp_url}")
 

mcp_server_core-0.3.0/mcp_server_core/tray.py

@@ -0,0 +1,534 @@
+"""Reusable Windows System Tray Application Base for MCP Services."""
+from __future__ import annotations
+
+import atexit
+import os
+import secrets
+import subprocess
+import sys
+import threading
+import time
+import urllib.request
+import webbrowser
+from pathlib import Path
+from typing import Any, Callable
+
+if sys.platform == "win32":
+    try:
+        sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+        sys.stderr.reconfigure(encoding="utf-8", errors="replace")
+    except Exception:
+        pass
+    try:
+        import ctypes
+        try:
+            ctypes.windll.shcore.SetProcessDpiAwareness(2)
+        except Exception:
+            ctypes.windll.user32.SetProcessDPIAware()
+    except Exception:
+        pass
+
+try:
+    from PIL import Image, ImageDraw, ImageFont
+    import pystray
+    from pystray import MenuItem as item
+except ImportError as err:
+    pystray = None
+    item = None
+
+if sys.platform == "win32":
+    import win32api
+    import win32clipboard
+    import win32con
+    import win32event
+    import win32job
+    import winerror
+else:
+    win32api = win32clipboard = win32con = win32event = win32job = winerror = None
+
+from .env import DeploymentEnvConfig, get_runtime_dir, update_env_variable
+from .process import is_port_in_use, kill_stale_server_process
+from .tunnel import ensure_tunnel_running, stop_tunnel_if_no_mcp
+
+
+def get_server_python_exe() -> str:
+    """Ensure child server runs with python.exe (with CREATE_NO_WINDOW) rather than pythonw.exe."""
+    py_exe = sys.executable
+    if py_exe.lower().endswith("pythonw.exe"):
+        cand = py_exe[:-5] + ".exe"
+        if os.path.exists(cand):
+            return cand
+    return py_exe
+
+
+class ServerProcessSupervisor:
+    """Supervises child MCP server subprocess lifecycle bound to a Windows Job Object."""
+
+    def __init__(self, port: int, cwd: Path, server_cmd: list[str], service_name: str):
+        self.port = port
+        self.cwd = cwd
+        self.server_cmd = server_cmd
+        self.service_name = service_name
+        self.runtime_dir = get_runtime_dir(cwd)
+        self.runtime_dir.mkdir(parents=True, exist_ok=True)
+        self.proc: subprocess.Popen | None = None
+        self.job = None
+        self.status_text = f"● 【运行中】127.0.0.1:{self.port}"
+        self._restarting = False
+        self._init_job_object()
+
+    def _init_job_object(self) -> None:
+        if sys.platform != "win32":
+            return
+        try:
+            job = win32job.CreateJobObject(None, "")
+            info = win32job.QueryInformationJobObject(job, win32job.JobObjectExtendedLimitInformation)
+            info["BasicLimitInformation"]["LimitFlags"] |= win32job.JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE
+            win32job.SetInformationJobObject(job, win32job.JobObjectExtendedLimitInformation, info)
+            self.job = job
+        except Exception:
+            self.job = None
+
+    def kill_stale_server_only(self) -> None:
+        kill_stale_server_process(self.port, self.cwd)
+        time.sleep(0.3)
+
+    def start(self) -> None:
+        self.kill_stale_server_only()
+        ensure_tunnel_running()
+
+        creationflags = subprocess.CREATE_NO_WINDOW if os.name == "nt" else 0
+        env = {**os.environ, "PYTHONUTF8": "1", "PYTHONIOENCODING": "utf-8"}
+
+        self.runtime_dir.mkdir(parents=True, exist_ok=True)
+        log_file = open(self.runtime_dir / "server_error.log", "w", encoding="utf-8")
+        self.proc = subprocess.Popen(
+            self.server_cmd,
+            cwd=str(self.cwd),
+            creationflags=creationflags,
+            env=env,
+            stdout=log_file,
+            stderr=log_file,
+        )
+
+        if self.job and self.proc and getattr(self.proc, "_handle", None):
+            try:
+                win32job.AssignProcessToJobObject(self.job, self.proc._handle)
+            except Exception:
+                pass
+
+    def stop(self) -> None:
+        if self.proc:
+            try:
+                self.proc.terminate()
+                self.proc.wait(timeout=2)
+            except Exception:
+                try:
+                    self.proc.kill()
+                except Exception:
+                    pass
+            self.proc = None
+        self.kill_stale_server_only()
+        stop_tunnel_if_no_mcp()
+
+    def restart_async(self, icon: Any | None = None) -> None:
+        if self._restarting:
+            return
+        threading.Thread(target=self._do_restart, args=(icon,), daemon=True).start()
+
+    def _do_restart(self, icon: Any | None = None) -> None:
+        self._restarting = True
+        self.status_text = f"● 【重启中...】127.0.0.1:{self.port}"
+        if icon:
+            try:
+                icon.update_menu()
+                icon.notify("正在重启 MCP 服务，请稍候...", self.service_name)
+            except Exception:
+                pass
+
+        try:
+            if self.proc:
+                try:
+                    self.proc.terminate()
+                    self.proc.wait(timeout=2)
+                except Exception:
+                    try:
+                        self.proc.kill()
+                    except Exception:
+                        pass
+                self.proc = None
+
+            self.kill_stale_server_only()
+            ensure_tunnel_running()
+
+            creationflags = subprocess.CREATE_NO_WINDOW if os.name == "nt" else 0
+            env = {**os.environ, "PYTHONUTF8": "1", "PYTHONIOENCODING": "utf-8"}
+
+            self.runtime_dir.mkdir(parents=True, exist_ok=True)
+            log_file = open(self.runtime_dir / "server_error.log", "w", encoding="utf-8")
+            self.proc = subprocess.Popen(
+                self.server_cmd,
+                cwd=str(self.cwd),
+                creationflags=creationflags,
+                env=env,
+                stdout=log_file,
+                stderr=log_file,
+            )
+
+            if self.job and self.proc and getattr(self.proc, "_handle", None):
+                try:
+                    win32job.AssignProcessToJobObject(self.job, self.proc._handle)
+                except Exception:
+                    pass
+
+            healthy = False
+            for _ in range(20):
+                time.sleep(0.5)
+                try:
+                    req = urllib.request.Request(f"http://127.0.0.1:{self.port}/health")
+                    with urllib.request.urlopen(req, timeout=1) as resp:
+                        if resp.status == 200:
+                            healthy = True
+                            break
+                except Exception:
+                    pass
+
+            if healthy:
+                self.status_text = f"● 【运行中】127.0.0.1:{self.port}"
+                if icon:
+                    try:
+                        icon.update_menu()
+                        icon.notify(f"服务已重启完成并就绪 (端口 {self.port})", self.service_name)
+                    except Exception:
+                        pass
+            else:
+                self.status_text = f"● 【异常】端口 {self.port} 未响应"
+                if icon:
+                    try:
+                        icon.update_menu()
+                        icon.notify("警告：服务重启超时，健康检查未通过！", self.service_name)
+                    except Exception:
+                        pass
+        finally:
+            self._restarting = False
+
+
+class BaseTrayApp:
+    """Base class for Windows System Tray applications powering local MCP servers."""
+
+    def __init__(
+        self,
+        service_name: str,
+        base_dir: Path | str | None = None,
+        default_port: int = 8788,
+        icon_char: str = "M",
+        icon_color: str = "#00b894",
+        server_module: str | None = "app",
+        server_cmd: list[str] | None = None,
+        custom_menu_builder: Callable[[BaseTrayApp], list[Any]] | None = None,
+    ):
+        if pystray is None:
+            raise RuntimeError(
+                "pystray and pillow are required for BaseTrayApp. Please install them: pip install pystray pillow pywin32"
+            )
+
+        self.service_name = service_name
+        self.base_dir = Path(base_dir).resolve() if base_dir else Path.cwd().resolve()
+        self.runtime_dir = get_runtime_dir(self.base_dir)
+        self.runtime_dir.mkdir(parents=True, exist_ok=True)
+        self.default_port = default_port
+        self.icon_char = icon_char
+        self.icon_color = icon_color
+        self.custom_menu_builder = custom_menu_builder
+
+        self.port = self.get_port()
+        self.mutex_name = f"Local\\{self.service_name.replace(' ', '_')}_{self.port}"
+        self.tray_pid_file = self.runtime_dir / ".tray.pid"
+
+        if server_cmd is not None:
+            self.server_cmd = server_cmd
+        else:
+            py_exe = get_server_python_exe()
+            mod = server_module or "app"
+            self.server_cmd = [py_exe, "-m", mod, "--no-tunnel"]
+
+        self.supervisor = ServerProcessSupervisor(
+            port=self.port,
+            cwd=self.base_dir,
+            server_cmd=self.server_cmd,
+            service_name=self.service_name,
+        )
+        self.icon: pystray.Icon | None = None
+
+    def get_current_env(self) -> DeploymentEnvConfig | None:
+        try:
+            return DeploymentEnvConfig.load(self.base_dir)
+        except Exception:
+            return None
+
+    def get_port(self) -> int:
+        cfg = self.get_current_env()
+        if cfg and cfg.port:
+            return cfg.port
+        return self.default_port
+
+    def get_api_key(self) -> str:
+        cfg = self.get_current_env()
+        if cfg and cfg.api_key:
+            return cfg.api_key
+        return os.getenv("MCP_API_KEY", "")
+
+    def get_public_url(self) -> str:
+        cfg = self.get_current_env()
+        if cfg and cfg.upstream_url:
+            return cfg.upstream_url
+        return os.getenv("TUNNEL_PUBLIC_URL", f"http://127.0.0.1:{self.port}/mcp")
+
+    def record_tray_pid(self) -> None:
+        try:
+            self.runtime_dir.mkdir(parents=True, exist_ok=True)
+            self.tray_pid_file.write_text(str(os.getpid()), encoding="utf-8")
+        except Exception:
+            pass
+
+    def cleanup_tray_pid(self) -> None:
+        for t_file in [self.tray_pid_file, self.base_dir / ".tray.pid"]:
+            try:
+                if t_file.exists():
+                    t_file.unlink()
+            except Exception:
+                pass
+
+    def ensure_single_instance(self) -> Any:
+        if sys.platform != "win32":
+            return None
+        mutex = win32event.CreateMutex(None, False, self.mutex_name)
+        if win32api.GetLastError() == winerror.ERROR_ALREADY_EXISTS:
+            try:
+                win32api.MessageBox(
+                    0,
+                    f"【提示】{self.service_name} 已在系统托盘运行中！\n\n请在任务栏右下角通知区域查看图标。\n如需停止，可右键托盘图标退出或运行 stop.bat。",
+                    self.service_name,
+                    win32con.MB_ICONINFORMATION | win32con.MB_OK | win32con.MB_SYSTEMMODAL,
+                )
+            except Exception:
+                pass
+            sys.exit(0)
+        return mutex
+
+    def copy_to_clipboard(self, text: str) -> None:
+        if sys.platform != "win32":
+            return
+        try:
+            win32clipboard.OpenClipboard()
+            win32clipboard.EmptyClipboard()
+            win32clipboard.SetClipboardText(text, win32con.CF_UNICODETEXT)
+            win32clipboard.CloseClipboard()
+        except Exception as e:
+            print("Clipboard error:", e)
+
+    def message_box(
+        self,
+        text: str,
+        title: str | None = None,
+        flags: int = win32con.MB_ICONINFORMATION | win32con.MB_OK | win32con.MB_SYSTEMMODAL,
+    ) -> int:
+        if sys.platform != "win32":
+            return 0
+        return win32api.MessageBox(0, text, title or self.service_name, flags)
+
+    def choose_folder(self, title: str = "选择文件夹") -> str | None:
+        """Open native high-DPI directory chooser dialog with Tkinter or PowerShell fallback."""
+        try:
+            import tkinter as tk
+            from tkinter import filedialog
+            root = tk.Tk()
+            root.withdraw()
+            root.attributes("-topmost", True)
+
+            ico_path = self.runtime_dir / "app.ico"
+            if not ico_path.exists():
+                try:
+                    self.create_tray_icon().save(ico_path, format="ICO")
+                except Exception:
+                    pass
+            if ico_path.exists():
+                try:
+                    root.iconbitmap(str(ico_path))
+                except Exception:
+                    pass
+
+            folder = filedialog.askdirectory(title=title, parent=root)
+            root.destroy()
+            if folder:
+                return folder
+        except Exception:
+            pass
+
+        try:
+            ps_cmd = (
+                'Add-Type -AssemblyName System.Windows.Forms; '
+                '$fb = New-Object System.Windows.Forms.FolderBrowserDialog; '
+                f'$fb.Description = "{title}"; '
+                '$fb.ShowNewFolderButton = $true; '
+                'if ($fb.ShowDialog() -eq [System.Windows.Forms.DialogResult]::OK) { '
+                '    Write-Output $fb.SelectedPath '
+                '}'
+            )
+            creationflags = subprocess.CREATE_NO_WINDOW if os.name == "nt" else 0
+            res = subprocess.run(
+                ["powershell", "-NoProfile", "-Command", ps_cmd],
+                capture_output=True,
+                text=True,
+                creationflags=creationflags,
+            )
+            out = res.stdout.strip()
+            return out if out else None
+        except Exception:
+            return None
+
+    def create_tray_icon(self) -> Image.Image:
+        """Create round dynamic tray icon with customizable letter and background color."""
+        img = Image.new("RGBA", (64, 64), (0, 0, 0, 0))
+        draw = ImageDraw.Draw(img)
+        draw.ellipse((4, 4, 60, 60), fill=self.icon_color)
+        try:
+            font = ImageFont.truetype("arial.ttf", 36)
+            draw.text((18, 12), self.icon_char, fill="white", font=font)
+        except Exception:
+            draw.text((22, 16), self.icon_char, fill="white")
+        return img
+
+    def build_custom_menu(self) -> list[Any]:
+        """Override this method or pass custom_menu_builder to inject business-specific menu items."""
+        if self.custom_menu_builder:
+            return self.custom_menu_builder(self)
+        return []
+
+    # Standard actions
+    def on_copy_url(self, icon: Any, _menu_item: Any) -> None:
+        url = self.get_public_url()
+        self.copy_to_clipboard(url)
+        try:
+            icon.notify("已复制 MCP 服务器网址:\n" + url, self.service_name)
+        except Exception:
+            pass
+
+    def on_copy_key(self, icon: Any, _menu_item: Any) -> None:
+        key = self.get_api_key()
+        self.copy_to_clipboard(key)
+        try:
+            icon.notify("已复制访问密匙:\n" + key, self.service_name)
+        except Exception:
+            pass
+
+    def on_rotate_key(self, icon: Any, _menu_item: Any) -> None:
+        new_key = f"sec_{secrets.token_urlsafe(16)}"
+        env_file = self.base_dir / ".env"
+        update_env_variable("MCP_API_KEY", new_key, env_file)
+        os.environ["MCP_API_KEY"] = new_key
+        self.copy_to_clipboard(new_key)
+        try:
+            icon.notify(
+                f"已生成新访问密匙并复制到剪贴板！\n{new_key}\n正在平滑重启服务以生效...",
+                self.service_name,
+            )
+        except Exception:
+            pass
+        self.supervisor.restart_async(icon)
+
+    def on_open_health(self, icon: Any, _menu_item: Any) -> None:
+        webbrowser.open(f"http://127.0.0.1:{self.port}/health")
+
+    def on_restart(self, icon: Any, _menu_item: Any) -> None:
+        self.supervisor.restart_async(icon)
+
+    def on_exit(self, icon: Any, _menu_item: Any) -> None:
+        def do_exit():
+            try:
+                icon.title = f"{self.service_name} (正在退出...)"
+                icon.notify(f"{self.service_name} 正在停止服务，请稍候...", self.service_name)
+            except Exception:
+                pass
+            try:
+                self.supervisor.stop()
+            except Exception:
+                pass
+            self.cleanup_tray_pid()
+            try:
+                icon.visible = False
+                icon.stop()
+            except Exception:
+                pass
+            os._exit(0)
+
+        threading.Thread(target=do_exit, daemon=True).start()
+
+    def build_menu(self) -> pystray.Menu:
+        items = []
+
+        # 1. Status header
+        items.append(item(lambda _: self.supervisor.status_text, lambda: None, enabled=False))
+        items.append(pystray.Menu.SEPARATOR)
+
+        # 2. Custom business menu items slot
+        custom_items = self.build_custom_menu()
+        if custom_items:
+            items.extend(custom_items)
+            items.append(pystray.Menu.SEPARATOR)
+
+        # 3. Standard platform tools
+        items.append(item("复制 MCP 服务器网址", self.on_copy_url))
+        items.append(item("复制访问密匙", self.on_copy_key))
+        items.append(item("重设访问密匙", self.on_rotate_key))
+        items.append(item("健康检查", self.on_open_health))
+        items.append(pystray.Menu.SEPARATOR)
+
+        # 4. Lifecycle controls
+        items.append(item("重启", self.on_restart))
+        items.append(item("退出", self.on_exit))
+
+        return pystray.Menu(*items)
+
+    def run(self) -> None:
+        mutex = self.ensure_single_instance()
+
+        if is_port_in_use(self.port):
+            try:
+                self.message_box(
+                    f"{self.service_name} 已在运行中 (端口 {self.port} 已被占用)。\n\n如需切换为无黑框托盘常驻模式，请先运行 stop.bat 停止现有服务后再启动。",
+                    flags=win32con.MB_ICONINFORMATION | win32con.MB_OK | win32con.MB_SYSTEMMODAL,
+                )
+            except Exception:
+                pass
+            sys.exit(0)
+
+        self.record_tray_pid()
+        atexit.register(self.cleanup_tray_pid)
+
+        self.supervisor.start()
+
+        self.icon = pystray.Icon(
+            name=f"{self.service_name.lower().replace(' ', '_')}_tray",
+            icon=self.create_tray_icon(),
+            title=f"{self.service_name} (端口 {self.port})",
+            menu=self.build_menu(),
+        )
+
+        try:
+            self.icon.run()
+        except Exception as e:
+            import traceback
+            try:
+                (self.runtime_dir / "tray_debug.log").write_text(
+                    f"Exception: {e}\n{traceback.format_exc()}", encoding="utf-8"
+                )
+            except Exception:
+                pass
+        finally:
+            try:
+                self.supervisor.stop()
+            except Exception:
+                pass
+            self.cleanup_tray_pid()
+            os._exit(0)

{mcp_server_core-0.2.2 → mcp_server_core-0.3.0/mcp_server_core.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcp-server-core
-Version: 0.2.2
+Version: 0.3.0
 Summary: Universal MCP Server Framework: Streamable HTTP ASGI, Cloudflare Tunnel, OAuth 2.1 & Process Supervisor
 Author: yimmr
 License-Expression: MIT
@@ -19,6 +19,9 @@ Requires-Dist: uvicorn>=0.27.0
 Requires-Dist: pywin32>=306; platform_system == "Windows"
 Provides-Extra: test
 Requires-Dist: httpx>=0.27.0; extra == "test"
+Provides-Extra: tray
+Requires-Dist: pystray>=0.19.5; extra == "tray"
+Requires-Dist: pillow>=10.0.0; extra == "tray"
 Dynamic: license-file
 
 # MCP Server Core 🚀

{mcp_server_core-0.2.2 → mcp_server_core-0.3.0}/mcp_server_core.egg-info/SOURCES.txt

@@ -4,16 +4,22 @@ pyproject.toml
 mcp_framework/__init__.py
 mcp_framework/env.py
 mcp_framework/http_server.py
+mcp_framework/launcher.py
 mcp_framework/oauth.py
 mcp_framework/process.py
+mcp_framework/response.py
 mcp_framework/server.py
+mcp_framework/tray.py
 mcp_framework/tunnel.py
 mcp_server_core/__init__.py
 mcp_server_core/env.py
 mcp_server_core/http_server.py
+mcp_server_core/launcher.py
 mcp_server_core/oauth.py
 mcp_server_core/process.py
+mcp_server_core/response.py
 mcp_server_core/server.py
+mcp_server_core/tray.py
 mcp_server_core/tunnel.py
 mcp_server_core.egg-info/PKG-INFO
 mcp_server_core.egg-info/SOURCES.txt

{mcp_server_core-0.2.2 → mcp_server_core-0.3.0}/mcp_server_core.egg-info/requires.txt

@@ -7,3 +7,7 @@ pywin32>=306
 
 [test]
 httpx>=0.27.0
+
+[tray]
+pystray>=0.19.5
+pillow>=10.0.0

{mcp_server_core-0.2.2 → mcp_server_core-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "mcp-server-core"
-version = "0.2.2"
+version = "0.3.0"
 description = "Universal MCP Server Framework: Streamable HTTP ASGI, Cloudflare Tunnel, OAuth 2.1 & Process Supervisor"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -31,6 +31,10 @@ dependencies = [
 test = [
     "httpx>=0.27.0",
 ]
+tray = [
+    "pystray>=0.19.5",
+    "pillow>=10.0.0",
+]
 
 [tool.setuptools.packages.find]
 where = ["."]