EVE-NG MCP Server

Instructions

Implementation Reference

• eveng_mcp_server/tools/node_management.py:137-189 (handler)

  The MCP tool handler for 'list_nodes'. Takes lab_path, calls eveng_client.list_nodes(), formats output as formatted text with status icons and details.

  async def list_nodes(arguments: ListNodesArgs) -> list[TextContent]:
      """
      List all nodes in a lab.
  
      This tool retrieves information about all nodes in the specified lab,
      including their status, configuration, and connectivity.
      """
      try:
          logger.info(f"Listing nodes in lab: {arguments.lab_path}")
  
          if not eveng_client.is_connected:
              return [TextContent(
                  type="text",
                  text="Not connected to EVE-NG server. Use connect_eveng_server tool first."
              )]
  
          # Get nodes
          nodes = await eveng_client.list_nodes(arguments.lab_path)
  
          if not nodes.get('data'):
              return [TextContent(
                  type="text",
                  text=f"No nodes found in lab: {arguments.lab_path}"
              )]
  
          # Format nodes information
          nodes_text = f"Nodes in {arguments.lab_path}:\n\n"
  
          for node_id, node in nodes['data'].items():
              status_icon = "🟢" if node.get('status') == 2 else "🔴" if node.get('status') == 1 else "⚪"
              nodes_text += f"{status_icon} {node.get('name', f'Node {node_id}')} (ID: {node_id})\n"
              nodes_text += f"   Template: {node.get('template', 'Unknown')}\n"
              nodes_text += f"   Type: {node.get('type', 'Unknown')}\n"
              nodes_text += f"   Image: {node.get('image', 'Unknown')}\n"
              nodes_text += f"   Status: {_get_status_text(node.get('status', 0))}\n"
              nodes_text += f"   Console: {node.get('console', 'Unknown')}\n"
              nodes_text += f"   CPU: {node.get('cpu', 'Unknown')}\n"
              nodes_text += f"   RAM: {node.get('ram', 'Unknown')} MB\n"
              nodes_text += f"   Position: ({node.get('left', 0)}%, {node.get('top', 0)}%)\n"
              nodes_text += "\n"
  
          return [TextContent(
              type="text",
              text=nodes_text
          )]
  
      except Exception as e:
          logger.error(f"Failed to list nodes: {e}")
          return [TextContent(
              type="text",
              text=f"Failed to list nodes: {str(e)}"
          )]

• eveng_mcp_server/tools/node_management.py:30-33 (schema)

  Pydantic input schema for the list_nodes tool, defining the required lab_path parameter.

  class ListNodesArgs(BaseModel):
      """Arguments for list_nodes tool."""
      lab_path: str = Field(description="Full path to the lab (e.g., /lab_name.unl)")

• eveng_mcp_server/server.py:52-54 (registration)

  Top-level registration of all tools, including node_management tools containing list_nodes, in the main EVENGMCPServer class.

  # Register tools
  register_tools(self.mcp, self.eveng_client)

• eveng_mcp_server/tools/__init__.py:24-28 (registration)

  Registration of node management tools (including list_nodes handler) via register_node_tools call within the overall register_tools function.

  # Node management tools
  register_node_tools(mcp, eveng_client)
  
  # Network management tools
  register_network_tools(mcp, eveng_client)

• eveng_mcp_server/core/eveng_client.py:343-353 (helper)

  Helper method in EVENGClientWrapper that calls the underlying EVE-NG API to list nodes in a lab and handles errors.

  async def list_nodes(self, lab_path: str) -> Dict[str, Any]:
      """List all nodes in a lab."""
      await self.ensure_connected()
  
      try:
          nodes = await asyncio.to_thread(self.api.list_nodes, lab_path)
          self.logger.debug("Listed nodes", lab_path=lab_path)
          return nodes
      except Exception as e:
          self.logger.error("Failed to list nodes", **log_error(e, {"lab_path": lab_path}))
          raise EVENGAPIError(f"Failed to list nodes: {str(e)}")