Add get_tool_info function for better tool discoverability

[raifdmueller]

Add get_tool_info function for better tool discoverability

Background

Currently, responsible-vibe-mcp provides excellent workflow management capabilities, but lacks a standardized get_tool_info function that would help users (both human and AI) understand the available tools and their capabilities. This is a common pattern used by other MCP servers for tool discovery and documentation.

Problem

When exploring the responsible-vibe-mcp tools, users currently need to:

1. Try different functions to understand the available tools
2. Guess at function parameters and capabilities
3. Understand the workflow system through trial and error

This creates a poor user experience and makes it harder for AI assistants to effectively use the tool.

Suggested Solution

Add a get_tool_info() function that returns comprehensive information about:

1. Tool Overview

• Tool name and version
• Purpose and philosophy
• Current status information

2. Available Functions

Based on my testing, the tool currently provides these functions:

• start_development() - Initialize new development with workflow selection
• whats_next() - Get phase-specific guidance and instructions
• proceed_to_phase() - Transition between workflow phases
• resume_workflow() - Continue development after breaks
• reset_development() - Clean slate restart
• list_workflows() - Show available workflow types

3. Workflow Information

• Available workflows (currently returns: bugfix, epcc, greenfield, minor, posts, slides, waterfall)
• Phase management concepts
• Plan file management

4. Usage Patterns

• Core workflow (whats_next after each interaction)
• Phase transition guidance
• Conversation context requirements

Implementation Reference

Based on similar implementations in other MCP servers (arc42, kroki, bash), the function should:

@mcp.tool()
async def get_tool_info() -> str:
    """Get comprehensive information about the responsible-vibe-mcp development workflow tools."""
    
    tool_info = {
        "tool_name": "Responsible Vibe MCP - Development Workflow Management",
        "version": "1.0.0",  # or appropriate version
        "purpose": "Structured development workflows with guided phase transitions",
        
        "available_tools": [
            {
                "name": "start_development",
                "description": "Initialize new development project with structured workflow",
                "parameters": ["workflow", "commit_behaviour"]
            },
            {
                "name": "whats_next", 
                "description": "Get phase-specific instructions and guidance",
                "parameters": ["context", "user_input", "conversation_summary", "recent_messages"]
            },
            # ... other tools
        ],
        
        "available_workflows": [
            # List from list_workflows() with descriptions
        ],
        
        "core_concepts": {
            "phase_management": "Structured progression through development phases",
            "plan_file_tracking": "Maintains development state in .vibe/development-plan-*.md",
            "conversation_context": "Stateless operation requires context in each whats_next() call"
        },
        
        "usage_guidelines": {
            "required_pattern": "Always call whats_next() after user interactions",
            "phase_transitions": "Only proceed when entrance criteria are met",
            "context_requirements": "Provide conversation history for stateless operation"
        }
    }
    
    return json.dumps(tool_info, indent=2, ensure_ascii=False)

Benefits

1. Improved Discoverability: Users can quickly understand all available functions
2. Better AI Integration: AI assistants can self-discover capabilities
3. Standardization: Follows established MCP patterns
4. Reduced Learning Curve: Clear documentation of concepts and usage patterns
5. Debugging Support: Current status information helps troubleshoot issues

Additional Observations

During testing, I noticed:

• The tool seems to always use "arc42-documentation" workflow regardless of selected workflow parameter
• The system provides excellent guided instructions through the whats_next() function
• Plan file management is well-structured but could benefit from better documentation
• The tool handles conversation context requirements well but this isn't immediately obvious to new users

Priority

This should be considered a medium priority enhancement as it significantly improves user experience and tool adoption without affecting core functionality.

---

Note: I've done extensive testing of the tool and can provide additional insights or help with implementation if needed.

[raifdmueller]

🐛 Critical Bug Discovery: Workflow Parameter Ignored

During my detailed testing, I've discovered a critical bug in the workflow selection mechanism:

Bug Description

The workflow parameter in start_development() is completely ignored when there's a local .vibe/workflow.yaml file present. Instead of using the specified workflow (bugfix, epcc, greenfield, etc.), the tool always falls back to the local custom workflow.

Test Results

With .vibe/workflow.yaml present:

start_development(workflow="bugfix")    → Returns "arc42-documentation" workflow
start_development(workflow="epcc")      → Returns "arc42-documentation" workflow  
start_development(workflow="greenfield") → Returns "arc42-documentation" workflow
start_development(workflow="custom")    → Returns "arc42-documentation" workflow

After removing .vibe/workflow.yaml:

start_development(workflow="bugfix")    → ✅ Returns correct "bugfix" workflow with phases: reproduce, analyze, fix, verify

Root Cause

The tool appears to prioritize local .vibe/workflow.yaml files over the workflow parameter, effectively making workflow selection non-functional when custom workflows exist.

Impact

• High: Users cannot select intended workflows
• Confusing UX: Tool silently ignores user choice
• Documentation mismatch: list_workflows() shows available options that can't actually be used

Expected Behavior

1. workflow="custom" should use .vibe/workflow.yaml
2. All other workflow values should use built-in workflows regardless of local files
3. Clear error message if specified workflow doesn't exist

Recommendation

This should be treated as a high priority bug as it breaks core functionality. The workflow selection logic needs to be fixed to respect the user's explicit workflow choice.

---

Note: This bug discovery actually strengthens the case for the get_tool_info function, as it would help users understand the current tool state and debug such issues more easily.

[raifdmueller]

✅ Implementation Complete

I've successfully implemented the get_tool_info function as requested in this issue.

Pull Request: #28
Branch: feature/issue-24-get-tool-info

What was implemented:

1. Comprehensive GetToolInfoHandler (src/server/tool-handlers/get-tool-info.ts)

   • Extends BaseToolHandler for consistency with existing patterns
   • Returns detailed JSON response with all available tools, workflows, core concepts, and usage guidelines
   • Includes current workflow state when available
   • Follows established logging and error handling patterns

2. Complete Integration

   • Tool registry registration in src/server/tool-handlers/index.ts
   • MCP server tool registration in src/server/server-config.ts
   • Proper TypeScript exports and error handling

Key Features:

• 7 Tools documented: All available tools including the new get_tool_info function itself
• 7 Workflows listed: Complete workflow information with descriptions and phases
• Core concepts explained: Phase management, plan file tracking, conversation context
• Usage guidelines provided: Required patterns, phase transitions, context requirements
• Current state included: Active workflow information when available

API Response Example:

{
  "tool_name": "Responsible Vibe MCP - Development Workflow Management",
  "version": "1.0.0", 
  "purpose": "Structured development workflows with guided phase transitions",
  "available_tools": [
    {
      "name": "get_tool_info",
      "description": "Get comprehensive information about all available tools and workflows",
      "parameters": [],
      "schema": { "required": [], "optional": [] }
    },
    // ... 6 other tools
  ],
  "available_workflows": [
    // ... all 7 workflows with descriptions
  ],
  "core_concepts": {
    "phase_management": "Structured progression through development phases...",
    "plan_file_tracking": "Maintains development state in .vibe/development-plan-*.md...",
    // ...
  },
  "usage_guidelines": {
    "required_pattern": "Always call whats_next() after user interactions...",
    // ...
  },
  "workflow_states": {
    // Current state when available
  }
}

This addresses all requirements mentioned in the issue:

• ✅ Better tool discoverability
• ✅ Improved AI integration
• ✅ Standardization following MCP patterns
• ✅ Reduced learning curve
• ✅ Comprehensive tool information

Ready for review and testing!