feat: non-resource interface support for ecs V2 (#360)

Author: CJ-HHH

server/mcp_server_ecs/README.md

@@ -14,23 +14,40 @@ ECS
 ## Features
 
 - Query instance information
-- Query event information 
+- Query event information
 - Query region information
 - Simple instance operations
+- Event subscription management
+- Instance console diagnostics
 
 ## Available Tools
 Since some interfaces have a lot of input parameters and return content, some uncommon content will cause too much context burden on llm. In order to avoid unnecessary token waste, ECS MCP Server only provides queries for common content.
 
+### Instance Management
 - `describe_instances`: [query instance list](https://www.volcengine.com/docs/6396/70466)
 - `describe_images`: [query image list](https://www.volcengine.com/docs/6396/70808)
 - `describe_instance_types`: [query instance type list](https://www.volcengine.com/docs/6396/92769)
+- `describe_instance_type_families`: [query instance type family list](https://www.volcengine.com/docs/6396/120172)
 - `describe_available_resource`: [query available resources](https://www.volcengine.com/docs/6396/76279)
-- `describe_system_events`: [query system events](https://www.volcengine.com/docs/6396/129399)
-- `describe_regions`: [query region list](https://www.volcengine.com/docs/6396/1053194)
-- `describe_zones`: [query availability zone list](https://www.volcengine.com/docs/6396/120518)
 - `start_instances`: [start instances](https://www.volcengine.com/docs/6396/101068)
 - `renew_instance`: [renew instance](https://www.volcengine.com/docs/6396/76276)
 
+### Region & Availability Zone
+- `describe_regions`: [query region list](https://www.volcengine.com/docs/6396/1053194)
+- `describe_zones`: [query availability zone list](https://www.volcengine.com/docs/6396/120518)
+
+### System Events
+- `describe_system_events`: [query system events](https://www.volcengine.com/docs/6396/129399)
+- `update_system_events`: [update system event status](https://www.volcengine.com/docs/6396/129400)
+- `describe_event_types`: [query event type list](https://www.volcengine.com/docs/6396/196424)
+
+### Event Subscription
+- `describe_subscriptions`: [query event subscription list](https://www.volcengine.com/docs/6396/166018)
+
+### Instance Diagnostics
+- `get_console_output`: [get instance console output](https://www.volcengine.com/docs/6396/176876)
+- `get_console_screenshot`: [get instance console screenshot](https://www.volcengine.com/docs/6396/176875)
+
 ## Usage Guide
 
 ### Prerequisites

server/mcp_server_ecs/README_zh.md

@@ -16,20 +16,37 @@ ECS MCP Server 是一个模型上下文协议(Model Context Protocol)服务器
 - 查询事件信息
 - 查询地域信息
 - 简单操作实例
+- 事件订阅管理
+- 实例控制台诊断
 
 ## 可用工具
 由于部分接口的入参和返回内容较多，一些不常用的内容会对大模型造成过长的上下文负担，为了避免不必要的token浪费，ECS MCP Server仅提供常见内容的查询。
 
+### 实例管理
 - `describe_instances`: [查询实例列表](https://www.volcengine.com/docs/6396/70466)
 - `describe_images`: [查询镜像列表](https://www.volcengine.com/docs/6396/70808)
 - `describe_instance_types`: [查询实例规格列表](https://www.volcengine.com/docs/6396/92769)
+- `describe_instance_type_families`: [查询实例规格族列表](https://www.volcengine.com/docs/6396/120172)
 - `describe_available_resource`: [查询可用资源](https://www.volcengine.com/docs/6396/76279)
-- `describe_system_events`: [查询系统事件](https://www.volcengine.com/docs/6396/129399)
-- `describe_regions`: [查询地域列表](https://www.volcengine.com/docs/6396/1053194)
-- `describe_zones`: [查询可用区列表](https://www.volcengine.com/docs/6396/120518)
 - `start_instances`: [启动实例](https://www.volcengine.com/docs/6396/101068)
 - `renew_instance`: [续费实例](https://www.volcengine.com/docs/6396/76276)
 
+### 地域与可用区
+- `describe_regions`: [查询地域列表](https://www.volcengine.com/docs/6396/1053194)
+- `describe_zones`: [查询可用区列表](https://www.volcengine.com/docs/6396/120518)
+
+### 系统事件
+- `describe_system_events`: [查询系统事件](https://www.volcengine.com/docs/6396/129399)
+- `update_system_events`: [更新系统事件状态](https://www.volcengine.com/docs/6396/129400)
+- `describe_event_types`: [查询事件类型列表](https://www.volcengine.com/docs/6396/196424)
+
+### 事件订阅
+- `describe_subscriptions`: [查询事件订阅列表](https://www.volcengine.com/docs/6396/166018)
+
+### 实例诊断
+- `get_console_output`: [获取实例控制台输出](https://www.volcengine.com/docs/6396/176876)
+- `get_console_screenshot`: [获取实例控制台截图](https://www.volcengine.com/docs/6396/176875)
+
 ## 使用指南
 
 ### 前置准备

server/mcp_server_ecs/pyproject.toml

@@ -11,6 +11,7 @@ dependencies = [
     "concurrent-log-handler==0.9.25",
     "dynaconf==3.2.10",
     "jsonref>=1.1.0",
+    "aiohttp>=3.13.2"
 ]
 
 [tool.hatch.metadata]

server/mcp_server_ecs/src/mcp_server_ecs/common/errors.py

@@ -1,34 +1,29 @@
-from mcp import types
-
 from mcp_server_ecs.common.logs import LOG
 
 
-# handle empty response error
-def _handle_empty_response(action_name):
-    LOG.error(f"{action_name} returned empty response")
-    return [types.TextContent(type="text", text="Error: empty response")]
-
-
-# handle exception error
-def _handle_exception(action_name, error):
-    LOG.error(f"Exception when calling {action_name}: {str(error)}")
-    return [types.TextContent(type="text", text=f"Error: {str(error)}")]
+class ToolExecutionError(Exception):
+    """工具执行错误，会被框架捕获并设置 isError=True"""
+    pass
 
 
-def handle_error(action_name, error=None):
-    """Handle API error response
+def handle_error(action_name: str, error: Exception | None = None) -> None:
+    """
+    处理 API 错误，抛出异常让框架设置 isError=True
+    
+    符合 MCP 规范：通过抛出异常让框架自动设置 CallToolResult.isError = True，
+    而不是返回错误文本（那样 isError 会保持 False）。
 
     Args:
         action_name: API action name
         error: Exception object (optional)
-
-    Returns:
-        A list of TextContent objects representing the error in a unified format
+    
+    Raises:
+        ToolExecutionError: 包含错误信息的异常
     """
-    # create a mapping table for handling functions
-    handlers = {
-        True: lambda: _handle_exception(action_name, error),
-        False: lambda: _handle_empty_response(action_name),
-    }
-
-    return handlers[error is not None]()
+    if error:
+        error_msg = str(error)
+        LOG.error(f"Exception when calling {action_name}: {error_msg}")
+        raise ToolExecutionError(error_msg) from error
+    else:
+        LOG.error(f"{action_name} returned empty response")
+        raise ToolExecutionError("empty response")

server/mcp_server_ecs/src/mcp_server_ecs/common/middleware.py

@@ -0,0 +1,116 @@
+"""
+MCP Server Metrics 中间件
+
+用于统计工具调用次数、成功/失败率、耗时等指标。
+输出结构化日志，便于 TLS 等日志采集系统解析统计。
+
+实现原理:
+    通过替换 MCP Server 底层的 CallToolRequest handler，
+    在请求处理层面拦截所有工具调用，实现真正的中间件效果。
+
+使用方式:
+    from mcp_server_ecs.common.middleware import install_metrics_handler
+    
+    mcp = FastMCP("ECS MCP Server", ...)
+    
+    # 在所有 @mcp.tool() 注册完成后，启动前调用
+    install_metrics_handler(mcp)
+
+日志输出格式:
+    [MCP_METRICS] {"timestamp": 1701590400.123, "type": "tool_call", "tool": "describe_instances", "status": "success", "duration_ms": 45.23}
+"""
+
+import json
+import time
+from typing import TYPE_CHECKING
+
+from mcp import types
+
+from mcp_server_ecs.common.logs import LOG
+
+if TYPE_CHECKING:
+    from mcp.server.fastmcp import FastMCP
+
+# 日志前缀，便于 TLS 过滤
+LOG_PREFIX = "[MCP_METRICS]"
+
+
+def _log_metric(**kwargs) -> None:
+    """输出结构化日志"""
+    log_data = {
+        "timestamp": time.time(),
+        "type": "tool_call",
+        **kwargs
+    }
+    metric_log = f"{LOG_PREFIX} {json.dumps(log_data, ensure_ascii=False)}"
+    LOG.info(metric_log)
+
+
+def install_metrics_handler(mcp: "FastMCP") -> None:
+    """
+    安装 metrics handler，拦截所有 CallToolRequest
+    
+    这是真正的中间件方案，通过替换底层 request handler 实现，
+    不需要修改任何工具代码，对所有工具调用生效。
+    
+    注意: 必须在所有 @mcp.tool() 注册完成后调用
+    
+    Args:
+        mcp: FastMCP 实例
+    
+    TLS 采集配置建议:
+    - 过滤规则: 包含 "[MCP_METRICS]"
+    - JSON 解析: 提取日志中的 JSON 部分
+    - 聚合统计: count by tool, status
+    """
+    server = mcp._mcp_server
+    original_handler = server.request_handlers[types.CallToolRequest]
+    
+    async def metrics_handler(req: types.CallToolRequest) -> types.ServerResult:
+        """带 metrics 统计的 CallToolRequest handler"""
+        tool_name = req.params.name if req.params else "unknown"
+        start_time = time.time()
+        
+        try:
+            result = await original_handler(req)
+            duration_ms = (time.time() - start_time) * 1000
+            
+            # result 是 ServerResult，内部包含 CallToolResult
+            # 需要检查 result.root.isError
+            is_error = False
+            error_msg = None
+            if hasattr(result, 'root') and hasattr(result.root, 'isError'):
+                is_error = result.root.isError
+                # 如果是错误，提取错误信息
+                if is_error and hasattr(result.root, 'content'):
+                    for content in result.root.content:
+                        if hasattr(content, 'text'):
+                            error_msg = content.text
+                            break
+            
+            metric_data = {
+                "tool": tool_name,
+                "status": "error" if is_error else "success",
+                "duration_ms": round(duration_ms, 2),
+            }
+            if error_msg:
+                metric_data["error_msg"] = error_msg
+            
+            _log_metric(**metric_data)
+            return result
+            
+        except Exception as e:
+            duration_ms = (time.time() - start_time) * 1000
+            
+            _log_metric(
+                tool=tool_name,
+                status="error",
+                duration_ms=round(duration_ms, 2),
+                error_type=type(e).__name__,
+                error_msg=str(e),
+            )
+            raise
+    
+    # 替换 handler
+    server.request_handlers[types.CallToolRequest] = metrics_handler
+    LOG.info("MCP metrics handler installed - all tool calls will be monitored")

server/mcp_server_ecs/src/mcp_server_ecs/main.py

@@ -7,6 +7,7 @@
 import argparse
 
 from mcp_server_ecs.common.logs import LOG
+from mcp_server_ecs.common.middleware import install_metrics_handler
 from mcp_server_ecs.tools import event, instance, mcp, region
 
 
@@ -24,6 +25,9 @@ def main():
     LOG.info(
         f"Including tool types: {event.__name__}, {instance.__name__}, {region.__name__}"
     )
+    
+    install_metrics_handler(mcp)
+    
     LOG.info(f"Starting ECS MCP Server with {args.transport} transport")
 
     mcp.run(transport=args.transport)