Class: KairosMcp::Tools::ToolGuide

Inherits:
BaseTool
  • Object
show all
Defined in:
lib/kairos_mcp/tools/tool_guide.rb

Overview

ToolGuide: Dynamic tool discovery and guidance system

Provides:

  • catalog: Category-based tool listing

  • search: Keyword/tag-based search

  • recommend: Goal-based tool recommendations

  • detail: Detailed tool information

  • workflow: Common workflow patterns

  • suggest: Auto-infer metadata from tool definition (for LLM)

  • apply_metadata: Apply metadata with human approval

  • validate: Validate metadata structure

Constant Summary collapse

WORKFLOWS =

Predefined workflow patterns

{
  'knowledge_lifecycle' => {
    title: 'Knowledge Lifecycle',
    description: 'Save temporary ideas, validate, then promote to permanent knowledge',
    steps: [
      { tool: 'context_save', desc: 'Save hypothesis in L2', params: 'name: "my_idea", content: "..."' },
      { tool: 'skills_audit', desc: 'Check promotion candidates', params: 'command: "recommend"' },
      { tool: 'skills_promote', desc: 'Promote to L1', params: 'from_layer: "L2", to_layer: "L1"' }
    ]
  },
  'health_check' => {
    title: 'System Health Check',
    description: 'Verify blockchain integrity and layer health',
    steps: [
      { tool: 'chain_status', desc: 'Check blockchain status', params: '' },
      { tool: 'chain_verify', desc: 'Verify integrity', params: '' },
      { tool: 'skills_audit', desc: 'Check layer health', params: 'command: "check"' },
      { tool: 'state_status', desc: 'Check uncommitted changes', params: '' }
    ]
  },
  'skill_evolution' => {
    title: 'L0 Skill Evolution',
    description: 'Safely modify L0 meta-skills with backup and recording',
    steps: [
      { tool: 'skills_dsl_list', desc: 'List current skills', params: '' },
      { tool: 'skills_rollback', desc: 'Create backup snapshot', params: 'action: "snapshot"' },
      { tool: 'skills_evolve', desc: 'Propose changes', params: 'skill_id: "...", changes: {...}' },
      { tool: 'chain_history', desc: 'Verify recording', params: '' }
    ]
  },
  'tool_onboarding' => {
    title: 'New Tool Onboarding',
    description: 'Add metadata for a new tool (LLM workflow)',
    steps: [
      { tool: 'tool_guide', desc: 'Auto-suggest metadata', params: 'command: "suggest", tool_name: "new_tool"' },
      { tool: 'tool_guide', desc: 'Validate metadata', params: 'command: "validate", metadata: {...}' },
      { tool: 'tool_guide', desc: 'Apply with approval', params: 'command: "apply_metadata", approved: true' }
    ]
  }
}.freeze
CATEGORIES =

Category definitions with display info

{
  chain: { label: 'Blockchain', description: 'Blockchain operations and verification' },
  knowledge: { label: 'Knowledge (L1)', description: 'Project knowledge management' },
  context: { label: 'Context (L2)', description: 'Temporary context management' },
  skills: { label: 'Skills (L0)', description: 'Meta-skill management' },
  resource: { label: 'Resource', description: 'Unified resource access' },
  state: { label: 'State', description: 'State commit and snapshot management' },
  guide: { label: 'Guide', description: 'Help and discovery tools' },
  utility: { label: 'Utility', description: 'General utility tools' }
}.freeze
READONLY_COMMANDS = 
%w[catalog search recommend detail workflow suggest validate].freeze
WRITE_COMMANDS = 
%w[apply_metadata].freeze

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from BaseTool

#initialize, #invoke_tool, #to_full_schema, #to_schema

Constructor Details

This class inherits a constructor from KairosMcp::Tools::BaseTool

Class Method Details

.metadata_file ⇒ Object 



21
22
23
 
# File 'lib/kairos_mcp/tools/tool_guide.rb', line 21

def self.metadata_file
  KairosMcp.tool_metadata_path
end

Instance Method Details

#call(arguments) ⇒ Object 



159
160
161
162
163
164
165
166
167
168
169
 
# File 'lib/kairos_mcp/tools/tool_guide.rb', line 159

def call(arguments)
  command = arguments['command']

  if READONLY_COMMANDS.include?(command)
    handle_readonly_command(command, arguments)
  elsif WRITE_COMMANDS.include?(command)
    handle_write_command(command, arguments)
  else
    text_content("Unknown command: #{command}")
  end
end

#category ⇒ Object 



92
93
94
 
# File 'lib/kairos_mcp/tools/tool_guide.rb', line 92

def category
  :guide
end

#description ⇒ Object 



86
87
88
89
90
 
# File 'lib/kairos_mcp/tools/tool_guide.rb', line 86

def description
  'Dynamic tool discovery and guidance. List tools by category, search by tags, ' \
  'get recommendations based on goals, view detailed tool info, and manage tool metadata. ' \
  'Also supports LLM workflow: suggest metadata, validate, and apply with human approval.'
end

#examples ⇒ Object 



100
101
102
103
104
105
106
107
108
 
# File 'lib/kairos_mcp/tools/tool_guide.rb', line 100

def examples
  [
    { title: 'List all tools by category', code: 'tool_guide(command: "catalog")' },
    { title: 'Search for save-related tools', code: 'tool_guide(command: "search", query: "save")' },
    { title: 'Get tool recommendation', code: 'tool_guide(command: "recommend", goal: "save project conventions")' },
    { title: 'View tool details', code: 'tool_guide(command: "detail", tool_name: "knowledge_update")' },
    { title: 'Suggest metadata for new tool', code: 'tool_guide(command: "suggest", tool_name: "my_new_tool")' }
  ]
end

#input_schema ⇒ Object 



114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
 
# File 'lib/kairos_mcp/tools/tool_guide.rb', line 114

def input_schema
  {
    type: 'object',
    properties: {
      command: {
        type: 'string',
        description: 'Command to execute',
        enum: READONLY_COMMANDS + WRITE_COMMANDS
      },
      query: {
        type: 'string',
        description: 'Search query (for search command)'
      },
      goal: {
        type: 'string',
        description: 'User goal for recommendations (for recommend command)'
      },
      tool_name: {
        type: 'string',
        description: 'Tool name (for detail, suggest, apply_metadata commands)'
      },
      workflow_name: {
        type: 'string',
        description: 'Workflow name (for workflow command)',
        enum: WORKFLOWS.keys
      },
      metadata: {
        type: 'object',
        description: 'Metadata to apply (for apply_metadata command)',
        properties: {
          category: { type: 'string' },
          usecase_tags: { type: 'array', items: { type: 'string' } },
          examples: { type: 'array' },
          related_tools: { type: 'array', items: { type: 'string' } }
        }
      },
      approved: {
        type: 'boolean',
        description: 'Human approval flag (required for apply_metadata)'
      }
    },
    required: ['command']
  }
end

#name ⇒ Object 



82
83
84
 
# File 'lib/kairos_mcp/tools/tool_guide.rb', line 82

def name
  'tool_guide'
end

#related_tools ⇒ Object 



110
111
112
 
# File 'lib/kairos_mcp/tools/tool_guide.rb', line 110

def related_tools
  %w[hello_world skills_list knowledge_list]
end

#usecase_tags ⇒ Object 



96
97
98
 
# File 'lib/kairos_mcp/tools/tool_guide.rb', line 96

def usecase_tags
  %w[help discovery catalog search recommend guide metadata]
end