fetch_spec_tool
Read-only
Fetch the official Ilograph specification including all property types, perspectives, relations, sequences, and requirements for validation and reference.
Instructions
Fetches the official Ilograph specification from https://www.ilograph.com/docs/spec/
This tool provides the authoritative reference for all Ilograph properties, types,
and requirements in a structured table format - perfect for validation and quick lookups.
Returns:
str: Complete specification in markdown format with:
- Top-level properties table
- Resource properties and types
- Perspective properties and types
- Relation, Sequence, Step definitions
- Context, Layout, Import specifications
- All property types and requirements
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||
Implementation Reference
- The main handler function for the fetch_spec_tool. It fetches the Ilograph specification from the official source, converts it to markdown, wraps it with metadata headers, and returns the result. Handles errors gracefully with descriptive messages.
async def fetch_spec_tool(ctx: Context) -> str: """ Fetches the official Ilograph specification from https://www.ilograph.com/docs/spec/ This tool provides the authoritative reference for all Ilograph properties, types, and requirements in a structured table format - perfect for validation and quick lookups. Returns: str: Complete specification in markdown format with: - Top-level properties table - Resource properties and types - Perspective properties and types - Relation, Sequence, Step definitions - Context, Layout, Import specifications - All property types and requirements """ try: # Log the request await ctx.info("Fetching Ilograph specification from official source") # Get fetcher instance fetcher = get_fetcher() # Fetch specification content content = await fetcher.fetch_specification() if content is None: error_msg = "Failed to fetch Ilograph specification. The content may be temporarily unavailable." await ctx.error(error_msg) return f"Error: {error_msg}" # Add metadata header to the content content_with_header = f"""# Ilograph Specification **Source:** https://www.ilograph.com/docs/spec/ **Description:** Official Ilograph YAML format specification with complete property definitions **Last Updated:** Fetched on demand from official Ilograph documentation This specification provides the authoritative reference for all Ilograph diagram properties, types, and requirements. Use this for validation, quick property lookups, and understanding the complete Ilograph schema. --- {content} --- *This specification was fetched from the official Ilograph website and converted to markdown format for easy consumption. For the most up-to-date information, visit https://www.ilograph.com/docs/spec/* """ await ctx.info( f"Successfully fetched Ilograph specification ({len(content)} characters)" ) return content_with_header except Exception as e: error_msg = f"Unexpected error fetching Ilograph specification: {str(e)}" await ctx.error(error_msg) return f"Error: An unexpected error occurred while fetching the specification. Please try again later." - src/ilograph_mcp/tools/register_fetch_spec_tool.py:18-27 (registration)Registration function that decorates the fetch_spec_tool as an @mcp.tool with annotations including title, readOnlyHint, and description. Also registers the companion check_spec_health tool.
def register_fetch_spec_tool(mcp: FastMCP) -> None: """Register the fetch specification tool with the FastMCP server.""" @mcp.tool( annotations={ "title": "Fetch Ilograph Specification", "readOnlyHint": True, "description": "Fetches the concise Ilograph specification with property definitions and types", } ) - src/ilograph_mcp/server.py:64-65 (registration)Server-level registration: calls register_fetch_spec_tool(mcp) to register the tool on the FastMCP server.
register_fetch_spec_tool(mcp) logger.info("Registered fetch_spec_tool") - The fetch_specification method on IlographContentFetcher, which performs the actual HTTP fetch of the spec HTML, converts it to markdown, and caches the result with a 24-hour TTL.
async def fetch_specification(self) -> Optional[str]: """ Fetch and parse the Ilograph specification with caching. Returns: Specification content as markdown or None if unavailable """ cache_key = "specification" # Check cache first cached_content = self.cache.get(cache_key) if cached_content is not None: logger.debug("Returning cached specification") return str(cached_content) try: logger.info("Fetching Ilograph specification") # Fetch HTML content html_content = await self.http_client.fetch_specification_html() if html_content is None: logger.error("Failed to fetch specification HTML") return None # Convert to markdown markdown_content = self.markdown_converter.convert_html_to_markdown( html_content, self.http_client.base_urls["spec"] ) # Cache the result self.cache.set(cache_key, markdown_content, self.cache_ttl["specification"]) logger.info("Successfully processed specification") return markdown_content except Exception as e: logger.error(f"Error fetching specification: {e}") return None - The fetch_specification_html method on IlographHTTPClient, which performs the HTTP GET request to https://www.ilograph.com/docs/spec/ with retry logic.
async def fetch_specification_html(self) -> Optional[str]: """ Fetch HTML content for the Ilograph specification. Returns: HTML content as string if successful, None otherwise """ response = await self.fetch_with_retry(self.base_urls["spec"]) if response is None: return None try: return response.text except Exception as e: logger.error(f"Error reading specification response text: {e}") return None