mcp-supervisor-core 0.1.0__tar.gz

mcp_supervisor_core-0.1.0/.gitignore

@@ -0,0 +1,89 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual Environment
+venv/
+env/
+ENV/
+.venv
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+logs/
+
+# Test
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Rust / Tauri
+packages/desktop/target/
+packages/desktop/gen/
+
+# MCP specific
+.mcp/
+*.mcp.json
+
+# Workbench UI
+packages/workbench-ui/node_modules/
+packages/workbench-ui/dist/
+packages/workbench-server/src/mcp_supervisor_workbench/static/assets/
+packages/workbench-server/src/mcp_supervisor_workbench/static/index.html
+src/mcp_ai_supervisor/workbench/static/assets/
+src/mcp_ai_supervisor/workbench/static/index.html
+
+# Node modules 兜底 — 任何子目录下的 node_modules 都不入库，防止未来重现 dashboard-ui/node_modules 这种事故
+**/node_modules/
+
+# Reference repositories (top-level only)
+/references/
+# Allow skill references subdirectories
+!.cursor/skills/**/references/
+!packages/workbench-server/resources/skills/**/references/
+# tgit-cursor-hook-scaffold
+.cursor/hooks.json
+.cursor/hooks/after-file-edit.js
+# tgit-cursor-hook-logs
+.cursor/hooks/logs/
+
+# Generated reports
+code-stats-report.md
+
+# PyPI credentials
+.pypi-credentials
+
+# cursor-memory
+.cursor/memory/
+.cursor/hooks/capture-user-message.sh
+.cursor/hooks/capture-feedback-message.sh
+.cursor/rules/memory-system.mdc

mcp_supervisor_core-0.1.0/PKG-INFO

@@ -0,0 +1,6 @@
+Metadata-Version: 2.4
+Name: mcp-supervisor-core
+Version: 0.1.0
+Summary: MCP AI Supervisor 基础设施（日志、路径、错误处理、国际化、资源管理）
+Requires-Python: >=3.11
+Requires-Dist: psutil>=7.0.0

mcp_supervisor_core-0.1.0/README.md

@@ -0,0 +1,87 @@
+# mcp-supervisor-core
+
+MCP AI Supervisor 基础设施包，提供日志、路径、国际化、错误处理等底层工具。被 `mcp-server` 和 `workbench-server` 共同依赖。
+
+## 包信息
+
+- **包名**: `mcp-supervisor-core`
+- **模块名**: `mcp_supervisor_core`
+- **版本**: 0.1.0
+- **依赖**: `psutil>=7.0.0`
+
+## 模块结构
+
+```
+mcp_supervisor_core/
+├── __init__.py           # 包入口，导出版本号
+├── log_writer.py         # 结构化日志系统（核心模块）
+├── paths.py              # 路径标准化和项目哈希
+├── i18n.py               # 国际化（多语言支持）
+├── error_handler.py      # 统一错误处理
+├── resource_manager.py   # 资源管理（文件/目录生命周期）
+├── memory_monitor.py     # 内存使用监控
+└── debug.py              # 调试工具
+```
+
+## 核心模块
+
+### `log_writer` — 结构化日志系统
+
+所有进程共用的日志模块，替代散落的 `logging`/`print` 调用。
+
+**特性**：
+- 按进程类型（`agent`/`dashboard`/`tauri`）分目录存储
+- 按天自动轮转，过期日志自动清理（默认 30 天）
+- 结构化格式：`{timestamp} [{level}] [{module}] [{context}] {message}`
+- 线程安全，支持上下文预绑定（`bind`）
+
+**核心类**：`SupervisorLogger`
+
+```python
+from mcp_supervisor_core.log_writer import get_logger
+
+logger = get_logger("agent", project_directory="/path/to/project")
+session_logger = logger.bind(project="myapp", session="abc123")
+session_logger.info("feedback", "[SESSION_CREATE] 新会话创建")
+```
+
+### `paths` — 路径工具
+
+```python
+from mcp_supervisor_core.paths import normalize_path, project_hash
+
+normalized = normalize_path("~/projects/my-app")  # → /Users/xxx/projects/my-app
+hash_id = project_hash("/Users/xxx/projects/my-app")  # → "a1b2c3d4_my-app"
+```
+
+### `i18n` — 国际化
+
+提供多语言支持（中文、英文、繁体中文），根据环境变量 `MCP_LANGUAGE` 自动选择语言。
+
+### `error_handler` — 错误处理
+
+统一的异常捕获和格式化，用于 MCP 工具调用中的错误响应生成。
+
+### `memory_monitor` — 内存监控
+
+监控当前进程的内存使用，在内存超限时发出警告。
+
+### `resource_manager` — 资源管理
+
+管理临时文件和目录的生命周期（创建、清理、过期检测）。
+
+## 安装
+
+```bash
+# 作为 workspace 依赖（推荐）
+uv pip install -e packages/core
+
+# 在其他包的 pyproject.toml 中引用
+# dependencies = ["mcp-supervisor-core>=0.1.0"]
+```
+
+## 设计原则
+
+1. **零外部依赖**（除 `psutil`）：确保所有依赖此包的上层模块不会因 core 引入额外依赖
+2. **纯工具性质**：不含业务逻辑，只提供基础设施
+3. **线程安全**：所有模块均考虑多线程/多进程场景

mcp_supervisor_core-0.1.0/pyproject.toml

@@ -0,0 +1,13 @@
+[project]
+name = "mcp-supervisor-core"
+version = "0.1.0"
+description = "MCP AI Supervisor 基础设施（日志、路径、错误处理、国际化、资源管理）"
+requires-python = ">=3.11"
+dependencies = ["psutil>=7.0.0"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mcp_supervisor_core"]

mcp_supervisor_core-0.1.0/src/mcp_supervisor_core/__init__.py

@@ -0,0 +1,7 @@
+"""MCP Supervisor Core — 基础设施包
+
+提供日志、路径、错误处理、国际化等底层工具，
+被 mcp-server 和 workbench-server 共同依赖。
+"""
+
+__version__ = "0.1.0"

mcp_supervisor_core-0.1.0/src/mcp_supervisor_core/debug.py

@@ -0,0 +1,141 @@
+#!/usr/bin/env python3
+"""
+統一調試日誌模組
+================
+
+提供統一的調試日誌功能，確保調試輸出不會干擾 MCP 通信。
+所有調試輸出都會發送到 stderr，並且只在調試模式啟用時才輸出。
+
+使用方法：
+```python
+from .debug import debug_log
+
+debug_log("這是一條調試信息")
+```
+
+環境變數控制：
+- MCP_DEBUG=true/1/yes/on: 啟用調試模式
+- MCP_DEBUG=false/0/no/off: 關閉調試模式（默認）
+
+作者: Minidoracat
+"""
+
+import os
+import sys
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+# === 文件日志句柄（懒初始化，按日期自动切换） ===
+_log_file = None
+_log_date: str = ""
+
+
+def _get_file_logger():
+    """获取当日的文件日志句柄，日期变化时自动切换新文件。"""
+    global _log_file, _log_date
+    today = datetime.now().strftime("%Y-%m-%d")
+    if _log_file is not None and _log_date == today:
+        return _log_file
+    # 关闭旧句柄
+    if _log_file is not None:
+        try:
+            _log_file.close()
+        except Exception:
+            pass
+    try:
+        log_dir = Path.home() / ".mcp" / "logs"
+        log_dir.mkdir(parents=True, exist_ok=True)
+        _log_file = open(log_dir / f"mcp-supervisor-{today}.log", "a", encoding="utf-8")
+        _log_date = today
+    except Exception:
+        _log_file = None
+    return _log_file
+
+
+def debug_log(message: Any, prefix: str = "DEBUG") -> None:
+    """
+    输出调试信息到 stderr + 文件日志，避免污染 stdout（MCP JSON-RPC 通信通道）
+
+    - **stderr**: 仅在 ``MCP_DEBUG=true`` 时输出，供 IDE 捕获
+    - **文件日志**: 始终写入 ``~/.mcp/logs/mcp-supervisor-YYYY-MM-DD.log``，
+      确保即使 IDE 不捕获 stderr 也有日志可查
+
+    Args:
+        message: 要输出的调试信息
+        prefix: 调试信息的前缀标识，默认为 "DEBUG"
+    """
+    try:
+        if not isinstance(message, str):
+            message = str(message)
+    except Exception:
+        return
+
+    timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+    formatted = f"[{prefix}] {message}"
+
+    # === 写入 stderr（仅 MCP_DEBUG 开启时） ===
+    if os.getenv("MCP_DEBUG", "").lower() in ("true", "1", "yes", "on"):
+        try:
+            print(formatted, file=sys.stderr, flush=True)
+        except UnicodeEncodeError:
+            safe = message.encode("ascii", errors="replace").decode("ascii")
+            print(f"[{prefix}] {safe}", file=sys.stderr, flush=True)
+        except Exception:
+            pass
+
+    # === 写入文件日志（始终写入） ===
+    try:
+        fh = _get_file_logger()
+        if fh is not None:
+            fh.write(f"{timestamp} {formatted}\n")
+            fh.flush()
+    except Exception:
+        pass
+
+
+def i18n_debug_log(message: Any) -> None:
+    """國際化模組專用的調試日誌"""
+    debug_log(message, "I18N")
+
+
+def server_debug_log(message: Any) -> None:
+    """伺服器模組專用的調試日誌"""
+    debug_log(message, "SERVER")
+
+
+def web_debug_log(message: Any) -> None:
+    """Web UI 模組專用的調試日誌"""
+    debug_log(message, "WEB")
+
+
+# === 日志限流器 ===
+_rate_limit_last: dict[str, float] = {}
+
+
+def debug_log_throttled(
+    message: Any,
+    prefix: str = "DEBUG",
+    *,
+    key: str,
+    interval_seconds: float = 60.0,
+) -> None:
+    """限流版 debug_log：同一 key 在 interval_seconds 内最多输出一次。"""
+    import time
+
+    now = time.monotonic()
+    last = _rate_limit_last.get(key, 0.0)
+    if now - last < interval_seconds:
+        return
+    _rate_limit_last[key] = now
+    debug_log(message, prefix)
+
+
+def is_debug_enabled() -> bool:
+    """檢查是否啟用了調試模式"""
+    return os.getenv("MCP_DEBUG", "").lower() in ("true", "1", "yes", "on")
+
+
+def set_debug_mode(enabled: bool) -> None:
+    """設置調試模式（用於測試）"""
+    os.environ["MCP_DEBUG"] = "true" if enabled else "false"