pose-platform 1.24.0__py3-none-any.whl

capabilities/mcp_server.py

@@ -0,0 +1,239 @@
+"""
+capabilities/mcp_server.py
+统一 MCP Server — 所有产品线连接同一个服务端
+
+启动：  python -m capabilities.mcp_server
+注册：  .claude/settings.json 中 mcpServers.pose-analysis
+"""
+from __future__ import annotations
+import json, os, glob
+from pathlib import Path
+
+DATA_DIR = Path(os.environ.get("POSE_DATA_DIR", "./data"))
+
+try:
+    from mcp.server.fastmcp import FastMCP
+    mcp = FastMCP("pose-analysis")
+    MCP_AVAILABLE = True
+except ImportError:
+    mcp = None
+    MCP_AVAILABLE = False
+    print("[MCP] fastmcp 未安装，MCP Server 以 stub 模式运行（功能测试仍可用）")
+
+
+def _run_tool(tool_name: str, tool_input: dict) -> str:
+    from capabilities.tools.registry import registry
+    import tempfile
+    tool = registry.get(tool_name)
+    if tool is None:
+        return json.dumps({"error": f"Tool {tool_name!r} 未注册"})
+    outdir = Path(tempfile.mkdtemp())
+    return tool.safe_run(tool_input, outdir)
+
+
+if MCP_AVAILABLE:
+    # 仅向 MCP 暴露在 registry 中已注册的 tool（受 POSE_ENABLE_WIP_TOOLS 门禁约束）
+    # wip tool 在 prod 部署中不出现在客户端工具列表，避免暴露未稳定能力
+    from capabilities.tools.registry import registry as _registry
+    _registered_names = set(_registry.names())
+
+    def _maybe_tool(tool_name: str):
+        """条件装饰器：仅当 tool_name 在 registry 中才用 @mcp.tool() 注册。
+
+        若 tool 是 wip 且当前环境不开启（POSE_ENABLE_WIP_TOOLS != "1"），返回 no-op 装饰器，
+        函数仍定义在 module 里但不向 MCP server 暴露。"""
+        if tool_name in _registered_names:
+            return mcp.tool()
+        return lambda fn: fn
+
+    @mcp.resource("pose://sessions/{filename}")
+    def get_session(filename: str) -> str:
+        path = DATA_DIR / filename
+        return path.read_text(encoding="utf-8") if path.exists() else f"文件不存在: {filename}"
+
+    @mcp.resource("pose://sessions/index")
+    def list_sessions() -> str:
+        files = sorted(DATA_DIR.glob("*.csv")) if DATA_DIR.exists() else []
+        return json.dumps([{"filename": f.name, "size_kb": f.stat().st_size // 1024}
+                           for f in files], ensure_ascii=False)
+
+    @_maybe_tool("detect_peak_energy")
+    def detect_peak_energy(path: str, fps: float = 30.0,
+                           prominence: float = 0.1) -> dict:
+        """检测运动峰值能量时刻，自动排除抖动帧"""
+        return json.loads(_run_tool("detect_peak_energy",
+                                   {"path": path, "fps": fps, "prominence": prominence}))
+
+    @_maybe_tool("stats")
+    def stats(path: str) -> dict:
+        """全面统计分析：运动幅度、数据质量、关节角度范围"""
+        return json.loads(_run_tool("stats", {"path": path}))
+
+    @_maybe_tool("detect_velocity")
+    def detect_velocity(path: str, joint: str = "body_position",
+                        smooth: bool = True) -> dict:
+        """计算关节移动速度（默认 body_position 世界坐标，反映全身位移速度）"""
+        return json.loads(_run_tool("detect_velocity",
+                                   {"path": path, "joint": joint, "smooth": smooth}))
+
+    @_maybe_tool("detect_swing_multifeature")
+    def detect_swing_multifeature(
+        path: str,
+        joint: str = "right_hand_joint",
+        arm_joint: str = "right_arm_joint",
+        shoulder_joint: str = "right_shoulder_1_joint",
+        coord: str = "mpoint",
+        smooth: bool = True,
+        min_hand_speed: float = 6.0,
+        min_swing_gap_s: float = 1.5,
+        max_swing_width_s: float = 2.5,
+        min_arm_engagement: float = 0.14,
+        fast_bypass_speed: float = 20.0,
+        min_shoulder_speed: float = 0.85,
+        shoulder_check_threshold: float = 8.0,
+        low_speed_arm_threshold: float = 0.22,
+        low_speed_shou_threshold: float = 0.75,
+        min_dir_dot: float = 0.95,
+        include_hour: bool = False,
+    ) -> dict:
+        """多关节挥拍检测：输出每次挥拍及其对应引拍谷底时刻，过滤假阳性（v1.1.0）
+        每条 swing 记录新增 backswing_frame/backswing_time/backswing_s/backswing_speed/backswing_shallow，
+        顶层新增 backswing_count（始终等于 swing_count）。"""
+        return json.loads(_run_tool("detect_swing_multifeature", {
+            "path": path,
+            "joint": joint,
+            "arm_joint": arm_joint,
+            "shoulder_joint": shoulder_joint,
+            "coord": coord,
+            "smooth": smooth,
+            "min_hand_speed": min_hand_speed,
+            "min_swing_gap_s": min_swing_gap_s,
+            "max_swing_width_s": max_swing_width_s,
+            "min_arm_engagement": min_arm_engagement,
+            "fast_bypass_speed": fast_bypass_speed,
+            "min_shoulder_speed": min_shoulder_speed,
+            "shoulder_check_threshold": shoulder_check_threshold,
+            "low_speed_arm_threshold": low_speed_arm_threshold,
+            "low_speed_shou_threshold": low_speed_shou_threshold,
+            "min_dir_dot": min_dir_dot,
+            "include_hour": include_hour,
+        }))
+
+    @_maybe_tool("classify_stroke_type")
+    def classify_stroke_type(
+        path: str,
+        joint: str = "right_hand_joint",
+        arm_joint: str = "right_arm_joint",
+        shoulder_joint: str = "right_shoulder_1_joint",
+        forearm_joint: str = "right_forearm_joint",
+        coord: str = "mpoint",
+        smooth: bool = True,
+        min_hand_speed: float = 6.0,
+        min_swing_gap_s: float = 1.5,
+    ) -> dict:
+        """羽毛球动作 4 层分类（v1.0.0）：输出每拍球路标签（杀球/高远球/平高球/吊球/抽球/推球/挑球/网前球等）及分类依据特征"""
+        return json.loads(_run_tool("classify_stroke_type", {
+            "path": path,
+            "joint": joint,
+            "arm_joint": arm_joint,
+            "shoulder_joint": shoulder_joint,
+            "forearm_joint": forearm_joint,
+            "coord": coord,
+            "smooth": smooth,
+            "min_hand_speed": min_hand_speed,
+            "min_swing_gap_s": min_swing_gap_s,
+        }))
+
+    @_maybe_tool("measure_running_speed")
+    def measure_running_speed(
+        path: str,
+        smooth: bool = True,
+        coord_mode: str = "horizontal",
+        series_resolution: str = "raw",
+        age: int | None = None,
+        gender: str = "male",
+        race_distance_m: int = 100,
+        region: str = "cn",
+    ) -> dict:
+        """测量跑步速度（sport=sprint）：输出合速度统计 (m/s & km/h)、时序曲线、数据质量诊断。
+        传入 age + gender + race_distance_m + region 同时输出青少年评级（assessment 字段）。
+        coord_mode: horizontal=XZ 平面（默认）/ 3d。
+        series_resolution: raw / downsampled（0.2s 间隔）。
+        race_distance_m: 100（默认）/ 50（仅 cn region 支持）。
+        region: cn=中国教育部+体育总局 / us=USATF Junior Olympics / ca=Athletics Canada Youth。"""
+        payload = {
+            "path": path,
+            "smooth": smooth,
+            "coord_mode": coord_mode,
+            "series_resolution": series_resolution,
+            "gender": gender,
+            "race_distance_m": race_distance_m,
+            "region": region,
+        }
+        if age is not None:
+            payload["age"] = age
+        return json.loads(_run_tool("measure_running_speed", payload))
+
+    @_maybe_tool("detect_action_boundaries")
+    def detect_action_boundaries(
+        path: str,
+        onset_energy_ratio: float = 0.01,
+        max_filter_win_s: float = 0.3,
+        prominence: float = 0.05,
+        min_action_duration_s: float = 0.3,
+        min_peak_gap_s: float = 0.5,
+    ) -> dict:
+        """通用动作区间检测：从全身位移能量找到动作的 onset/offset 边界，输出 start_s/peak_s/end_s。
+        适用于短跑、跳跃等非羽毛球运动；onset_energy_ratio=0.01（1% 峰值能量）对 sprint 准备阶段覆盖准确。"""
+        return json.loads(_run_tool("detect_action_boundaries", {
+            "path": path,
+            "onset_energy_ratio": onset_energy_ratio,
+            "max_filter_win_s": max_filter_win_s,
+            "prominence": prominence,
+            "min_action_duration_s": min_action_duration_s,
+            "min_peak_gap_s": min_peak_gap_s,
+        }))
+
+    @_maybe_tool("detect_highlight")
+    def detect_highlight(
+        path: str,
+        sport_id: str | None = None,
+        max_highlights: int = 3,
+        onset_energy_ratio: float = 0.01,
+    ) -> dict:
+        """高光时刻统一入口：自动路由到最优分析路径，返回 highlights[].start_s/peak_s/end_s。
+        sport_id=badminton → detect_swing_multifeature；sprint/通用 → detect_action_boundaries；
+        无结果降级到 detect_peak_energy+±0.5s 扩展。"""
+        payload: dict = {
+            "path": path,
+            "max_highlights": max_highlights,
+            "onset_energy_ratio": onset_energy_ratio,
+        }
+        if sport_id is not None:
+            payload["sport_id"] = sport_id
+        return json.loads(_run_tool("detect_highlight", payload))
+
+    @_maybe_tool("compare_with_reference")
+    def compare_with_reference(path: str, reference_id: str = "") -> dict:
+        """与参考标准对比关节偏差"""
+        payload: dict = {"path": path}
+        if reference_id:
+            payload["reference_id"] = reference_id
+        return json.loads(_run_tool("compare_with_reference", payload))
+
+    @mcp.prompt()
+    def analyze_session(filename: str) -> str:
+        """标准 session 分析流程模板"""
+        return f"""
+请对 session 文件 {filename} 进行完整分析：
+1. 先用 stats("{filename}") 了解数据结构和质量
+2. 用 detect_peak_energy("{filename}") 找出运动峰值
+3. 用中文输出分析报告，包含数据质量摘要、运动峰值时间线、最活跃关节排名
+"""
+
+    if __name__ == "__main__":
+        mcp.run()
+else:
+    def run_tool_directly(tool_name: str, **kwargs) -> dict:
+        """MCP 不可用时的直接调用接口（用于测试）"""
+        return json.loads(_run_tool(tool_name, kwargs))