ssh-mcp

Instructions

Implementation Reference

• src/ssh_mcp/server.py:156-177 (handler)

  The list_groups() async function is the main handler for the 'list_groups' tool. It initializes the registry, retrieves all groups using _registry.all_groups(), counts servers per group, and returns formatted output using format_group_table().

  async def list_groups() -> str:
      """List all server groups with descriptions and member counts.
  
      Returns:
          Formatted table of groups with name, description, and server count.
      """
      try:
          _init()
  
          groups = _registry.all_groups()
  
          # Count servers per group
          server_counts = {}
          for group in groups:
              count = len(_registry.servers_in_group(group.name))
              server_counts[group.name] = count
  
          return format_group_table(groups, server_counts)
  
      except Exception as e:
          logger.error(f"Error listing groups: {e}")
          return f"Error listing groups: {e}"

• src/ssh_mcp/server.py:155-155 (registration)

  The @mcp.tool() decorator registers the list_groups function as an MCP tool with FastMCP server.

  @mcp.tool()

• src/ssh_mcp/models.py:32-43 (schema)

  The GroupConfig dataclass defines the schema for group data with 'name' and 'description' fields. It's frozen for immutability.

  class GroupConfig:
      """Configuration for a logical server group.
  
      Groups allow organizing servers by environment, function, or team.
  
      Attributes:
          name: Unique group identifier
          description: Human-readable description of the group's purpose
      """
  
      name: str
      description: str

• src/ssh_mcp/config.py:112-118 (helper)

  The all_groups() method in ServerRegistry retrieves all configured groups from the registry as a list of GroupConfig objects.

  def all_groups(self) -> list[GroupConfig]:
      """Get all configured groups.
  
      Returns:
          List of all GroupConfig objects
      """
      return list(self._groups.values())

• src/ssh_mcp/formatting.py:63-101 (helper)

  The format_group_table() function formats a list of groups with their server counts into a human-readable text table for display.

  def format_group_table(groups: list[GroupConfig], server_counts: dict[str, int]) -> str:
      """Format a list of groups into a text table.
  
      Args:
          groups: List of group configurations to display
          server_counts: Mapping of group name to number of servers in that group
  
      Returns:
          Formatted text table with columns: GROUP, SERVERS, DESCRIPTION
  
      Example:
          >>> groups = [GroupConfig(name="prod", description="Production servers")]
          >>> counts = {"prod": 5}
          >>> print(format_group_table(groups, counts))
          GROUP  SERVERS  DESCRIPTION
          prod   5        Production servers
      """
      if not groups:
          return "No groups found."
  
      # Calculate column widths
      max_name = max(len("GROUP"), max(len(g.name) for g in groups))
      max_count = max(
          len("SERVERS"), max(len(str(server_counts.get(g.name, 0))) for g in groups)
      )
  
      # Build header
      lines = [
          f"{'GROUP':<{max_name}}  {'SERVERS':<{max_count}}  DESCRIPTION",
      ]
  
      # Build rows
      for group in groups:
          count = server_counts.get(group.name, 0)
          lines.append(
              f"{group.name:<{max_name}}  {count:<{max_count}}  {group.description}"
          )
  
      return "\n".join(lines)