feat: support list span & trace detail in apmplus

Author: danielqsj

server/mcp_server_apmplus/.gitignore

@@ -0,0 +1,159 @@
+### Python template
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+.idea/
+.DS_Store

server/mcp_server_apmplus/README.md

@@ -2,38 +2,69 @@
 
 The MCP Server officially launched by the Application Performance Monitoring service can accurately convert natural language into observable analysis statements. It efficiently analyzes observable data including metrics, traces, and logs, helping you comprehensively ensure the entire lifecycle of your applications and improve the efficiency of troubleshooting and problem-solving.
 
-| Version | v0.1.0 |
-| :-: |:----------------:|
+| Version |                                              v0.2.0                                               |
+| :-: |:-------------------------------------------------------------------------------------------------:|
 | Description | The APMPlus MCP Server helps you comprehensively ensure the entire lifecycle of your applications |
-| Category | Observability |
-| Tags | Observability, Traces, Metrics, Logs, Performance Monitoring |
+| Category |                                           Observability                                           |
+| Tags |                   Observability, Traces, Metrics, Logs, Performance Monitoring                    |
 
 ## Tools
 This MCP Server product provides the following Tools (capabilities):
 ### 1. apmplus_server_list_alert_rule
-Query the alert rules for APMPlus - Server Monitoring in a specified region.
+Query the alert rules from APMPlus - Server Monitoring in a specified region.
 - Parameters:
-  - `region_id`: [str] Region ID
-  - `keyword`: [str] Search keyword
-  - `page_number`: [int] Page number for pagination
-  - `page_size`: [int] Page size for pagination
+  - `region`: [str, optional] Region ID. Defaults to cn-beijing.
+  - `keyword`: [str, optional] Search keyword. Defaults to "".
+  - `page_number`: [int, optional] Page number for pagination. Defaults to 1.
+  - `page_size`: [int, optional] Page size for pagination. Defaults to 10.
 
 ### 2. apmplus_server_list_notify_group
-Query the notification group information for APMPlus - Server Monitoring in a specified region.
+Query the notification group information from APMPlus - Server Monitoring in a specified region.
 - Parameters:
-  - `region_id`: [str] Region ID
-  - `keyword`: [str] Search keyword
-  - `page_number`: [int] Page number for pagination
-  - `page_size`: [int] Page size for pagination
+  - `region`: [str, optional] Region ID. Defaults to cn-beijing.
+  - `keyword`: [str, optional] Search keyword. Defaults to "".
+  - `page_number`: [int, optional] Page number for pagination. Defaults to 1.
+  - `page_size`: [int, optional] Page size for pagination. Defaults to 10.
 
 ### 3. apmplus_server_query_metrics
-Query the metrics for APMPlus - Server Monitoring in a specified region.
+Query the metrics from APMPlus - Server Monitoring in a specified region.
 - Parameters:
-  - `region_id`: [str] Region ID
+  - `region`: [str, optional] Region ID. Defaults to cn-beijing.
   - `query`: [str] Metric expression, in PromQL format
   - `start_time`: [int] Start time, in seconds
   - `end_time`: [int] End time, in seconds
 
+### 4. apmplus_server_get_trace_detail
+Get trace detail information from APMPlus - Server Monitoring in a specified region.
+- Parameters:
+  - `trace_id`: [str, optional] Trace ID.
+  - `suggest_time`: [int, optional] Suggest time in seconds.
+  - `region`: [str, optional] Region ID. Defaults to cn-beijing.
+
+### 5. apmplus_server_list_span
+Get a list of trace span from APMPlus - Server Monitoring in a specified region.
+- Parameters:
+  - `start_time`: [int] Start time in seconds, example: 1693536000
+  - `end_time`: [int] End time in seconds, example: 1693546000
+  - `filters`: [list[dict], optional] Filter expression.
+                                    Each dict contains:
+                                  - 'Op' (str): in, not_in
+                                  - 'Key' (str): Filter key
+                                  - 'Values' (list[str]): Filter values
+  - `order`: [str, optional] Order direction. Defaults to DESC.
+  - `order_by`: [str, optional] Order by field. Defaults to "".
+  - `offset`: [int, optional] Offset for pagination. Defaults to 0.
+  - `limit`: [int, optional] Limit for pagination. Defaults to 10.
+  - `min_call_cost_millisecond`: [int, optional] Minimum call cost in milliseconds. Defaults to 0.
+  - `max_call_cost_millisecond`: [int, optional] Maximum call cost in milliseconds. Defaults to 0.
+  - `project_name`: [str, optional] The project name.
+  - `tag_filters`: [list[dict], optional] List of tag filters. Each dict contains:
+                                             - 'Key' (str): Tag key
+                                             - 'Value' (list[str]): Tag value
+                                             Max 10 tag pairs.
+                                             Empty value means no restriction on tag value.
+  - `region`: [str, optional] Region ID. Defaults to cn-beijing.
+
 ## Compatible Platforms
 You can use cline, cursor, claude desktop, or other terminals that support MCP server calls.
 

server/mcp_server_apmplus/README_zh.md

@@ -2,37 +2,67 @@
 
 应用性能监控服务官方推出的 MCP Server，可以将自然语言精准转化为可观测分析语句，高效分析包含指标、链路和日志在内的可观测数据，助您全面保障应用的全生命周期，提升异常问题排查与解决的效率。
 
-| 版本 | v0.1.0 |
-| :-: |:----------------:|
+| 版本 |              v0.2.0               |
+| :-: |:---------------------------------:|
 | 描述 | APMPlus MCP Server 助您全面保障应用的全生命周期 |
-| 分类 | 可观测 |
-| 标签 | 可观测，链路，指标，日志，性能监控 |
+| 分类 |                可观测                |
+| 标签 |         可观测，链路，指标，日志，性能监控         |
 
 ## Tools
 本 MCP Server 产品提供以下 Tools (工具/能力):
 ### 1. apmplus_server_list_alert_rule
 查询应用性能监控-服务端监控在指定区域下的告警规则
 - 参数:
-  - `region_id`: [str] 地域 id
-  - `keyword`: [str] 搜索关键词
-  - `page_number`: [int] 分页页码
-  - `page_size`: [int] 分页大小
+  - `region`: [str, optional] 地域 ID。默认为 cn-beijing。
+  - `keyword`: [str, optional] 搜索关键词。默认为空。
+  - `page_number`: [int, optional] 分页页码。默认为1。
+  - `page_size`: [int, optional] 分页大小。默认为10。
 
 ### 2. apmplus_server_list_notify_group
 查询应用性能监控-服务端监控在指定区域下的通知组信息
 - 参数:
-  - `region_id`: [str] 地域 id
-  - `keyword`: [str] 搜索关键词
-  - `page_number`: [int] 分页页码
-  - `page_size`: [int] 分页大小
+  - `region`: [str, optional] 地域 ID。默认为 cn-beijing。
+  - `keyword`: [str, optional] 搜索关键词。默认为空。
+  - `page_number`: [int, optional] 分页页码。默认为1。
+  - `page_size`: [int, optional] 分页大小。默认为10。
 
 ### 3. apmplus_server_query_metrics
 查询应用性能监控-服务端监控在指定区域下的指标
 - 参数:
-  - `region_id`: [str] 地域 id
-  - `query`: [str] 指标表达式，PromQL格式
-  - `start_time`: [int] 开始时间，单位为秒
-  - `end_time`: [int] 结束时间，单位为秒
+  - `region`: [str, optional] 地域 ID。默认为 cn-beijing。
+  - `query`: [str] 指标表达式，PromQL格式。
+  - `start_time`: [int] 开始时间，单位为秒。
+  - `end_time`: [int] 结束时间，单位为秒。
+
+### 4. apmplus_server_get_trace_detail
+查询应用性能监控-服务端监控在指定区域下的链路详情信息
+- 参数:
+  - `trace_id`: [str, optional] 链路 ID。
+  - `suggest_time`: [int, optional] 链路发生的大致时间（秒）。
+  - `region`: [str, optional] 地域 ID。默认为 cn-beijing。
+
+### 5. apmplus_server_list_span
+查询应用性能监控-服务端监控在指定区域下的链路Span列表
+- 参数:
+  - `start_time`: [int] 开始时间（秒），例如：1693536000。
+  - `end_time`: [int] 结束时间（秒），例如：1693546000。
+  - `filters`: [list[dict], optional] 过滤表达式。每个字典包含：
+                                  - 'Op' (str): in, not_in
+                                  - 'Key' (str): 过滤键
+                                  - 'Values' (list[str]): 过滤值
+  - `order`: [str, optional] 排序方向。默认为 DESC。
+  - `order_by`: [str, optional] 排序字段。默认为空字符串。
+  - `offset`: [int, optional] 分页偏移量。默认为 0。
+  - `limit`: [int, optional] 分页限制。默认为 10。
+  - `min_call_cost_millisecond`: [int, optional] 最小调用耗时（毫秒）。默认为 0。
+  - `max_call_cost_millisecond`: [int, optional] 最大调用耗时（毫秒）。默认为 0。
+  - `project_name`: [str, optional] 项目名称。
+  - `tag_filters`: [list[dict], optional] 标签过滤列表。每个字典包含：
+                                             - 'Key' (str): 标签键
+                                             - 'Value' (list[str]): 标签值
+                                             Max 10 tag pairs.
+                                             最多 10 个标签对。空值表示对标签值无限制。
+  - `region`: [str, optional] 地域 ID。默认为 cn-beijing。
 
 ## 可适配平台  
 可以使用cline、cursor、claude desktop或支持MCP server调用的其它终端

server/mcp_server_apmplus/pyproject.toml

@@ -1,17 +1,19 @@
 [project]
 name = "mcp-server-apmplus"
-version = "0.1.0"
+version = "0.2.0"
 description = "Add your description here"
 readme = "README.md"
 requires-python = ">=3.10"
 dependencies = [
-    "mcp==1.10.0",
+    "black>=26.1.0",
+    "click==8.2.0",
+    "mcp==1.12.4",
     "requests>=2.32.3",
-    "volcengine-python-sdk>=3.0.1",
+    "volcengine-python-sdk==5.0.14",
 ]
 
 [project.scripts]
-mcp-server-apmplus = "mcp_server_apmplus.main:main"
+mcp-server-apmplus = "mcp_server_apmplus.server:main"
 
 [build-system]
 requires = ["hatchling"]

server/mcp_server_apmplus/requirements.txt

@@ -77,5 +77,5 @@ urllib3==2.4.0
     #   volcengine-python-sdk
 uvicorn==0.34.2
     # via mcp
-volcengine-python-sdk==3.0.1
+volcengine-python-sdk==5.0.14
     # via mcp-server-apmplus (pyproject.toml)

server/mcp_server_apmplus/run.sh

@@ -3,4 +3,4 @@ set -ex
 cd `dirname $0`
 
 cd src
-exec python3 -m mcp_server_apmplus.main -t streamable-http
+exec python3 -m mcp_server_apmplus.server -t streamable-http