get_validation_help

Instructions

    Provides comprehensive help for Ilograph diagram validation.

    Returns guidance on common validation issues, proper syntax,
    and best practices for creating valid Ilograph diagrams.

    Returns:
        str: Detailed validation help in markdown format
    

Implementation Reference

• src/ilograph_mcp/tools/register_validate_diagram_tool.py:599-685 (handler)

  The async handler function for the 'get_validation_help' tool. It returns a hardcoded markdown string with comprehensive Ilograph diagram validation guidance, including overview, validation process, common issues, top-level properties, example structure, and tips for success.

      async def get_validation_help(ctx: Context) -> str:
          """
          Provides comprehensive help for Ilograph diagram validation.
  
          Returns guidance on common validation issues, proper syntax,
          and best practices for creating valid Ilograph diagrams.
  
          Returns:
              str: Detailed validation help in markdown format
          """
          try:
              await ctx.info("Providing Ilograph validation help")
  
              help_content = """# Ilograph Diagram Validation Help
  
  ## Overview
  This validation tool checks your Ilograph diagrams for both YAML syntax correctness and Ilograph-specific schema compliance.
  
  ## Validation Process
  1. **YAML Syntax Check**: Ensures your diagram is valid YAML
  2. **Schema Validation**: Checks Ilograph-specific structure and properties
  3. **Best Practice Suggestions**: Provides recommendations for improvement
  
  ## Common Issues and Solutions
  
  ### YAML Syntax Errors
  - **Indentation**: Use consistent spaces (2 or 4), not tabs
  - **Missing Colons**: Properties need colons (`name: value`)
  - **List Format**: Use dashes for lists or bracket notation
  - **Quoted Strings**: Quote strings with special characters
  
  ### Ilograph Schema Issues
  - **Missing Required Properties**: Resources need `name` or `id`
  - **Unknown Properties**: Check property names against specification
  - **Duplicate IDs**: Resource IDs must be unique
  - **Invalid Relations**: Relations need both `from` and `to`
  
  ## Valid Top-Level Properties
  - `resources`: Your diagram components (required for meaningful diagrams)
  - `perspectives`: Different views of your architecture
  - `contexts`: Multiple context views
  - `imports`: External namespace imports
  - `layout`: Diagram layout properties
  
  ## Example Valid Structure
  ```yaml
  imports:
  - from: ilograph/aws
    namespace: AWS
  
  resources:
  - name: Web Server
    subtitle: Frontend
    description: Serves the web application
    icon: server.svg
    children:
    - name: Load Balancer
      instanceOf: AWS::ElasticLoadBalancer
  
  perspectives:
  - name: System Overview
    relations:
    - from: User
      to: Web Server
      label: HTTPS requests
  ```
  
  ## Getting More Help
  - Use `fetch_spec_tool()` to get the complete Ilograph specification
  - Use `fetch_documentation_tool(section='tutorial')` for detailed tutorials
  - Use `fetch_example_tool()` to see working example diagrams
  
  ## Tips for Success
  1. Start with simple structures and build complexity gradually
  2. Use consistent naming conventions
  3. Add descriptions to improve documentation
  4. Validate frequently during development
  5. Check examples for pattern guidance
  """
  
              await ctx.info("Validation help provided successfully")
              return help_content
  
          except Exception as e:
              error_msg = f"Error providing validation help: {str(e)}"
              await ctx.error(error_msg)
              return f"Error: {error_msg}"

• src/ilograph_mcp/tools/register_validate_diagram_tool.py:592-598 (registration)

  The @mcp.tool decorator that registers 'get_validation_help' as a FastMCP tool with title 'Get Validation Help' and readOnlyHint annotation.

  @mcp.tool(
      annotations={
          "title": "Get Validation Help",
          "readOnlyHint": True,
          "description": "Provides guidance on Ilograph diagram validation and common issues",
      }
  )

• src/ilograph_mcp/server.py:70-71 (registration)

  The call to register_validate_diagram_tool(mcp) in the server setup, which registers both validate_diagram_tool and get_validation_help tools.

  register_validate_diagram_tool(mcp)
  logger.info("Registered validate_diagram_tool")

• src/ilograph_mcp/tools/register_validate_diagram_tool.py:688-697 (registration)

  Helper function get_tool_info() that reports 'get_validation_help' as one of the tools provided by the validate_diagram_tool module.

  def get_tool_info() -> dict:
      """Get information about the validation tools for registration."""
      return {
          "name": "validate_diagram_tool",
          "description": "Comprehensive Ilograph diagram validation with detailed error reporting",
          "tools": [
              "validate_diagram_tool",
              "get_validation_help",
          ],
      }

• src/ilograph_mcp/server.py:55-55 (registration)

  Reference to 'get_validation_help' in the server instructions/description string shown to users.

  - get_validation_help: Provides guidance on Ilograph diagram validation and common issues