Must Gather Code Execution MCP

必须收集渐进式披露MCP服务器

高效的OpenShift必须使用 Anthropic的渐进式披露模式 用于模型上下文协议（MCP）。

概述

该项目实施 渐进式披露 -该模式将AI上下文开销降低了92%，同时实现了无限的可扩展性。代理通过智能搜索按需发现功能，而不是预先加载所有分析工具。

进化

传统MCP （v1.0）：

• ❌ 直接暴露的11个工具
• ❌ ~6000个令牌仅用于工具定义
• ❌ 难以扩展到20-30个工具之外
• ✅ 代码执行模式（本地数据处理）

渐进呈现 （v2.0-此版本）：

• ✅ 2元工具 为了发现
• ✅ 约500个代币 用于工具定义（减少92%！）
• ✅ 扩展到100多种方法 没有上下文惩罚
• ✅ 智能搜索 按组件、严重性、关键字
• ✅ 按需型探索
• ✅ 代码执行模式（本地数据处理）

问题

传统的人工智能代理在必须收集的分析中挣扎：

• 539MB 数据跨越 5245张图片
• 加载所有工具会消耗宝贵的上下文
• 代理商必须提前知道确切的工具名称
• 无法扩展到全面的分析能力

解决方案

渐进呈现 + 代码执行:

1. 发现 -按意图（严重性、成分、关键字）搜索分析方法
2. 探索 -按需获取类型定义
3. 执行 -编写在本地处理数据的代码
4. 总结 -只返回见解，不返回原始数据

结果：98%+令牌减少，无限可扩展性，更好的代理体验

建筑

┌─────────────────────────────────────────────────────┐
│  AI Agent (Claude)                                  │
│  ├─ Searches for methods: "degraded operators"     │
│  ├─ Gets type definitions: ClusterOperator         │
│  ├─ Writes analysis code                           │
│  └─ Receives compact results                       │
└─────────────────────────────────────────────────────┘
                      ↓
┌─────────────────────────────────────────────────────┐
│  Progressive Disclosure Layer (2 Meta-Tools)        │
│  ├─ mustGather_searchAnalysis()                    │
│  │  → Returns: method signatures, examples         │
│  │  → Tokens: ~200 per search                      │
│  │                                                  │
│  └─ mustGather_getTypeDefinition()                 │
│     → Returns: TypeScript interfaces               │
│     → Tokens: ~150 per type lookup                 │
└─────────────────────────────────────────────────────┘
                      ↓
┌─────────────────────────────────────────────────────┐
│  Analysis Method Index (11+ methods)                │
│  ├─ getDegradedOperators()                         │
│  ├─ getFailingPods()                               │
│  ├─ getEtcdHealth()                                │
│  └─ ... 8 more (easily extensible to 100+)        │
└─────────────────────────────────────────────────────┘
                      ↓
┌─────────────────────────────────────────────────────┐
│  Code Execution Environment                         │
│  ├─ MustGatherAnalyzer (helper library)            │
│  ├─ Process data locally (no token overhead)       │
│  ├─ Cross-correlate events, logs, resources        │
│  └─ Return only summaries                          │
└─────────────────────────────────────────────────────┘
                      ↓
┌─────────────────────────────────────────────────────┐
│  Must-Gather Data (539MB)                           │
│  ├─ cluster-scoped-resources/                      │
│  ├─ namespaces/                                    │
│  ├─ etcd_info/                                     │
│  └─ host_service_logs/                             │
└─────────────────────────────────────────────────────┘

安装

1.克隆和安装

git clone https://github.com/Prshanth684/must-gather-code-execution-mcp.git
cd must-gather-code-execution-mcp
npm install
npm run build

2.获取必须收集的数据

Collect必须从OpenShift集群收集数据：

oc adm must-gather

这将创建一个类似的目录 must-gather.local.XXXXX/ 包含您的群集诊断。

用法

MCP服务器（推荐）

启动渐进式披露MCP服务器：

export MUST_GATHER_PATH=/path/to/must-gather
npm run start

在Claude桌面中配置(claude_desktop_config.json):

{
  "mcpServers": {
    "must-gather": {
      "command": "node",
      "args": ["/absolute/path/to/must-gather-code-execution-mcp/dist/mcp-server.js"],
      "env": {
        "MUST_GATHER_PATH": "/absolute/path/to/must-gather.local.xxxxx"
      }
    }
  }
}

渐进式披露工作流程

代理交互示例：

User: "What's wrong with my cluster?"

Agent thinks: "I need to discover critical cluster health methods"

Step 1: SEARCH FOR METHODS
→ Uses: mustGather_searchAnalysis({ severity: "critical", scope: "cluster" })
→ Returns:
  - getDegradedOperators(): ClusterOperator[]
  - getEtcdHealth(): EtcdHealth[]
  - usage: "CODE EXECUTION PATTERN: (1) READ library resource, (2) WRITE script, (3) EXECUTE with tsx"
→ Tokens: ~200

Step 2: READ LIBRARY RESOURCE
→ Uses: ReadMcpResourceTool({ server: "must-gather", uri: "file:///must-gather-lib.ts" })
→ Returns: Complete TypeScript library code
→ Tokens: ~1,500 (one-time cost)

Step 3: WRITE ANALYSIS SCRIPT
→ Agent writes must-gather-lib.ts to current directory (from resource)
→ Agent writes analysis script (e.g., analyze-cluster.ts):
  import { MustGatherAnalyzer } from './must-gather-lib.js';
  const analyzer = new MustGatherAnalyzer({ basePath: '/path' });

  const degraded = analyzer.getDegradedOperators();
  const etcd = analyzer.getEtcdHealth().filter(e => !e.health);

  console.log({
    status: degraded.length === 0 && etcd.length === 0 ? 'Healthy' : 'Degraded',
    issues: {
      degradedOperators: degraded.length,
      unhealthyEtcd: etcd.length
    }
  });
→ Tokens: ~100

Step 4: EXECUTE ANALYSIS
→ Uses: Bash({ command: "tsx analyze-cluster.ts" })
→ Returns: Only the concise result object
→ Tokens: ~50

Total: ~1,850 tokens first time, ~350 tokens subsequent (vs ~11,000 with traditional approach!)

关键洞察：图书馆资源只需读取一次，即可用于所有后续分析，这使得多步骤调查非常高效。

代码执行模式详解

MCP服务器使用 嵌入式指令 在工具描述中，指导AI代理完成代码执行工作流程：

1. 工具说明：The mustGather_searchAnalysis 工具描述明确地告诉代理：

- 先搜索方法 - 读取库资源（uri:file:///must-gather-lib.ts) - 编写一个从导入的TypeScript脚本。/must-father-lib.js - 使用tsx执行脚本

1. 结果使用说明：当发现方法时，响应包括 usage 带有分步说明的字段：

   CODE EXECUTION PATTERN:
   1. READ the library: Use ReadMcpResourceTool with server="must-gather" and uri="file:///must-gather-lib.ts"
   2. WRITE a TypeScript script in the current directory
   3. EXECUTE with: tsx your-script.ts

1. 资源描述说明：库资源描述告诉代理：

- 读取资源内容 - 写下来。/must-father-lib.ts - 在分析脚本中从中导入

这种方法将执行指令直接嵌入到工具描述中，以指导LLM完成复杂的工作流程。

可用元工具

1. mustGather_searchAnalysis

按组件、严重性、范围、类别或关键字搜索分析方法。

参数：

• component （可选）：“etcd”、“运算符”、“pod”、“节点”、“事件”、“命名空间”
• severity （可选）：“严重”、“警告”、“信息”
• scope （可选）：“集群”、“命名空间”、“pod”、“节点”、“容器”
• category （可选）：“健康”、“性能”、“配置”、“日志”
• keyword （可选）：自由文本搜索（例如，“降级”、“失败”、“错误”）
• limit （可选）：最大结果（默认10，最大50）

退货：

{
  summary: string,
  totalMethods: number,
  methods: [{
    name: string,
    signature: string,
    description: string,
    component: string,
    severity: string,
    scope: string,
    category: string,
    parameters: Parameter[],
    returns: string,
    example: string  // TypeScript code example
  }],
  usage: string  // How to import and use
}

示例：

// Find critical cluster health methods
searchAnalysis({ severity: "critical", scope: "cluster" })
→ Returns: getDegradedOperators, getEtcdHealth

// Find pod-related methods
searchAnalysis({ component: "pods" })
→ Returns: getPods, getFailingPods, getPodLogs

// Find methods by keyword
searchAnalysis({ keyword: "degraded" })
→ Returns: getDegradedOperators (exact match)

// Find all log-related methods
searchAnalysis({ category: "logs" })
→ Returns: getPodLogs

2. mustGather_getTypeDefinition

获取必须收集的数据结构的TypeScript类型定义。

参数：

• typeNames （必填）：类型名称数组
• depth （可选）：嵌套类型的扩展深度（默认1，最大3）
• includeExamples （可选）：包括示例值

可用类型：

• Node -群集节点信息
• Pod -Pod详细信息
• Container -集装箱信息
• Event -Kubernetes事件
• EtcdHealth -Etcd健康状况
• ClusterOperator -OpenShift操作员状态
• Condition -标准Kubernetes条件
• MustGatherAnalyzer -帮助程序库API

退货：

{
  types: [{
    name: string,
    definition: string,  // TypeScript interface
    source: string,      // Source location
    examples?: any       // Sample data (if requested)
  }],
  availableTypes: string[]
}

示例：

// Get Pod type definition
getTypeDefinition({ typeNames: ["Pod"] })

// Get multiple types with nested expansion
getTypeDefinition({
  typeNames: ["Pod", "ClusterOperator"],
  depth: 2
})

// Get types with examples
getTypeDefinition({
  typeNames: ["Node"],
  includeExamples: true
})

帮助程序库API

这 MustGatherAnalyzer 类提供对必须收集的数据的编程访问：

class MustGatherAnalyzer {
  constructor(config: { basePath: string, dataDir?: string });

  // Namespace operations
  listNamespaces(): string[]

  // Node operations
  getNodes(): Node[]

  // Pod operations
  getPods(namespace?: string): Pod[]
  getFailingPods(): Pod[]
  getPodLogs(namespace: string, podName: string, container?: string): string | null

  // Event operations
  getEvents(namespace?: string): Event[]
  getWarningEvents(): Event[]

  // Cluster health
  getEtcdHealth(): EtcdHealth[]
  getEtcdStatus(): any
  getClusterOperators(): ClusterOperator[]
  getDegradedOperators(): ClusterOperator[]
}

所有11种方法都可以通过以下方式进行索引和发现 searchAnalysis.

例子

运行渐进式披露演示

npm run example:progressive-disclosure

这表明：

1. 按严重程度和范围搜索方法
2. 按需获取类型定义
3. 基于关键字的搜索
4. 特定组件搜索
5. 令牌使用情况比较

传统分析示例

# Find failing pods with errors
npm run example:failing-pods

# Comprehensive cluster health
npm run example:health

# Correlate pod failures with events
npm run example:correlate

渐进式披露的好处

代币效率

可扩展性

• 传统：每个新工具在初始上下文中添加约500个令牌
• 渐进呈现：每个新方法向初始上下文添加0个令牌
• 结果：可以添加100多种方法而不会受到惩罚

更好的代理体验

传统：

Agent: Uses get_degraded_operators()
       ↑ Must know exact name

渐进式披露：

Agent: Searches for "degraded"
       ↓ Discovers getDegradedOperators()
       ↓ Sees example usage
       ↓ Executes with confidence

发现示例

// Intent-based discovery
"find broken components" → getDegradedOperators
"failing pods" → getFailingPods
"etcd problems" → getEtcdHealth

// Component exploration
component: "operators" → getClusterOperators, getDegradedOperators
component: "pods" → getPods, getFailingPods, getPodLogs

// Severity filtering
severity: "critical" → getDegradedOperators, getEtcdHealth
severity: "warning" → getFailingPods, getWarningEvents

建筑细部

方法索引

所有分析方法均已编入索引 src/analysis/methodIndex.ts:

export interface AnalysisMethod {
  name: string;           // Method name
  signature: string;      // TypeScript signature
  description: string;    // What it does
  component: string;      // "etcd", "operators", "pods", etc.
  severity: string;       // "critical", "warning", "info"
  scope: string;          // "cluster", "namespace", "pod", etc.
  category: string;       // "health", "logs", etc.
  parameters: Parameter[];
  returns: string;
  example: string;        // TypeScript code example
  keywords: string[];     // For search
}

搜索算法

位于 src/analysis/search.ts:

1. 过滤器 按确切的成分、严重程度、范围、类别
2. 得分 按关键字匹配：

- 姓名匹配：100分 - 名称包含关键字：80分 - 关键字数组匹配：每个20分 - 描述匹配：10分

1. 排名 按分数（最高者优先）
2. 限制 结果（默认10，最大50）

发电机类型

位于 src/codegen/typeGenerator.ts:

• 从库代码生成TypeScript接口
• 支持嵌套类型扩展（可配置深度）
• 可选示例值
• 循环参考预防

添加新的分析方法

渐进式披露使得添加新功能变得轻而易举：

步骤1：将方法添加到库中

// must-gather-lib.ts
export class MustGatherAnalyzer {
  getNetworkPolicies(namespace?: string): NetworkPolicy[] {
    // Implementation
  }
}

第二步：为方法建立索引

// src/analysis/methodIndex.ts
{
  name: 'getNetworkPolicies',
  signature: 'getNetworkPolicies(namespace?: string): NetworkPolicy[]',
  description: 'Get network policies from a namespace or all namespaces',
  component: 'networking',
  severity: 'info',
  scope: 'namespace',
  category: 'configuration',
  parameters: [
    { name: 'namespace', type: 'string', optional: true }
  ],
  returns: 'NetworkPolicy[]',
  example: `const policies = analyzer.getNetworkPolicies('default');`,
  keywords: ['network', 'policy', 'firewall', 'security', 'ingress', 'egress']
}

第三步：完成！

• 方法可自动发现
• 可按组件搜索：“网络”
• 可按关键字搜索：“网络”、“策略”、“安全”
• 无需更改MCP服务器
• 无上下文开销

逐步披露实施

此实现使用渐进式披露模式进行必须收集的分析：

从v1.0迁移

突破性变化

v1.0 暴露了11个直接工具：

• list_namespaces()
• get_nodes()
• get_pods(namespace?)
• …8更多

v2.0 公开了2个元工具：

• mustGather_searchAnalysis(...)
• mustGather_getTypeDefinition(...)

迁移路径

之前（v1.0）：

// Agent directly calls tool
const pods = await get_pods({ namespace: 'default' });

在（v2.0）之后：

// Agent discovers method
const methods = await searchAnalysis({ component: 'pods' });
// → finds getPods

// Agent writes code
import { MustGatherAnalyzer } from './must-gather-lib.js';
const analyzer = new MustGatherAnalyzer({ basePath: '/path' });
const pods = analyzer.getPods('default');

优点：

• 代理学会发现能力
• 更适合复杂的多步分析
• 扩展到更多方法

注： v1.0服务器另存为 mcp-server.traditional.ts 以供参考。

演出

• 初始上下文：约500个代币（而传统代币约6000个）
• 搜索查询：每次搜索约200个令牌
• 类型查找：每种类型约150个令牌
• 总工作流程：10个查询约2500个令牌（传统约11000个）

贡献

要添加新的分析方法，请执行以下操作：

1. 添加实现 must-gather-lib.ts
2. 将索引条目添加到 src/analysis/methodIndex.ts
3. 将类型定义添加到 src/codegen/typeGenerator.ts （如果是新类型）
4. 构建和测试： npm run build && npm run example:progressive-disclosure

许可证

麻省理工学院

相关

• Anthropic：使用MCP执行代码
• 模型上下文协议
• OpenShift必须集合

引用

如果你在工作中使用这种模式，请引用：

@software{must_gather_progressive_disclosure,
  title = {Must-Gather Progressive Disclosure MCP Server},
  author = {Prashanth Sundararaman},
  year = {2025},
  url = {https://github.com/Prshanth684/must-gather-code-execution-mcp},
  note = {Based on Anthropic's progressive disclosure pattern for MCP}
}