Diagrams MCP Server

Instructions

Implementation Reference

• src/diagrams_mcp/tools/core.py:573-589 (registration)

  Registers the 'list_available_nodes' tool with the MCP server, defining its name, description, input parameters schema via type hints, and annotations.

  @mcp.tool(
      name="list_available_nodes",
      description="""Discover 500+ node types across providers.
  
  ⚠️ USE THIS FIRST before create_diagram to avoid invalid node errors.
  
  Filters: provider, category, search_term
  
  Examples:
  AWS compute: provider="aws", category="compute" → EC2, Lambda, ECS, EKS...
  Search DBs: search_term="db" → RDS, DynamoDB, SQL across providers""",
      annotations={
          "readOnlyHint": True,
          "destructiveHint": False,
          "idempotentHint": True,
      },
  )

• src/diagrams_mcp/tools/core.py:590-620 (handler)

  The main handler function that implements the tool logic: accepts parameters, calls the search_nodes helper, formats the result using format_node_catalog, and handles errors.

  async def list_available_nodes(
      provider: Annotated[
          Optional[str], Field(description="Filter by provider (aws, azure, gcp, etc.)")
      ] = None,
      category: Annotated[
          Optional[str], Field(description="Filter by category (compute, database, etc.)")
      ] = None,
      search_term: Annotated[
          Optional[str], Field(description="Search term for node type names")
      ] = None,
      limit: Annotated[int, Field(description="Maximum results to return", ge=1, le=500)] = 100,
  ) -> str:
      """List available diagram node types."""
      try:
          # Search nodes
          nodes = search_nodes(
              provider=provider,
              category=category,
              search_term=search_term,
              limit=limit,
          )
  
          # Calculate total (for this implementation, returned = total due to limit)
          total_count = len(nodes)
          returned_count = len(nodes)
  
          return format_node_catalog(nodes, total_count, returned_count)
  
      except Exception as e:
          return format_error(f"Failed to list nodes: {str(e)}")

• src/diagrams_mcp/core/node_registry.py:328-380 (helper)

  Core helper function that performs the node discovery and filtering logic by dynamically introspecting the 'diagrams' library modules using importlib and inspect.

  def search_nodes(
      provider: Optional[str] = None,
      category: Optional[str] = None,
      search_term: Optional[str] = None,
      limit: int = 100,
  ) -> List[Dict[str, str]]:
      """Search for nodes matching criteria using dynamic discovery.
  
      Args:
          provider: Optional provider filter
          category: Optional category filter
          search_term: Optional search term for node type
          limit: Maximum number of results to return
  
      Returns:
          List of matching nodes with their information
      """
      # Get discovered nodes (cached after first call)
      all_nodes = _discover_all_nodes()
  
      results = []
  
      # Determine which providers to search
      providers_to_search = [provider] if provider else all_nodes.keys()
  
      for prov in providers_to_search:
          if prov not in all_nodes:
              continue
  
          provider_nodes = all_nodes[prov]
  
          # Determine which categories to search
          categories_to_search = [category] if category else provider_nodes.keys()
  
          for cat in categories_to_search:
              if cat not in provider_nodes:
                  continue
  
              # Get nodes in this category
              nodes = provider_nodes[cat]
  
              for node in nodes:
                  # Apply search filter if provided
                  if search_term and search_term.lower() not in node.lower():
                      continue
  
                  node_info = get_node_info(prov, cat, node)
                  results.append(node_info)
  
                  if len(results) >= limit:
                      return results
  
      return results