Skip to main content
Glama

Ilograph

ARCHITECTURE.md10.9 kB
# Architecture The Ilograph MCP Server is built with a modular, scalable architecture designed for high performance and maintainability. This document provides detailed technical information about the system design and implementation patterns. ## System Overview The server acts as a **dynamic Ilograph domain expert**, providing AI agents with comprehensive access to live Ilograph documentation and examples through a FastMCP-based architecture. ``` ┌─────────────────────────────────────────────────────────────┐ │ MCP Client Layer │ │ (Cursor, GitHub Copilot, etc.) │ └─────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ FastMCP Server │ │ (Tool Registration) │ └─────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ Tool Layer │ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ │ │ Documentation │ │ Example Access │ │ Health Checks │ │ │ │ Tools │ │ Tools │ │ Tools │ │ │ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ └─────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ Core Layer │ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ │ │ Content Fetcher │ │ Cache System │ │ Content Parser │ │ │ │ (HTTP Client) │ │ (TTL-based) │ │ (HTML→Markdown) │ │ │ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ └─────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ External Sources │ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ │ │ Ilograph Docs │ │ Static Examples │ │ Icon Catalog │ │ │ │ (ilograph.com) │ │ (Local Files) │ │ (Future) │ │ │ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ └─────────────────────────────────────────────────────────────┘ ``` ## Project Structure ``` src/ilograph_mcp/ ├── __init__.py # Package exports and public API ├── server.py # Main FastMCP server instance ├── core/ │ ├── __init__.py │ ├── fetcher.py # HTTP content fetching with retry logic │ ├── cache.py # TTL-based in-memory caching system │ └── content_processor.py # Content processing and sanitization ├── tools/ │ ├── __init__.py │ ├── fetch_documentation_tool.py # Documentation access tools │ └── register_example_tools.py # Example diagram tools ├── utils/ │ ├── __init__.py │ ├── http_client.py # HTTP client with connection pooling │ ├── markdown_converter.py # HTML to Markdown conversion │ ├── content_sanitizer.py # Content cleaning utilities │ └── llm_formatter.py # LLM-optimized formatting └── static/ └── examples/ ├── aws-distributed-load-testing.ilograph ├── stack-overflow-architecture-2016.ilograph └── serverless-on-aws.ilograph ``` ## Core Components ### 1. FastMCP Server (`server.py`) The main server instance built on the FastMCP framework: ```python @mcp.tool() async def example_tool(parameter: str, ctx: Context) -> dict: """FastMCP tool with proper annotations and error handling.""" # Tool implementation with context logging ``` **Key Features:** - **Decorator-based Tools**: Uses `@mcp.tool()` for exposing functionality - **Async/Await Support**: First-class async support for I/O operations - **Context Integration**: Built-in logging, HTTP requests, and progress reporting - **Type Safety**: Pydantic integration for request/response validation ### 2. Content Fetcher (`core/fetcher.py`) Handles dynamic content retrieval from external sources: ```python class ContentFetcher: async def fetch_documentation(self, section: str) -> str: """Fetch and process documentation from ilograph.com""" # HTTP request with caching and error handling async def fetch_icon_catalog(self) -> List[dict]: """Fetch live icon catalog for search functionality""" # Dynamic catalog retrieval ``` **Features:** - **Connection Pooling**: Efficient HTTP client with reused connections - **Retry Logic**: Exponential backoff for transient failures - **Rate Limiting**: Intelligent throttling for external API calls - **Error Recovery**: Graceful degradation with fallback strategies ### 3. Caching System (`core/cache.py`) Multi-tier TTL-based caching for optimal performance: ```python class TTLCache: def __init__(self): self.cache_tiers = { "raw_html": {"ttl": 86400, "max_size_mb": 50}, "processed_markdown": {"ttl": 86400, "max_size_mb": 100}, "structured_data": {"ttl": 43200, "max_size_mb": 25}, } ``` **Cache Strategies:** - **Raw HTML Content**: 24h TTL for source HTML - **Processed Markdown**: 24h TTL for converted content - **Structured Data**: 12h TTL for parsed/indexed content - **Memory Management**: Automatic eviction based on size and TTL ### 4. Content Processing (`utils/markdown_converter.py`) Converts HTML documentation to LLM-optimized markdown: ```python class IlographMarkdownConverter: def convert_html_to_markdown(self, html: str) -> str: """Convert HTML to clean, structured markdown""" # HTML parsing, content extraction, and formatting ``` **Processing Pipeline:** 1. **HTML Parsing**: BeautifulSoup-based parsing with error handling 2. **Content Extraction**: Intelligent main content identification 3. **Navigation Removal**: Strip sidebars, ads, and navigation elements 4. **Link Resolution**: Convert relative to absolute URLs 5. **Code Preservation**: Maintain YAML syntax highlighting 6. **Markdown Generation**: Clean, structured output for LLM consumption ## Tool Architecture ### Tool Registration Pattern ```python # Individual tool files export registration functions def register_documentation_tools(mcp: FastMCP) -> None: """Register all documentation-related tools""" @mcp.tool(annotations={ "title": "Fetch Documentation", "readOnlyHint": True, "description": "Fetches Ilograph documentation sections" }) async def fetch_documentation_tool(section: str, ctx: Context) -> str: # Tool implementation ``` ### Error Handling Pattern All tools follow consistent error handling: ```python async def tool_implementation(param: str, ctx: Context) -> dict: try: await ctx.info(f"Processing {param}...") result = await process_content(param) return {"success": True, "data": result} except ValidationError as e: await ctx.error(f"Validation error: {str(e)}") return {"success": False, "error": "validation", "message": str(e)} except Exception as e: await ctx.error(f"Unexpected error: {str(e)}") return {"success": False, "error": "internal", "message": "Service unavailable"} ``` ## Performance Characteristics ### Response Time Targets - **Documentation Fetching**: < 500ms (cached), < 2s (fresh) - **Example Access**: < 100ms (always cached) - **Health Checks**: < 200ms - **List Operations**: < 100ms ### Caching Strategy - **Hit Rate Target**: > 90% for documentation requests - **Memory Usage**: < 200MB for cache storage - **TTL Management**: Automatic cleanup and refresh - **Fallback Handling**: Serve stale content if fresh unavailable ### Scalability Considerations - **Concurrent Requests**: Support for 100+ concurrent tool calls - **Memory Efficiency**: Streaming for large content - **Connection Limits**: Configurable HTTP client pool sizes - **Rate Limiting**: Respectful external API usage ## Testing Architecture ### Test Structure ``` tests/ ``` **SEE https://gofastmcp.com/patterns/testing** ### Test Patterns - **Async Testing**: Full async/await support with pytest-asyncio - **Mocking**: External service mocking for reliable tests - **Fixtures**: Reusable test data and server instances - **Coverage**: Comprehensive coverage requirements (>90%)

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