visualize_graph
Create interactive visualizations of network data using GPU-accelerated rendering for graphs and hypergraphs to reveal connections and patterns.
Instructions
Visualize a graph using Graphistry's GPU-accelerated renderer.
Args:
graph_type (str, optional): Type of graph to visualize. Must be one of "graph" (two-way edges, default), "hypergraph" (many-to-many edges).
graph_data (dict): Dictionary describing the graph to visualize. Fields:
- edges (list, required): List of edges, each as a dict with at least 'source' and 'target' keys (e.g., [{"source": "A", "target": "B"}, ...]) and any other columns you want to include in the edge table
- nodes (list, optional): List of nodes, each as a dict with at least 'id' key (e.g., [{"id": "A"}, ...]) and any other columns you want to include in the node table
- node_id (str, optional): Column name for node IDs, if nodes are provided, must be provided.
- source (str, optional): Column name for edge source (default: "source")
- destination (str, optional): Column name for edge destination (default: "target")
- columns (list, optional): List of column names for hypergraph edge table, use if graph_type is hypergraph.
- title (str, optional): Title for the visualization
- description (str, optional): Description for the visualization
ctx: MCP context for progress reporting
Example (graph):
graph_data = {
"graph_type": "graph",
"edges": [
{"source": "A", "target": "B", "weight": 1},
{"source": "A", "target": "C", "weight": 2},
...
],
"nodes": [
{"id": "A", "label": "Node A"},
{"id": "B", "label": "Node B"},
...
],
"node_id": "id",
"source": "source",
"destination": "target",
"title": "My Graph",
"description": "A simple example graph."
}
Example (hypergraph):
graph_data = {
"graph_type": "hypergraph",
"edges": [
{"source": "A", "target": "B", "group": "G1", "weight": 1},
{"source": "A", "target": "C", "group": "G1", "weight": 1},
...
],
"columns": ["source", "target", "group"],
"title": "My Hypergraph",
"description": "A simple example hypergraph."
}Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| graph_data | Yes | ||
| ctx | No |
Implementation Reference
- The core handler function for the 'visualize_graph' tool. Decorated with @mcp.tool() for automatic registration in FastMCP. Parses graph_data (edges/nodes), creates Graphistry visualization object, caches it with a unique ID, and returns the graph_id and visualization URL.
@mcp.tool() async def visualize_graph(graph_data: Dict[str, Any], ctx: Optional[Context] = None) -> Dict[str, Any]: """ Visualize a graph using Graphistry's GPU-accelerated renderer. Args: graph_type (str, optional): Type of graph to visualize. Must be one of "graph" (two-way edges, default), "hypergraph" (many-to-many edges). graph_data (dict): Dictionary describing the graph to visualize. Fields: - edges (list, required): List of edges, each as a dict with at least 'source' and 'target' keys (e.g., [{"source": "A", "target": "B"}, ...]) and any other columns you want to include in the edge table - nodes (list, optional): List of nodes, each as a dict with at least 'id' key (e.g., [{"id": "A"}, ...]) and any other columns you want to include in the node table - node_id (str, optional): Column name for node IDs, if nodes are provided, must be provided. - source (str, optional): Column name for edge source (default: "source") - destination (str, optional): Column name for edge destination (default: "target") - columns (list, optional): List of column names for hypergraph edge table, use if graph_type is hypergraph. - title (str, optional): Title for the visualization - description (str, optional): Description for the visualization ctx: MCP context for progress reporting Example (graph): graph_data = { "graph_type": "graph", "edges": [ {"source": "A", "target": "B", "weight": 1}, {"source": "A", "target": "C", "weight": 2}, ... ], "nodes": [ {"id": "A", "label": "Node A"}, {"id": "B", "label": "Node B"}, ... ], "node_id": "id", "source": "source", "destination": "target", "title": "My Graph", "description": "A simple example graph." } Example (hypergraph): graph_data = { "graph_type": "hypergraph", "edges": [ {"source": "A", "target": "B", "group": "G1", "weight": 1}, {"source": "A", "target": "C", "group": "G1", "weight": 1}, ... ], "columns": ["source", "target", "group"], "title": "My Hypergraph", "description": "A simple example hypergraph." } """ try: if ctx: await ctx.info("Initializing graph visualization...") graph_type = graph_data.get("graph_type") or "graph" edges = graph_data.get("edges") nodes = graph_data.get("nodes") node_id = graph_data.get("node_id") source = graph_data.get("source") or "source" destination = graph_data.get("destination") or "target" title = graph_data.get("title") description = graph_data.get("description") columns = graph_data.get("columns", None) g = None edges_df = None nodes_df = None if graph_type == "graph": if not edges: raise ValueError("edges list required for edge_list format") edges_df = pd.DataFrame(edges) if nodes: nodes_df = pd.DataFrame(nodes) g = graphistry.edges(edges_df, source=source, destination=destination).nodes(nodes_df, node=node_id) else: g = graphistry.edges(edges_df, source=source, destination=destination) nx_graph = nx.from_pandas_edgelist(edges_df, source=source, target=destination) elif graph_type == "hypergraph": if not edges: raise ValueError("edges list required for hypergraph format") edges_df = pd.DataFrame(edges) g = graphistry.hypergraph(edges_df, columns)['graph'] nx_graph = None else: raise ValueError(f"Unsupported graph_type: {graph_type}") g = g.name(title) # Generate unique ID and cache graph_id = f"graph_{len(graph_cache)}" graph_cache[graph_id] = { "graph": g, "title": title, "description": description, "edges_df": edges_df, "nodes_df": nodes_df, "node_id": node_id, "source": source, "destination": destination, "nx_graph": nx_graph } if ctx: await ctx.info("Graph visualization complete!") return { "graph_id": graph_id, "title": title, "url": g.plot(render=False) } except Exception as e: logger.error(f"Error in visualize_graph: {e}") raise - src/graphistry_mcp_server/server.py:57-57 (registration)The @mcp.tool() decorator on visualize_graph registers it as an MCP tool named 'visualize_graph' (by function name convention).
@mcp.tool() - The function docstring provides detailed input schema validation description, including required 'graph_data' dict structure, graph_type options ('graph' or 'hypergraph'), edge/node formats, and examples.
""" Visualize a graph using Graphistry's GPU-accelerated renderer. Args: graph_type (str, optional): Type of graph to visualize. Must be one of "graph" (two-way edges, default), "hypergraph" (many-to-many edges). graph_data (dict): Dictionary describing the graph to visualize. Fields: - edges (list, required): List of edges, each as a dict with at least 'source' and 'target' keys (e.g., [{"source": "A", "target": "B"}, ...]) and any other columns you want to include in the edge table - nodes (list, optional): List of nodes, each as a dict with at least 'id' key (e.g., [{"id": "A"}, ...]) and any other columns you want to include in the node table - node_id (str, optional): Column name for node IDs, if nodes are provided, must be provided. - source (str, optional): Column name for edge source (default: "source") - destination (str, optional): Column name for edge destination (default: "target") - columns (list, optional): List of column names for hypergraph edge table, use if graph_type is hypergraph. - title (str, optional): Title for the visualization - description (str, optional): Description for the visualization ctx: MCP context for progress reporting Example (graph): graph_data = { "graph_type": "graph", "edges": [ {"source": "A", "target": "B", "weight": 1}, {"source": "A", "target": "C", "weight": 2}, ... ], "nodes": [ {"id": "A", "label": "Node A"}, {"id": "B", "label": "Node B"}, ... ], "node_id": "id", "source": "source", "destination": "target", "title": "My Graph", "description": "A simple example graph." } Example (hypergraph): graph_data = { "graph_type": "hypergraph", "edges": [ {"source": "A", "target": "B", "group": "G1", "weight": 1}, {"source": "A", "target": "C", "group": "G1", "weight": 1}, ... ], "columns": ["source", "target", "group"], "title": "My Hypergraph", "description": "A simple example hypergraph." } """