Skip to content

[FEATURE][UI]: Add search capabilities for tools in admin UI #2076

Closed
Feature
#2868
Closed
[FEATURE][UI]: Add search capabilities for tools in admin UI#2076
Feature
#2868
Assignees
crivetimihai
Labels
MUSTP1: Non-negotiable, critical requirements without which the product is non-functional or unsafeenhancementNew feature or requesticaICA related issuesuiUser Interface
Milestone
Release 1.0.0-RC1
@crivetimihai

Description

@crivetimihai
crivetimihai
opened on Jan 13, 2026

🔍 Feature: Add Search Capabilities for Tools in Admin UI

Parent Epic: #2109 - Unified Search Experience for MCP Gateway Admin UI

Goal

Provide a fast, consistent search experience for tools in the Admin UI that supports text search, tag filtering, and faceted refinement. Handle large tool sets (1000+) without client-side performance degradation.

Why Now?

  1. Scale: Deployments are growing to hundreds or thousands of tools, making manual scrolling impractical
  2. Backend Exists: /admin/tools/search endpoint already exists but lacks frontend integration
  3. UX Consistency: Other sections need similar search; tools can serve as the reference implementation
  4. Discoverability: Users need to quickly find tools by name, description, gateway, or tags

📖 User Stories

US-1: Admin - Search Tools by Name or Description

As an Admin User with 500+ tools
I want to search tools by typing in a search box
So that I can quickly find the tool I need without scrolling

Acceptance Criteria:

Scenario: Search by tool name
  Given I am on the Tools page in Admin UI
  And there are 500 tools registered
  When I type "github" in the search box
  And I wait 300ms for debounce
  Then I should see only tools with "github" in their name or description
  And the results should update without full page reload
  And the count should show "Showing 12 of 500"

Scenario: Clear search returns all tools
  Given I have searched for "github" with 12 results showing
  When I click the clear button (X)
  Then all tools should be displayed again
  And the search box should be empty

Scenario: No results found
  Given I search for "nonexistent_tool_xyz"
  When the search completes
  Then I should see "No tools found matching 'nonexistent_tool_xyz'"
  And a "Clear search" link should be displayed

Technical Requirements:

  • Debounced search (300ms) to reduce API calls
  • HTMX partial update (no full page reload)
  • Case-insensitive search on name, original_name, description
  • Show result count
US-2: Admin - Filter Tools by Gateway

As an Admin User
I want to filter tools by their source gateway
So that I can see only tools from a specific MCP server

Acceptance Criteria:

Scenario: Filter by single gateway
  Given tools from gateways "github-mcp", "slack-mcp", and REST tools
  When I select "github-mcp" from the gateway filter dropdown
  Then only tools from "github-mcp" should be displayed
  And the URL should update to include "?gateway_id=abc123"

Scenario: Filter REST-only tools
  Given some tools have no gateway (REST tools)
  When I select "REST Tools (No Gateway)" from the filter
  Then only tools with gateway_id=null should be displayed

Scenario: Combine search with gateway filter
  Given I have filtered to "github-mcp" gateway
  When I search for "issue"
  Then only tools from github-mcp containing "issue" should appear

Technical Requirements:

  • Gateway dropdown populated from existing gateways
  • Support "null" sentinel for REST tools
  • Combine with text search using AND logic
US-3: Admin - Filter Tools by Tags

As an Admin User
I want to filter tools by tags
So that I can find tools in specific categories like "production" or "deprecated"

Acceptance Criteria:

Scenario: Filter by single tag
  Given tools have tags like ["production", "experimental", "deprecated"]
  When I add "production" to the tag filter
  Then only tools tagged "production" should appear

Scenario: Filter by multiple tags (OR logic)
  Given I want to see production OR staging tools
  When I enter tags "production,staging" (comma-separated)
  Then tools with either tag should appear

Scenario: Filter by multiple tags (AND logic)
  Given I want tools that are both "production" AND "api"
  When I enter tags "production+api" (plus-separated)
  Then only tools with BOTH tags should appear

Scenario: Tag autocomplete
  Given existing tags in the system
  When I start typing "prod" in the tag filter
  Then I should see autocomplete suggestions including "production"

Technical Requirements:

  • Add tags parameter to /admin/tools/search endpoint
  • Use existing json_contains_expr() helper for tag matching
  • Support comma (OR) and plus (AND) separators
  • Autocomplete from existing tags
US-4: Admin - Filter by Visibility and Status

As an Admin User
I want to filter tools by visibility and active status
So that I can find public tools or see disabled tools

Acceptance Criteria:

Scenario: Show only active tools (default)
  Given there are 100 active and 20 inactive tools
  When I load the Tools page without filters
  Then only the 100 active tools should be shown
  And "Include inactive" checkbox should be unchecked

Scenario: Include inactive tools
  Given some tools are disabled
  When I check "Include inactive" checkbox
  Then both active and inactive tools should appear
  And inactive tools should have a visual indicator (gray/strikethrough)

Scenario: Filter by visibility
  Given tools with visibility public, team, and private
  When I select "Public" from visibility filter
  Then only public tools should be displayed
US-5: Admin - Persist Search State in URL

As an Admin User
I want my search filters to be preserved in the URL
So that I can bookmark or share filtered views

Acceptance Criteria:

Scenario: URL reflects current filters
  Given I search for "api" with gateway "github-mcp" and tag "production"
  Then the URL should be:
    "/admin#tools?q=api&gateway_id=abc123&tags=production"

Scenario: Load page with URL parameters
  Given I navigate to "/admin#tools?q=api&tags=production"
  When the page loads
  Then the search box should contain "api"
  And the tag filter should show "production"
  And results should be filtered accordingly

Scenario: Browser back button works
  Given I perform several searches
  When I click the browser back button
  Then I should return to my previous search state

🏗 Architecture

Search Flow

sequenceDiagram
    participant User
    participant UI as Admin UI (Alpine.js)
    participant HTMX
    participant API as /admin/tools/search
    participant DB as Database

    User->>UI: Types "github" in search
    UI->>UI: Debounce 300ms
    UI->>HTMX: Trigger search
    HTMX->>API: GET /admin/tools/search?q=github&limit=50
    API->>DB: SELECT * FROM tools WHERE name ILIKE '%github%'
    DB-->>API: Matching tools
    API-->>HTMX: HTML partial with results
    HTMX->>UI: Swap results container
    UI->>UI: Update URL with search params
Loading

Frontend Component Structure

// Alpine.js component in admin.js
function toolSearchComponent() {
    return {
        query: '',
        gateway_id: '',
        tags: '',
        visibility: '',
        include_inactive: false,
        
        init() {
            // Load state from URL params
            this.loadFromUrl();
        },
        
        search() {
            // Debounced search via HTMX
            htmx.trigger('#tools-search-form', 'submit');
            this.updateUrl();
        },
        
        updateUrl() {
            const params = new URLSearchParams();
            if (this.query) params.set('q', this.query);
            if (this.gateway_id) params.set('gateway_id', this.gateway_id);
            // ... etc
            history.replaceState(null, '', `#tools?${params}`);
        }
    }
}

📋 Implementation Tasks

Phase 1: Backend Enhancement

  • Add tags parameter to /admin/tools/search endpoint
  • Implement tag filtering using json_contains_expr() helper
  • Support comma (OR) and plus (AND) tag separators
  • Add visibility parameter to filter by public/team/private
  • Ensure consistent response format: {"tools": [...], "count": N}

Phase 2: Search Bar UI

  • Add search input with placeholder "Search tools by name, description..."
  • Add clear button (X) to reset search
  • Implement 300ms debounce using Alpine.js
  • Show loading spinner during search
  • Display result count "Showing X of Y"

Phase 3: Faceted Filters

  • Add gateway dropdown filter (populated from /gateways)
  • Add "REST Tools (No Gateway)" option
  • Add tag input with autocomplete
  • Add visibility dropdown (All, Public, Team, Private)
  • Add "Include inactive" checkbox

Phase 4: HTMX Integration

  • Create tools search form with HTMX attributes
  • Create tools_search_results.html partial template
  • Wire up form submission to partial update
  • Handle empty results state

Phase 5: URL State Management

  • Read filter state from URL on page load
  • Update URL when filters change (history.replaceState)
  • Support browser back/forward navigation
  • Encode special characters properly

Phase 6: Testing

  • Unit tests for tag filtering logic
  • Playwright tests for search interaction
  • Playwright tests for filter combinations
  • Playwright tests for URL state persistence
  • Performance test with 1000+ tools

⚙️ Configuration

No new configuration required. Uses existing settings:

  • Existing /admin/tools/search endpoint
  • Existing json_contains_expr() helper for tag matching

✅ Success Criteria

  • Users can search tools by name/description with 300ms debounce
  • Results update without full page reload (HTMX partial)
  • Gateway filter works including "REST Tools (No Gateway)"
  • Tag filtering supports OR (comma) and AND (plus) logic
  • Visibility and status filters work correctly
  • URL reflects current filter state
  • Page loads with filters from URL parameters
  • Works smoothly with 1000+ tools
  • Playwright tests pass for all scenarios

🏁 Definition of Done

  • Backend endpoint enhanced with tag/visibility filters
  • Search bar with debounce implemented
  • All faceted filters working
  • HTMX partial updates working
  • URL state management working
  • Playwright tests written and passing
  • Code passes make verify
  • PR reviewed and approved

🔗 Related Issues

Metadata

Metadata

Assignees

Labels

MUSTP1: Non-negotiable, critical requirements without which the product is non-functional or unsafeenhancementNew feature or requesticaICA related issuesuiUser Interface

Type

Feature

Projects

No projects

Milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions