Skip to main content
Glama

Ilograph

TOOLS.md14.2 kB
# Tools Reference The Ilograph MCP Server provides comprehensive tools for accessing Ilograph documentation, examples, diagram validation, and icon searching. All tools are designed to be compatible with current MCP clients (Cursor, GitHub Copilot, etc.) that support the tools specification. ## Available Tools ### 1. `fetch_documentation_tool` Fetches comprehensive documentation from Ilograph's official website. **Parameters:** - `section` (str): Documentation section to fetch **Supported Sections:** - `resources` - Resource tree organization, hierarchies, instanceOf patterns - `relation-perspectives` - Arrow connections, from/to properties, routing - `sequence-perspectives` - Time-based diagrams with steps, bidirectional flows - `references` - Resource reference patterns and advanced referencing - `advanced-references` - Complex reference scenarios and usage patterns - `resource-sizes-and-positions` - Layout control, resource sizing, visual hierarchy - `parent-overrides` - Resource parent overrides in perspectives - `perspectives-other-properties` - Additional perspective properties and options - `icons` - Icon system with iconStyle, icon paths, and categorization - `walkthroughs` - Interactive step-by-step guides through diagrams - `contexts` - Multiple context views with roots, extends inheritance - `imports` - Namespace management with from/namespace properties - `markdown` - Rich text support in descriptions, notes, and diagram text - `tutorial` - Complete tutorial for learning Ilograph diagram creation **Returns:** Clean markdown content with detailed explanations, examples, and best practices. **Example Usage:** ```python docs = await client.call_tool("fetch_documentation_tool", { "section": "resources" }) ``` ### 2. `list_documentation_sections` Lists all available documentation sections with descriptions and usage examples. **Parameters:** None **Returns:** Formatted list of available documentation sections with descriptions and guidance on when to use each section. **Example Usage:** ```python sections = await client.call_tool("list_documentation_sections", {}) ``` ### 3. `check_documentation_health` Performs health checks on the documentation service and returns cache statistics. **Parameters:** None **Returns:** Health status report with service connectivity and cache information including: - Service connectivity status - Cache hit/miss statistics - Available documentation sections - System performance metrics **Example Usage:** ```python health = await client.call_tool("check_documentation_health", {}) ``` ### 4. `list_examples` Lists available Ilograph example diagrams with their categories and descriptions. **Parameters:** - `category` (optional): Filter examples by complexity ('beginner', 'intermediate', 'advanced') **Available Examples:** - `serverless-on-aws.ilograph` - Serverless web application architecture on AWS (intermediate) - `stack-overflow-architecture-2016.ilograph` - High-traffic web application with .NET, Redis, SQL Server (advanced) - `aws-distributed-load-testing.ilograph` - Distributed load testing solution with containerized tasks (advanced) **Returns:** Dictionary containing a list of available examples and guidance message. **Example Usage:** ```python # List all examples examples = await client.call_tool("list_examples", {}) # Filter by category intermediate_examples = await client.call_tool("list_examples", { "category": "intermediate" }) ``` ### 5. `fetch_example` Retrieves a specific Ilograph example diagram with its content and rich metadata. **Parameters:** - `example_name` (str): The filename of the example to fetch (e.g., 'serverless-on-aws.ilograph') **Returns:** Dictionary containing: - Complete diagram content - Learning objectives - Patterns demonstrated - Category and description - Metadata about the example **Example Usage:** ```python example = await client.call_tool("fetch_example", { "example_name": "serverless-on-aws.ilograph" }) ``` ### 6. `fetch_spec_tool` Fetches the official Ilograph specification from the authoritative source with complete property definitions. **Parameters:** None **Returns:** Complete specification in markdown format containing: - Top-level properties table (resources, perspectives, imports, contexts, etc.) - Resource properties and types (name, subtitle, description, color, style, etc.) - Perspective properties and types (id, name, notes, color, extends, relations, etc.) - Relation, Sequence, Step definitions with all properties - Context, Layout, Import specifications - All property types and required/optional flags This tool provides the authoritative reference for all Ilograph properties, perfect for validation and quick property lookups. **Example Usage:** ```python spec = await client.call_tool("fetch_spec_tool", {}) ``` ### 7. `check_spec_health` Performs health checks specifically on the specification fetching service. **Parameters:** None **Returns:** Health status report focused on specification service including: - Specification endpoint connectivity status - Specification cache information - Response time metrics - Service availability status **Example Usage:** ```python spec_health = await client.call_tool("check_spec_health", {}) ``` ### 8. `validate_diagram_tool` Validates Ilograph diagram syntax and provides detailed error messages with suggestions. **Parameters:** - `content` (str): The Ilograph diagram content as a string **Returns:** Dictionary containing comprehensive validation results: - `success` (bool): Overall validation success status - `yaml_valid` (bool): Whether YAML syntax is valid - `schema_valid` (bool): Whether Ilograph schema is valid - `summary`: Object with total counts of errors, warnings, and info messages - `errors`: Array of error objects with messages, locations, and suggestions - `warnings`: Array of warning objects for non-critical issues - `info`: Array of informational messages and suggestions - `assessment`: Human-readable overall assessment This tool performs comprehensive validation in two stages: 1. **YAML Syntax Check**: Ensures the diagram is valid YAML 2. **Ilograph Schema Validation**: Checks Ilograph-specific requirements like required properties, valid property names, and relationship structures **Example Usage:** ```python diagram_content = ''' resources: - name: Web Server subtitle: Frontend description: Serves the web application children: - name: Load Balancer description: Distributes traffic perspectives: - name: System Overview relations: - from: User to: Web Server label: HTTPS requests ''' result = await client.call_tool("validate_diagram_tool", { "content": diagram_content }) if result["success"]: print("✅ Diagram is valid!") if result["warnings"]: print(f"⚠️ {len(result['warnings'])} suggestions for improvement") else: print("❌ Diagram has errors:") for error in result["errors"]: print(f" - {error['message']}") if error.get("suggestion"): print(f" Suggestion: {error['suggestion']}") ``` ### 9. `get_validation_help` Provides comprehensive guidance on Ilograph diagram validation and common issues. **Parameters:** None **Returns:** Detailed validation help in markdown format including: - Overview of the validation process - Common YAML syntax issues and solutions - Ilograph schema requirements - Valid property lists and examples - Tips for successful diagram creation - References to other helpful tools **Example Usage:** ```python help_content = await client.call_tool("get_validation_help", {}) print(help_content) # Displays comprehensive validation guidance ``` ### 10. `search_icons_tool` Searches the current icon catalog with semantic matching and provider filtering. **Parameters:** - `query` (str): Search term (e.g., 'database', 'aws lambda', 'kubernetes', 'storage') - `provider` (optional str): Filter by provider ('AWS', 'Azure', 'GCP', 'Networking') **Returns:** List of matching icons with paths, categories, and usage information. Each icon dict contains: - `path`: The icon path for use in Ilograph diagrams - `provider`: The cloud provider or category (AWS, Azure, GCP, Networking) - `category`: The service category (e.g., 'Compute', 'Database', 'Analytics') - `name`: The specific icon name - `usage`: Example usage string for Ilograph diagrams **Example Usage:** ```python # Search for database icons database_icons = await client.call_tool("search_icons_tool", { "query": "database" }) # Search for AWS compute icons aws_compute = await client.call_tool("search_icons_tool", { "query": "compute", "provider": "AWS" }) ``` ### 11. `list_icon_providers_tool` Lists all available icon providers and their categories. **Parameters:** None **Returns:** Dictionary containing provider information with categories and icon counts for each provider (AWS, Azure, GCP, Networking). **Example Usage:** ```python providers = await client.call_tool("list_icon_providers_tool", {}) ``` ## Tool Design Principles ### Compatibility All tools are designed with the **tool-first** approach to ensure compatibility with current MCP clients that only support the tools specification (not resources or prompts). ### Error Handling All tools implement comprehensive error handling with: - Structured error responses - Meaningful error messages - Graceful fallbacks where possible - Logging for debugging ### Performance - **Intelligent Caching**: TTL-based caching with fallback strategies - **Sub-500ms Response Times**: Optimized for agent workflows - **Connection Pooling**: Efficient HTTP client with retry logic ### Content Processing - **LLM-Optimized Output**: Content formatted for AI agent consumption - **Clean Markdown**: HTML converted to clean, structured markdown - **Preserved Code Examples**: YAML code blocks with proper syntax highlighting - **Absolute Links**: All relative links converted to absolute URLs ## Future Tools (Planned) > **Note:** Additional advanced tools are planned for future releases. ### Planned Tools - **Best Practices Guidance**: AI-powered suggestions for diagram improvements - **Template Generation**: Generate diagram templates based on common patterns - **Advanced Validation**: Extended validation with cross-reference checking and best practice analysis ## Integration Examples ### Complete Workflow Example ```python from fastmcp import Client from ilograph_mcp import create_server async def create_diagram_workflow(): mcp = create_server() async with Client(mcp) as client: # 1. Check service health health = await client.call_tool("check_documentation_health", {}) print("Service status:", health) # 2. List available documentation sections = await client.call_tool("list_documentation_sections", {}) print("Available sections:", sections) # 3. Fetch specific documentation resources_docs = await client.call_tool("fetch_documentation_tool", { "section": "resources" }) # 4. Get example for reference examples = await client.call_tool("list_examples", { "category": "intermediate" }) # 5. Fetch specific example example = await client.call_tool("fetch_example", { "example_name": "serverless-on-aws.ilograph" }) # 6. Get specification for property reference spec = await client.call_tool("fetch_spec_tool", {}) # 7. Check specification service health spec_health = await client.call_tool("check_spec_health", {}) # 8. Validate a diagram (example) test_diagram = ''' resources: - name: Test Resource description: A simple test ''' validation_result = await client.call_tool("validate_diagram_tool", { "content": test_diagram }) # 9. Get validation help if needed if not validation_result["success"]: help_content = await client.call_tool("get_validation_help", {}) # 10. Search for appropriate icons database_icons = await client.call_tool("search_icons_tool", { "query": "database", "provider": "AWS" }) # 11. Get icon provider information icon_providers = await client.call_tool("list_icon_providers_tool", {}) # Now use the documentation, examples, specification, and icons to create diagrams return { "documentation": resources_docs, "example": example, "specification": spec, "spec_health": spec_health, "validation": validation_result, "icons": database_icons, "icon_providers": icon_providers, } ``` ### Error Handling Example ```python async def safe_tool_usage(): mcp = create_server() async with Client(mcp) as client: try: result = await client.call_tool("fetch_documentation_tool", { "section": "invalid-section" }) if isinstance(result, dict) and not result.get("success", True): print(f"Tool error: {result.get('error', 'Unknown error')}") return None return result except Exception as e: print(f"Client error: {e}") return None ``` ## Tool Response Formats ### Success Response Most tools return structured responses: ```python { "success": True, "data": "content or structured data", "metadata": { "source_url": "https://...", "cache_hit": True, "processing_time": "0.123s" } } ``` ### Error Response ```python { "success": False, "error": "error_type", "message": "Human-readable error message", "details": "Additional error context" } ``` ### Content-Only Response Some tools return direct content for simpler integration: ```python "# Documentation Content\n\nMarkdown formatted content..." ```

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/QuincyMillerDev/ilograph-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server