List Registered Servers

Instructions

Implementation Reference

• src/app.ts:707-726 (registration)

  Registration of the 'list_servers' tool with the MCP server, including title, description, inputSchema, annotations, and handler callback.

  server.registerTool(
    'list_servers',
    {
      title: 'List Registered Servers',
      description: 'List all registered MCP servers with their current status.',
      inputSchema: ListServersSchema,
      annotations: {
        readOnlyHint: true,
        destructiveHint: false,
        openWorldHint: false
      }
    },
    async (input: ListServersInput) => {
      const servers = listServers(input);
      return formatResponse({
        count: servers.length,
        servers
      });
    }
  );

• src/registry.ts:185-240 (handler)

  Core handler function `listServers` that queries the SQLite database using a CTE to fetch servers with latest health check info and 24h uptime percentage, then filters by optional tags and status.

  export function listServers(options: ListServersInput): ServerStatus[] {
    const since24Hours = Date.now() - 24 * 60 * 60 * 1000;
    const rows = getDb()
      .prepare(
        `
          WITH latest_checks AS (
            SELECT
              server_name,
              tool_count,
              ROW_NUMBER() OVER (
                PARTITION BY server_name
                ORDER BY timestamp DESC, id DESC
              ) AS row_number
            FROM health_checks
          ),
          uptime_24h AS (
            SELECT
              server_name,
              CAST(ROUND(100.0 * SUM(CASE WHEN status = 'up' THEN 1 ELSE 0 END) / COUNT(*)) AS INTEGER) AS uptime_24h_percent
            FROM health_checks
            WHERE timestamp > ?
            GROUP BY server_name
          )
          SELECT
            s.*,
            latest_checks.tool_count AS latest_tool_count,
            uptime_24h.uptime_24h_percent
          FROM servers s
          LEFT JOIN latest_checks
            ON latest_checks.server_name = s.name
           AND latest_checks.row_number = 1
          LEFT JOIN uptime_24h
            ON uptime_24h.server_name = s.name
          ORDER BY s.name ASC
        `
      )
      .all(since24Hours) as ListServerRow[];
  
    return rows
      .filter((row) => {
        if (!options.tags?.length) {
          return true;
        }
  
        const tags = parseJsonArray(row.tags);
        return options.tags.some((tag: string) => tags.includes(tag));
      })
      .map(buildServerStatus)
      .filter((serverStatus) => {
        if (!options.status) {
          return true;
        }
  
        return serverStatus.status === options.status;
      });
  }

• src/types.ts:73-76 (schema)

  Zod schema `ListServersSchema` defining input validation: optional `tags` (array of strings) and optional `status` (one of 'up', 'down', 'unknown').

  export const ListServersSchema = z.object({
    tags: z.array(z.string()).optional(),
    status: ListableStatusSchema.optional()
  });

• src/registry.ts:71-93 (helper)

  Helper function `buildServerStatus` that maps a database row to the `ServerStatus` interface, including optional url/command fields.

  function buildServerStatus(row: ListServerRow): ServerStatus {
    const status: ServerStatus = {
      name: row.name,
      type: row.type,
      status: mapStatus(row.last_status),
      last_checked: row.last_checked,
      last_response_time_ms: row.last_response_time_ms,
      tool_count: row.latest_tool_count,
      uptime_24h_percent: row.uptime_24h_percent,
      consecutive_failures: row.consecutive_failures ?? 0,
      tags: parseJsonArray(row.tags)
    };
  
    if (row.url) {
      status.url = row.url;
    }
  
    if (row.command) {
      status.command = row.command;
    }
  
    return status;
  }