yams (Juniper)

YAMS（又一个MCP服务器）

山药 是一个功能强大的模型上下文协议（MCP）服务器，专为分析Kubernetes集群上运行的服务而设计。YAMS支持两者 超文本传输协议 和 标准 传输模式，提供与VS Code Copilot Chat和其他MCP兼容工具的无缝集成。

什么是YAMS？

YAMS是一个 通用Kubernetes管理工具 它可以使用标准的kubeconfig文件或安全的SSH隧道连接到任何Kubernetes环境。虽然YAMS在设计时考虑了Juniper Cloud Native Router（JCNR）部署，但它适用于任何Kubernetes集群。

关键能力

• 双重运输支持：web客户端的HTTP传输（默认）和VS Code Copilot Chat和其他MCP兼容工具的stdio传输
• 多集群管理：同时连接到多个Kubernetes集群
• 灵活的访问方法：远程集群的直接kubeconfig访问或SSH隧道连接
• 通用Kubernetes操作：列出集群、命名空间、pod，并在任何pod中执行命令
• JCNR具体分析：具有CLI命令和HTTP API集成的深度可见性。关联命令中的数据，以提供JCNR状态的可用摘要。
• VS代码集成：原生支持VS Code Copilot Chat和其他MCP客户端

用例

• 基础设施分析：查询和分析跨多个集群的Kubernetes部署
• JCNR运营：监控Juniper云原生路由器部署并排除故障
• 远程群集访问：通过SSH隧道安全访问私有或本地集群

特性

• 双重运输支持：HTTP传输（默认）和stdio传输，以满足不同的集成需求
• MCP服务器采用FastAPI构建，支持HTTP模式和原生stdio
• Kubernetes与kubeconfig支持的集成
• SSH隧道支持远程集群访问
• 通用工具: list_clusters, list_namespaces, list_pods, execute_command, pod_command_and_summary
• JCNR专用工具:

- execute_dpdk_command -DPDK数据路径命令（vrdpdk pod） - execute_agent_command -Contrail Agent命令（vrouter节点Pod） - execute_junos_cli_commands -cRPD和cSRX路由命令（jcnr命名空间） - jcnr_summary - 具有CLI+HTTP API关联的全面JCNR数据路径分析

• 操作工具: check_core_files, analyze_logs
• 高级功能:

- 通过JSON文件配置命令列表 - Sandesh HTTP API响应的XML到表格式 - 多集群数据路径相关性分析 - 自动JCNR组件发现

• CORS支持和健康检查端点

配置

配置群集

创建一个 clusters.json 包含集群配置的文件。每个集群都由一个唯一的名称（键）和配置对象（值）定义。

群集配置字段：

每个集群的必填字段：

• kubeconfig_path：kubeconfig文件的绝对或相对路径

- *示例*: "/home/user/.kube/config", "~/.kube/prod-config" - *目的*：包含集群连接详细信息的kubeconfig文件的路径 - *备注*：对于SSH隧道集群，这应该是远程主机上的路径

每个集群的可选字段：

• description：集群的人类可读描述

- *示例*: "Production JCNR cluster", "Development environment" - *目的*：日志和UI中的文档和标识

• pod_command_list：包含pod诊断命令的JSON文件的路径

- *示例*: "pod-command-list.json" - *目的*：由以下人员使用 pod_command_and_summary 运行诊断命令的工具

• jcnr_command_list：包含JCNR数据路径命令的JSON文件的路径

- *示例*: "jcnr-command-list.json" - *目的*：由以下人员使用 jcnr_summary 全面数据路径分析工具

• ssh：SSH隧道配置对象（请参阅下面的SSH配置选项）

- *目的*：当集群不能直接访问并且需要SSH隧道时，需要此项

配置结构：

{
  "cluster-name": {
    "kubeconfig_path": "path/to/kubeconfig",
    "description": "Optional description",
    "pod_command_list": "path/to/pod-command-list.json",
    "jcnr_command_list": "path/to/jcnr-command-list.json",
    "ssh": {
      // SSH configuration (optional, see SSH section below)
    }
  }
}

直接Kubeconfig访问

{
  "production": {
    "kubeconfig_path": "/home/user/.kube/prod-cluster-config",
    "description": "Production Kubernetes cluster",
    "pod_command_list": "pod-command-list.json",
    "jcnr_command_list": "jcnr-command-list.json"
  },
  "staging": {
    "kubeconfig_path": "/home/user/.kube/staging-cluster-config", 
    "description": "Staging environment for testing",
    "pod_command_list": "pod-command-list.json"
  },
  "local": {
    "kubeconfig_path": "~/.kube/config",
    "description": "Local Kubernetes cluster"
  }
}

最小配置示例

{
  "my-cluster": {
    "kubeconfig_path": "~/.kube/config"
  }
}

SSH隧道访问

{
  "remote-cluster": {
    "kubeconfig_path": "/home/user/.kube/remote-cluster-config",
    "description": "Remote cluster accessed via SSH tunnel",
    "ssh": {
      "host": "jump-host.example.com",
      "port": 22,
      "username": "ubuntu",
      "key_path": "/home/user/.ssh/id_rsa",
      "k8s_host": "10.0.1.100",
      "k8s_port": 6443,
      "local_port": 6443
    }
  },
  "password-auth-cluster": {
    "kubeconfig_path": "/home/user/.kube/password-cluster-config",
    "description": "Cluster with SSH password authentication",
    "ssh": {
      "host": "bastion.company.com",
      "username": "operator",
      "password": "secure-password",
      "k8s_host": "kubernetes.internal",
      "k8s_port": 6443,
      "local_port": 6444
    }
  }
}

最小SSH配置示例

{
  "ssh-key-cluster": {
    "kubeconfig_path": "/home/user/.kube/ssh-cluster-config",
    "ssh": {
      "host": "jump-server.com",
      "username": "user",
      "key_path": "/home/user/.ssh/id_rsa",
      "k8s_host": "kubernetes.internal"
    }
  },
  "ssh-password-cluster": {
    "kubeconfig_path": "/home/user/.kube/ssh-cluster-config",
    "ssh": {
      "host": "bastion.company.com",
      "username": "operator",
      "password": "my-password",
      "k8s_host": "localhost"
    }
  }
}

快速设置

选择您喜欢的安装方法：

选项A:Docker（推荐）

Docker提供了一个隔离的、可复制的环境，其中包含所有依赖项。

# Quick start - automated setup
./docker-run.sh

# Check health
curl http://localhost:40041/health

Docker会自动处理：

• 默认配置（如果没有提供示例配置，则使用示例配置）
• SSH密钥权限
• 目录创建
• 服务启动

选项B：本地Python安装

# Lets go to YAMS directory
cd /path/to/yams

# Create virtual environment (recommended)
python -m venv venv
source venv/bin/activate  # On macOS/Linux
# or venv\Scripts\activate  # On Windows

# Install dependencies
pip install -r requirements.txt

使用本地Python：

# Start server with Kubernetes sources using HTTP transport (default)
python enhanced_mcp_server.py --port 40041 --clusters-config clusters/clusters.json

配置VS代码

对于HTTP传输（默认）：

{
  "mcp": {
    "servers": {
      "yams-mcp-server": {
        "url": "http://127.0.0.1:40041/mcp/"
      }
    }
  }
}

对于stdio传输（建议用于VS Code）：

{
  "yams-mcp-stdio-server": {
      "type": "stdio",
      "command": "/path/to/yams/run_mcp_stdio.sh",
      "args": [
          "/path/to/yams",
          "/path/to/yams/clusters/clusters-stdio.json",
          "/path/to/yams/venv"
      ]
  }
}

命令行选项

• --transport：运输方式- http （默认）或 stdio
• --port：运行HTTP服务器的端口（默认值：40041，stdio忽略）
• --clusters-config：包含集群配置的JSON文件的路径

API端点（仅限HTTP传输）

• GET /：服务器信息和可用端点
• GET /health：健康检查端点
• POST /mcp：主MCP协议端点

MCP协议支持

此服务器实现了支持两种传输的模型上下文协议：

• HTTP传输：用于web客户端和测试的RESTful API端点
• stdio运输：直接stdin/stdout通信
• 工具：可由客户端调用的可调用函数
• 资源：可通过URI访问的可读内容
• 初始化：正确的MCP握手和能力协商

可用工具

1. list_cluster

• 说明：列出所有已配置的Kubernetes集群

2. list_namespaces

• 描述：列出Kubernetes集群中的命名空间
• 参数： cluster_name （可选字符串）-群集的名称

3. list_pods

• 描述：列出特定命名空间和集群中的Pod
• 参数： namespace （字符串）， cluster_name （可选字符串）

4. execute_命令

• 描述：在特定pod中执行命令
• 参数： pod_name （字符串）， namespace （字符串）， command （字符串）， container （可选字符串）， cluster_name （可选字符串）

5. execute_dpdk命令

• 描述：在所有集群的轨迹命名空间中的所有DPDK Pod（vrdpdk）中执行命令
• 参数： command （字符串）， cluster_name （可选字符串）-如果未指定，则在所有集群上执行
• 命令示例： vif --list, dropstats, vif --get 0

6. 执行_代理_命令

• 描述：在所有集群的轨迹命名空间中的所有Contrail Agent Pod（vrouter节点）中执行命令
• 参数： command （字符串）， cluster_name （可选字符串）-如果未指定，则在所有集群上执行
• 命令示例： contrail-status, vif --list, nh --list

7. execute_junos_cli_命令

• 描述：在所有集群的jcnr命名空间中的所有cRPD（Contrail Routing Protocol Daemon）和cSRX Pod中执行命令
• 参数： command （字符串）， cluster_name （可选字符串）-如果未指定，则在所有集群上执行
• 命令示例： show route, show bgp summary, show interfaces terse, show security policies

8. check_core_files

• 描述：检查Kubernetes集群中节点上的核心文件。在常见位置搜索岩芯堆
• 参数：

- cluster_name （可选字符串）-群集的名称（如果未指定，则检查所有群集） - search_paths （可选数组）-搜索核心文件的自定义路径（如果未指定，则使用默认路径） - max_age_days （可选整数）-要报告的核心文件的最长期限（默认值：7天）

• 默认搜索路径： /cores, /var/cores, /var/crash, /var/log/crash, /var/log/cores
• 用例：调试崩溃、系统监控、排除应用程序故障

9. 分析日志

• 说明：分析中的日志文件 /var/log/ 和 /log/ 集群节点上的目录。搜索错误、大文件和最近的活动
• 参数：

- cluster_name （可选字符串）-集群的名称（如果未指定，则分析所有集群） - pod_name （可选字符串）-用于分析日志的特定pod的名称 - namespace （可选字符串）-pod的Kubernetes命名空间（如果指定了pod_name，则需要） - log_paths （可选数组）-搜索日志文件的自定义路径 - max_age_days （可选整数）-要分析的日志文件的最大年龄（以天为单位）（默认值：7） - max_lines （可选整数）-日志分析返回的最大行数（默认值：100） - pattern （可选字符串）-在日志中搜索自定义正则表达式模式

10. pod_命令_和_摘要

• 描述：在给定的pod上运行一组命令，并用执行统计数据总结输出。命令仅从集群配置的“pod_command_list”字段中引用的文件加载。
• 参数：

- pod_name （string）-要在其上执行命令的pod的名称 - namespace （string）-pod的Kubernetes命名空间 - container （可选字符串）-容器名称（默认为第一个容器） - cluster_name （可选字符串）-群集的名称

11. jcnr_摘要 ⭐ （新的JCNR数据路径分析工具）

• 说明： 全面的JCNR数据路径分析 将CLI命令和HTTP API数据与相关性分析相结合
• 参数： cluster_name （可选字符串）-集群的名称（如果未指定，则分析所有集群）
• 主要特点:

- 自动发现：在轨迹命名空间中查找并连接到DPDK Pod（vrdpdk） - CLI命令：执行全面的数据路径命令（nh、vif、rt、frr、mpls、flow） - HTTP API集成：使用XML到表格式从Sandesh HTTP API（端口8085）获取数据 - 相关性分析：分析下一跳、路由、MPLS标签和流之间的关系 - 可配置命令：使用JSON配置文件创建可自定义的命令/端点列表 - 增强输出：结构化表格、汇总统计和详细分析

上下文管理工具

• start_context_gathering：开始收集LLM分析的命令输出
• stop_context_gathering：停止收集并返回累积的上下文以进行LLM分析
• resume_context_gathering：恢复已停止的上下文会话以继续收集命令
• get_text_sessions：获取有关活动和已完成上下文会话的信息
• analyze_context_with_llm：使用自定义提示格式化LLM分析的存储上下文会话
• append_last_common_to_context：将上次执行的命令附加到特定的上下文会话
• get_last_command_info：获取有关上次执行的命令的信息

JCNR特定功能

YAMS为 Juniper云原生路由器（JCNR） 部署，提供对数据路径操作和网络状态的深入可见性。

JCNR分析

这 jcnr_summary 该工具提供了对数据路径中JCNR组件的全面分析 vRouter Agent洞察的实用程序。

配置管理：

JCNR命令和端点可以通过JSON文件进行配置：

{
  "datapath_commands": [
    "nh --list",
    "vif --list", 
    "rt --dump 0",
    "frr --dump",
    "mpls --dump",
    "flow -l"
  ],
  "http_endpoints": {
    "nh_list": "Snh_NhListReq?type=&nh_index=&policy_enabled=",
    "vrf_list": "Snh_VrfListReq?name=",
    "inet4_routes": "Snh_Inet4UcRouteReq?x=0",
    "interface_list": "Snh_ItfReq?name=",
    "flow_list": "Snh_FetchFlowRecord?x=0"
  },
  "http_port": 8085,
  "analysis_config": {
    "max_display_lines": 50,
    "max_table_rows": 20,
    "max_http_display_chars": 5000,
    "enable_detailed_analysis": true,
    "truncate_large_outputs": true
  }
}

JCNR组件访问

DPDK吊舱（vrdpdk）

• 目的：用户空间数据路径处理
• 命令: vif --list, nh --list, rt --dump, dropstats
• 位置: contrail 命名空间
• 工具: execute_dpdk_command

Contrail Agent Pod（vrouter节点）

• 目的：用于数据路径编程的控制平面代理
• 命令: contrail-status, vif --list, nh --list
• 位置: contrail 命名空间
• 工具: execute_agent_command

cRPD Pod（控制路由协议守护进程）

• 目的：BGP/MPLS控制平面路由
• 命令: show route, show bgp summary, show interfaces
• 位置: jcnr 命名空间
• 工具: execute_junos_cli_commands
• 备注：Junos CLI的命令会自动格式化(cli -c 'command')

JCNR用例

• 性能分析：监控接口统计、流处理、丢包
• 路由验证：验证跨IPv4/IPv6表的路由安装
• 数据路径调试：关联下一跳、路由和流以进行故障排除
• 多集群监控：比较跨JCNR部署的配置
• 运营健康：检查核心文件、分析日志、验证组件状态

Kubernetes集成

服务器支持通过JSON文件配置的多个Kubernetes集群。集群可以通过kubeconfig文件直接访问，也可以通过SSH隧道进行远程访问。

SSH隧道支持

对于不能直接访问的集群，YAMS支持通过堡垒主机或跳转服务器进行SSH隧道。这对于以下情况特别有用：

• 通过堡垒主机访问私有集群
• 从云环境连接到本地集群
• 通过公司网络中的跳转服务器进行安全访问

SSH配置选项

配置SSH隧道访问时，包括 ssh 集群配置中的对象。以下是所有可用字段的详细分类：

必填字段：

• host：SSH服务器主机名或IP地址

- *示例*: "jump-host.example.com" 或 "10.87.3.248" - *目的*：您将连接到的SSH服务器（堡垒主机、跳转服务器或直接主机）

• username：用于身份验证的SSH用户名

- *示例*: "ubuntu", "admin", "your-username" - *目的*：SSH服务器上的用户帐户

• k8s_host：从SSH服务器看到的Kubernetes API服务器主机名

- *示例*: "localhost", "10.0.1.100", "k8s-master.internal" - *目的*：可从SSH服务器访问Kubernetes API服务器的位置 - *共同价值观*: - "localhost" -K8s API运行在与SSH服务器相同的主机上 - "10.x.x.x" -K8s主节点内部IP地址 - "kubernetes.internal" -K8s API的内部DNS名称

身份验证（选择一个）：

• key_path：SSH私钥文件的路径（用于公钥身份验证）

- *示例*: "/home/user/.ssh/id_rsa", "/Users/user/.ssh/company_key" - *目的*：用于无密码SSH身份验证的私钥文件 - *备注*：必须是私钥，而不是 .pub 文件

• password：SSH密码（用于密码验证）

- *示例*: "my-secure-password" - *目的*：SSH登录密码 - *安全*：考虑使用基于密钥的身份验证以提高安全性

可选字段：

• port：SSH服务器端口号

- *默认*: 22 - *示例*: 2222, 22 - *目的*：非标准SSH端口（如果与22不同）

• k8s_port：Kubernetes API服务器端口

- *默认*: 6443 - *示例*: 6443, 8443, 443 - *目的*：Kubernetes API服务器监听的端口

• local_port：SSH隧道的本地端口

- *默认*: 6443 - *示例*: 6443, 16443, 8443 - *目的*：绑定隧道的本地端口（避免与其他隧道冲突）

场关系和常见模式：

模式1:SSH主机上的K8s API

"ssh": {
  "host": "k8s-master.company.com",
  "username": "admin",
  "key_path": "/home/user/.ssh/id_rsa",
  "k8s_host": "localhost",
  "k8s_port": 6443,
  "local_port": 6443
}

模式2:K8s API在不同的内部主机上

"ssh": {
  "host": "bastion.company.com",
  "username": "jump-user",
  "password": "secure-password",
  "k8s_host": "k8s-internal.company.com",
  "k8s_port": 6443,
  "local_port": 16443
}

模式3：多个集群（不同的本地端口）

{
  "cluster-1": {
    "ssh": {
      "host": "bastion1.com",
      "local_port": 16443
    }
  },
  "cluster-2": {
    "ssh": {
      "host": "bastion2.com", 
      "local_port": 16444
    }
  }
}

备注：SSH主机密钥验证会自动禁用，以防止交互式提示。这相当于使用 ssh -o StrictHostKeyChecking=no。虽然这提高了自动化程度，但请确保您信任SSH主机的网络路径。

集群配置示例(clusters.json)

具有直接和SSH访问的混合配置

{
  "production": {
    "kubeconfig_path": "/home/user/.kube/prod-cluster-config",
    "description": "Production Kubernetes cluster (direct access)",
    "pod_command_list": "pod-command-list.json",
    "jcnr_command_list": "jcnr-command-list.json"
  },
  "staging": {
    "kubeconfig_path": "/home/user/.kube/staging-cluster-config", 
    "description": "Staging environment (direct access)",
    "pod_command_list": "pod-command-list.json"
  },
  "remote-prod": {
    "kubeconfig_path": "/home/user/.kube/remote-prod-config",
    "description": "Remote production cluster via SSH tunnel",
    "pod_command_list": "pod-command-list.json",
    "jcnr_command_list": "jcnr-command-list.json",
    "ssh": {
      "host": "bastion.company.com",
      "username": "kubectl-user",
      "key_path": "/home/user/.ssh/company_rsa",
      "k8s_host": "k8s-master.internal",
      "k8s_port": 6443,
      "local_port": 6443
    }
  },
  "dev-cluster": {
    "kubeconfig_path": "/home/user/.kube/dev-config",
    "description": "Development cluster via SSH (password auth)",
    "pod_command_list": "pod-command-list.json",
    "ssh": {
      "host": "dev-jump.lab.local",
      "username": "developer",
      "password": "dev-password",
      "k8s_host": "localhost",
      "k8s_port": 6443,
      "local_port": 6444
    }
  }
}

Pod命令配置

这 pod_command_list 配置允许通过以下方式执行智能的、特定于吊舱的诊断命令 pod_command_and_summary 工具。

配置文件结构

使用pod特定的命令配置创建JSON文件：

{
  "description": "Enhanced pod-specific diagnostic commands with pattern matching support",
  "pod_configurations": [
    {
      "pod_name": "nginx-*",
      "namespace": "default",
      "description": "Nginx web server diagnostic commands (pattern match)",
      "commands": [
        "hostname",
        "uptime",
        "ps aux | grep nginx",
        "nginx -t",
        "nginx -V",
        "curl -I http://localhost",
        "df -h",
        "free -m",
        "netstat -tulpn | grep :80",
        "ls -la /var/log/nginx/",
        "tail -20 /var/log/nginx/access.log",
        "tail -20 /var/log/nginx/error.log"
      ]
    },
    {
      "pod_name": "redis-*",
      "namespace": "default",
      "description": "Redis cache server diagnostic commands",
      "commands": [
        "hostname",
        "uptime",
        "ps aux | grep redis",
        "redis-cli ping",
        "redis-cli info memory",
        "redis-cli info stats",
        "redis-cli config get '*'",
        "df -h",
        "free -m",
        "netstat -tulpn | grep :6379"
      ]
    },
    {
      "pod_name": "*",
      "namespace": "*",
      "description": "Generic pod diagnostic commands (fallback)",
      "commands": [
        "hostname",
        "uptime",
        "ps aux | head -20",
        "df -h",
        "free -m",
        "env | grep -E 'PATH|HOME|USER|KUBERNETES'",
        "ip addr show",
        "netstat -tulpn | head -10"
      ]
    }
  ],
  "execution_options": {
    "timeout_seconds": 30,
    "max_output_size": 1048576,
    "retry_count": 1,
    "parallel_execution": false,
    "continue_on_error": true
  }
}

Pod名称匹配系统

系统使用智能模式匹配来选择合适的命令集：

1. 精确匹配

{
  "pod_name": "nginx-deployment-abc123",
  "namespace": "default",
  "commands": ["specific", "commands", "for", "this", "exact", "pod"]
}

2. 通配符模式匹配

{
  "pod_name": "nginx-*",
  "namespace": "default",
  "commands": ["commands", "for", "any", "nginx", "pod"]
}

3. 通用回退

{
  "pod_name": "*",
  "namespace": "*",
  "commands": ["generic", "commands", "for", "any", "pod"]
}

命令选择优先级

执行时 pod_command_and_summary，系统遵循此选择逻辑：

1. 精确匹配：查找精确的pod名称和命名空间匹配
2. 模式匹配：查找与pod名称匹配的通配符模式
3. 后备方案：如果找不到匹配项，则使用第一个配置
4. 通用：使用 * 模式作为最终的退路

示例：用于吊舱 nginx-deployment-abc123 在命名空间中 default:

1. 尝试精确匹配： nginx-deployment-abc123
2. 尝试模式匹配： nginx-*
3. 回退到第一个配置或 * 模式

执行选项

全局配置命令执行行为：

"execution_options": {
  "timeout_seconds": 30,           // Command execution timeout
  "max_output_size": 1048576,      // Max output size in bytes (1MB)
  "retry_count": 1,                // Number of retry attempts on failure
  "parallel_execution": false,     // Execute commands in parallel (not implemented)
  "continue_on_error": true        // Continue if one command fails
}

使用示例

执行pod特定的命令

# The system automatically selects appropriate commands based on pod name
curl -X POST http://127.0.0.1:40041/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "pod_command_and_summary",
      "arguments": {
        "pod_name": "nginx-deployment-abc123",
        "namespace": "default",
        "cluster_name": "production"
      }
    }
  }'

命令输出摘要

该工具提供详细的执行统计数据：

Command Execution Summary
=========================
Pod: nginx-deployment-abc123
Namespace: default
Container: nginx
Cluster: production
Command Source: cluster_config: /path/to/pod-command-list.json

Execution Options:
  Timeout: 30s
  Max Output Size: 1048576 bytes
  Retry Count: 1
  Continue on Error: true

✓ Command 1: nginx -t (success, 5 lines, 245 bytes)
   Execution Time: 0.12s
   First line: nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
   Last line: nginx: configuration file /etc/nginx/nginx.conf test is successful

✓ Command 2: ps aux | grep nginx (success, 8 lines, 456 bytes)
   Execution Time: 0.08s
   First line: root      1234  0.0  0.1 123456  7890 ?        Ss   10:30   0:00 nginx: master
   Last line: www-data   1251  0.0  0.0  12345   890 pts/0    S+   10:31   0:00 grep nginx

Commands executed: 12
Successful: 11
Failed: 1
Success rate: 91.7%

与集群集成

请参考集群配置中的pod命令列表：

{
  "production": {
    "kubeconfig_path": "/path/to/kubeconfig",
    "pod_command_list": "clusters/pod-command-list.json",
    "description": "Production cluster with enhanced pod diagnostics"
  }
}

这种智能命令选择系统可确保每种吊舱类型都能收到适当的诊断命令，使故障排除更加高效和有针对性。

上下文管理器和LLM分析工作流

增强型MCP服务器包括一个强大的上下文管理系统，允许您从多个诊断工具收集命令输出，并为LLM分析做好准备。这使得在人工智能的帮助下进行全面的网络故障排除成为可能。

上下文管理器功能

• 基于会话的上下文收集：使用有意义的标识符启动和停止上下文收集会话
• 自动命令跟踪：当会话处于活动状态时，所有MCP工具执行都会自动捕获
• 多命令聚合：将不同工具（DPDK、Junos CLI、日志分析等）的输出收集到一个上下文中
• 手动命令添加：使用以下命令将特定命令输出附加到任何会话 append_last_command_to_context
• 会话状态控制：除非明确恢复，否则追加后会话仍将停止
• LLM就绪格式化：准备带有分析提示的上下文数据，以实现无缝的LLM集成
• 会话管理：查看活动和已完成的会话，获取会话统计信息

工作流示例

1.开始上下文收集

# Begin collecting diagnostic context
start_context_gathering session_id="bgp-outage-investigation" description="Production BGP neighbor down issue"

2.运行诊断命令

所有后续命令都将被自动捕获：

# Check BGP status across clusters
execute_junos_cli_commands command="show bgp summary" cluster_name="prod"
execute_junos_cli_commands command="show bgp neighbor 192.168.1.1" cluster_name="prod"

# Analyze DPDK datapath
execute_dpdk_command command="vif --list" cluster_name="prod"
execute_dpdk_command command="flow -l" cluster_name="prod"

# Get comprehensive JCNR summary
jcnr_summary cluster_name="prod"

# Check for core files and log errors
check_core_files cluster_name="prod"
analyze_logs cluster_name="prod" pattern="bgp|error"

3.停止上下文收集

# Complete the session and get accumulated context
stop_context_gathering session_id="bgp-outage-investigation"

4.准备LLM分析

# Format context for LLM analysis with different prompt types
analyze_context_with_llm session_id="bgp-outage-investigation" analysis_type="troubleshooting"

# Alternative analysis types:
# analysis_type="summary" - Get key findings summary
# analysis_type="recommendations" - Get actionable recommendations  
# analysis_type="root_cause" - Deep dive root cause analysis
# analysis_type="custom" custom_prompt="Focus on BGP timers and suggest optimizations"

手动命令添加工作流

有时，您需要在会话停止后向上下文会话添加命令，或者您希望选择性地添加特定命令而不自动收集。上下文管理器提供手动命令添加功能：

向已停止的会话添加命令

# Start investigation session
start_context_gathering session_id="interface-analysis" description="Investigating interface flapping"

# Run some commands (automatically collected)
execute_dpdk_command command="vif --list" cluster_name="prod"
list_pods namespace="contrail" cluster_name="prod"

# Stop the session
stop_context_gathering session_id="interface-analysis"

# Later, run additional command outside of the session
execute_junos_cli_commands command="show interfaces extensive" cluster_name="prod"

# Add the last command to the stopped session
append_last_command_to_context session_id="interface-analysis"

# Session remains STOPPED - use explicit resume if you want automatic collection again
resume_context_gathering session_id="interface-analysis"

# Continue investigation (now auto-collected again)
execute_dpdk_command command="dropstats" cluster_name="prod"

选择性命令添加

# Run commands without any active session
execute_dpdk_command command="vif --get 0" cluster_name="prod"
execute_dpdk_command command="vif --get 1" cluster_name="prod"  
execute_agent_command command="contrail-status" cluster_name="prod"

# Check what command is available to append
get_last_command_info

# Create session and add only the last (most relevant) command
start_context_gathering session_id="vif-analysis" description="Virtual interface analysis"
append_last_command_to_context session_id="vif-analysis"

# Session stays active for future commands
execute_junos_cli_commands command="show interfaces terse" cluster_name="prod"

会话状态管理

上下文管理器提供对会话状态的显式控制：

• 活跃会话：自动收集所有命令输出
• 已停止会话：没有自动收集，但可以手动附加命令
• 附加行为: append_last_command_to_context 保留会话状态
• 明确简历：使用 resume_context_gathering 重新激活自动收集

# Session state examples
get_context_sessions                                    # View active sessions only
get_context_sessions show_all=true                     # View all sessions (active + stopped)
get_context_sessions session_id="interface-analysis"   # View specific session details

# Session shows:
# - Status: "active" or "stopped"  
# - Commands executed count
# - Total output size
# - Duration

会话管理

# View all active sessions
get_context_sessions

# View specific session details
get_context_sessions session_id="bgp-outage-investigation"

# View all sessions (active and completed)
get_context_sessions show_all=true

分析类型

这 analyze_context_with_llm 该工具提供了几个内置的分析提示：

• troubleshooting （默认）：逐步排除故障建议，并确定根本原因
• summary：诊断会议的主要发现和模式
• recommendations：立即修复、改进和预防的可操作建议
• root_cause：深入分析，追踪事件的顺序，找出根本原因
• custom：使用您自己的分析提示进行具体调查

与MCP客户端集成

上下文管理器遵循MCP架构原则：

1. 服务器角色：收集和格式化诊断上下文数据
2. 客户端角色：将格式化的上下文发送到所选的LLM（OpenAI、Anthropic等）
3. 无LLM依赖关系：服务器不直接进行LLM API调用
4. 灵活的LLM选择：适用于您的MCP客户支持的任何LLM

最佳实践

1. 使用描述性会话ID：选择有意义的名称，如“bgp-outage-dec16”或“接口皮瓣调查”
2. 添加说明：提供你正在调查的内容的背景
3. 逻辑命令序列：按逻辑故障排除顺序运行命令
4. 选择适当的分析类型：选择与您的调查需求相匹配的分析类型
5. 查看会话数据：使用 get_context_sessions 在分析之前审查收集的数据

此工作流程使您能够系统地收集网络诊断数据，并利用LLM分析进行更快、更全面的故障排除。

安全考虑

一般安全

• 如果公开部署，请添加身份验证
• 在生产环境中使用HTTPS
• 彻底验证所有输入参数
• 对公共端点实施速率限制
• 保护kubeconfig文件和SSH凭据

SSH隧道安全

• SSL验证：对于SSH隧道群集，SSL证书验证会自动禁用(insecure-skip-tls-verify: true)因为Kubernetes API服务器证书对于 127.0.0.1 隧道端点
• SSH主机密钥验证：SSH主机密钥检查已禁用以实现自动化，但这会降低安全性。考虑添加主机密钥验证以供生产使用
• 密钥管理：使用适当的权限安全地存储SSH私钥（600）。永远不要将私钥提交给版本控制
• 网络安全：SSH隧道只能在受信任的网络环境中使用。考虑VPN替代方案以增强安全性

Kubeconfig安全

• 文件权限：确保kubeconfig文件具有受限权限（600或640）
• 临时文件：服务器为SSH隧道集群创建临时kubeconfig文件。这些在关机时会自动清理
• 凭据存储：避免将敏感凭据存储在群集配置文件中。尽可能使用环境变量或安全凭据存储

需求

看 requirements.txt 查看完整的依赖关系列表。关键要求包括：

• FastAPI
• 优维康
• 主控程序
• kubernetes（可选，用于kubernetes支持）
• paramiko和sshtunnel（可选，用于SSH隧道支持）
• 皮丹提克

SSH隧道的安全注意事项

• SSL证书绕过：使用SSH隧道时，MCP服务器会自动禁用Kubernetes API服务器的SSL证书验证，因为证书对 127.0.0.1 隧道端点
• 生产注意事项：对于生产环境，考虑使用VPN连接或正确配置的SSL证书，而不是SSH隧道
• 凭证保护：如果SSH私钥或密码可能被共享或提交给版本控制，则永远不要将其存储在clusters.json文件中

Docker部署

YAMS包括Docker支持，便于部署和一致的环境。

Docker快速入门

# Automated setup
./docker-run.sh

目录设置

Docker脚本会自动为卷装载创建以下目录：

./clusters/      # Runtime cluster configurations (contains clusters.json)
./sshkeys/       # SSH private keys for tunnel access  
./kubeconfigs/   # Kubernetes config files

文件放置指南

1. 群集配置 (./clusters/)

# clusters.json should already be in the clusters/ directory
# Edit ./clusters/clusters.json with your actual cluster settings

2. SSH密钥 (./sshkeys/)

# Copy SSH private keys (for clusters using SSH tunnels)
cp ~/.ssh/id_rsa ./sshkeys/
cp ~/.ssh/company_key ./sshkeys/

# IMPORTANT: Set proper permissions BEFORE running Docker
# SSH keys must have 600 permissions for security
chmod 600 ./sshkeys/*

备注：为了安全起见，SSH密钥在容器中以只读方式装载。在装载之前，请确保在主机系统上正确设置了权限。

3. Kubeconfig文件 (./kubeconfigs/)

# Copy kubeconfig files referenced in clusters.json
cp ~/.kube/config ./kubeconfigs/
cp ~/.kube/prod-cluster ./kubeconfigs/
cp ~/.kube/staging-cluster ./kubeconfigs/

# Set proper permissions  
chmod 600 ./kubeconfigs/*