Ilograph

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:592-686 (handler)

  The handler function for the 'get_validation_help' tool. It returns a comprehensive markdown-formatted guide on Ilograph diagram validation, including common issues, solutions, and examples. Registered via @mcp.tool() decorator with metadata.

      @mcp.tool(
          annotations={
              "title": "Get Validation Help",
              "readOnlyHint": True,
              "description": "Provides guidance on Ilograph diagram validation and common issues",
          }
      )
      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/server.py:70-70 (registration)

  The call to register_validate_diagram_tool(mcp) in the server setup, which defines and registers the get_validation_help tool (along with validate_diagram_tool).

  register_validate_diagram_tool(mcp)

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

  Tool name listed in get_tool_info() for reference.

  "get_validation_help",

• src/ilograph_mcp/tools/register_validate_diagram_tool.py:600-608 (schema)

  Docstring defining the tool's purpose and return type (str). No input parameters required.

  """
  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
  """