Complete agent rating system with UI, CLI, and API documentation (#275)

* Add API endpoints for agent rating and user tracking #226

* add rate agent

* Add agent rating system with CLI support and API documentation

- Add rating API endpoints (POST /api/agents/{path}/rate, GET /api/agents/{path}/rating)
- Implement rotating buffer for last 100 ratings
- Add CLI commands: agent-rate and agent-rating
- Update Pydantic models to support float ratings (num_stars: int -> float)
- Fix registry_client to send JSON for all agent endpoints
- Fix token file parsing to extract access_token from JSON
- Update OpenAPI spec with rating endpoints and schemas
- Change num_stars from integer to float in AgentCard and AgentInfo models

* Add interactive star rating UI component

- Create StarRatingWidget component with dropdown interaction
- Implement click-to-rate functionality with 5-star selection
- Add hover preview and visual feedback
- Support rating submission and updates
- Show success/loading states with animations
- Integrate with AgentCard to replace static rating display
- Auto-close dropdown after successful submission
- Handle outside-click to close dropdown
- Full keyboard navigation support (planned)
- Mobile-responsive design with touch-friendly targets

* Fix rating count display to use rating_details.length

- Changed initialCount from usersCount to rating_details.length
- Added rating_details to Agent interface TypeScript definition
- This ensures rating count matches actual number of ratings

* Update README with agent rating system in What's New section

---------

Co-authored-by: Ubuntu <ubuntu@ip-172-31-27-29.us-east-2.compute.internal>

Author: aarora79

README.md

@@ -129,6 +129,7 @@ Interactive terminal interface for chatting with AI models and discovering MCP t
 
 ## What's New
 
+- **⭐ Agent Rating System** - Rate and review agents with an interactive 5-star rating widget. Users can submit ratings via the UI or CLI, view aggregate ratings with individual rating details, and update their existing ratings. Features include a rotating buffer (max 100 ratings per agent), one rating per user, float average calculations, and full OpenAPI documentation. Enables community-driven agent quality assessment and discovery.
 - **🧠 Flexible Embeddings Support** - Choose from three embedding provider options for semantic search: local sentence-transformers, OpenAI, or any LiteLLM-supported provider including Amazon Bedrock Titan, Cohere, and 100+ other models. Switch providers with simple configuration changes. [Embeddings Guide](docs/embeddings.md)
 - **☁️ AWS ECS Production Deployment** - Production-ready deployment on Amazon ECS Fargate with multi-AZ architecture, Application Load Balancer with HTTPS, auto-scaling, CloudWatch monitoring, and NAT Gateway high availability. Complete Terraform configuration for deploying the entire stack. [ECS Deployment Guide](terraform/aws-ecs/README.md)
 - **Federated Registry** - MCP Gateway registry now supports federation of servers and agents from other registries. [Federation Guide](docs/federation.md)

api/registry_client.py

@@ -417,6 +417,33 @@ class AgentSemanticDiscoveryResponse(BaseModel):
     agents: List[SemanticDiscoveredAgent] = Field(..., description="Semantically discovered agents")
 
 
+class RatingDetail(BaseModel):
+    """Individual rating detail."""
+
+    user: str = Field(..., description="Username who submitted the rating")
+    rating: int = Field(..., ge=1, le=5, description="Rating value (1-5 stars)")
+
+
+class RatingRequest(BaseModel):
+    """Rating submission request."""
+
+    rating: int = Field(..., ge=1, le=5, description="Rating value (1-5 stars)")
+
+
+class RatingResponse(BaseModel):
+    """Rating submission response."""
+
+    message: str = Field(..., description="Success message")
+    average_rating: float = Field(..., ge=1.0, le=5.0, description="Updated average rating")
+
+
+class RatingInfoResponse(BaseModel):
+    """Rating information response."""
+
+    num_stars: float = Field(..., ge=0.0, le=5.0, description="Average rating (0.0 if no ratings)")
+    rating_details: List[RatingDetail] = Field(..., description="Individual ratings (max 100)")
+
+
 # Anthropic Registry API Models (v0.1)
 
 
@@ -588,9 +615,9 @@ def _make_request(
         logger.debug(f"{method} {url}")
 
         # Determine content type based on endpoint
-        # Agent registration uses JSON, server registration uses form data
-        if endpoint == "/api/agents/register":
-            # Send as JSON for agent registration
+        # Agent endpoints use JSON, server registration uses form data
+        if endpoint.startswith("/api/agents"):
+            # Send as JSON for all agent endpoints
             response = requests.request(
                 method=method,
                 url=url,
@@ -1169,6 +1196,74 @@ def discover_agents_semantic(
         logger.info(f"Discovered {len(result.agents)} agents via semantic search")
         return result
 
+
+    def rate_agent(
+        self,
+        path: str,
+        rating: int
+    ) -> RatingResponse:
+        """
+        Submit a rating for an agent (1-5 stars).
+
+        Each user can only have one active rating. If user has already rated,
+        this updates their existing rating. System maintains a rotating buffer
+        of the last 100 ratings.
+
+        Args:
+            path: Agent path (e.g., /code-reviewer)
+            rating: Rating value (1-5 stars)
+
+        Returns:
+            Rating response with success message and updated average rating
+
+        Raises:
+            requests.HTTPError: If rating fails (400 for invalid rating, 403 for unauthorized, 404 for not found)
+        """
+        logger.info(f"Rating agent '{path}' with {rating} stars")
+
+        request_data = RatingRequest(rating=rating)
+
+        response = self._make_request(
+            method="POST",
+            endpoint=f"/api/agents{path}/rate",
+            data=request_data.model_dump()
+        )
+
+        result = RatingResponse(**response.json())
+        logger.info(f"Agent '{path}' rated successfully. New average: {result.average_rating:.2f}")
+        return result
+
+
+    def get_agent_rating(
+        self,
+        path: str
+    ) -> RatingInfoResponse:
+        """
+        Get rating information for an agent.
+
+        Returns average rating and up to 100 most recent individual ratings
+        (maintained as rotating buffer).
+
+        Args:
+            path: Agent path (e.g., /code-reviewer)
+
+        Returns:
+            Rating information with average and individual ratings
+
+        Raises:
+            requests.HTTPError: If retrieval fails (403 for unauthorized, 404 for not found)
+        """
+        logger.info(f"Getting ratings for agent: {path}")
+
+        response = self._make_request(
+            method="GET",
+            endpoint=f"/api/agents{path}/rating"
+        )
+
+        result = RatingInfoResponse(**response.json())
+        logger.info(f"Retrieved ratings for '{path}': {result.num_stars:.2f} stars ({len(result.rating_details)} ratings)")
+        return result
+
     # Anthropic Registry API Methods (v0.1)
 
     def anthropic_list_servers(

api/registry_management.py

@@ -44,6 +44,12 @@
     # Delete agent
     uv run python registry_management.py agent-delete --path /code-reviewer
 
+    # Rate an agent (1-5 stars)
+    uv run python registry_management.py agent-rate --path /code-reviewer --rating 5
+
+    # Get agent rating information
+    uv run python registry_management.py agent-rating --path /code-reviewer
+
     # Discover agents by skills
     uv run python registry_management.py agent-discover --skills code_analysis,bug_detection
 
@@ -103,6 +109,8 @@
     AgentToggleResponse,
     AgentDiscoveryResponse,
     AgentSemanticDiscoveryResponse,
+    RatingResponse,
+    RatingInfoResponse,
     AnthropicServerList,
     AnthropicServerResponse,
 )
@@ -277,7 +285,18 @@ def _create_client(
             raise FileNotFoundError(f"Token file not found: {args.token_file}")
 
         logger.debug(f"Loading token from file: {args.token_file}")
-        token = token_path.read_text().strip()
+
+        # Try to parse as JSON first (token files from generate-agent-token.sh)
+        try:
+            with open(token_path, 'r') as f:
+                token_data = json.load(f)
+            # Extract access_token from JSON structure
+            token = token_data.get('access_token')
+            if not token:
+                raise RuntimeError(f"No 'access_token' field found in token file: {args.token_file}")
+        except json.JSONDecodeError:
+            # Fall back to plain text token file
+            token = token_path.read_text().strip()
 
         if not token:
             raise RuntimeError(f"Empty token in file: {args.token_file}")
@@ -1030,6 +1049,67 @@ def cmd_agent_search(args: argparse.Namespace) -> int:
         return 1
 
 
+def cmd_agent_rate(args: argparse.Namespace) -> int:
+    """
+    Rate an agent (1-5 stars).
+
+    Args:
+        args: Command arguments with path and rating
+
+    Returns:
+        Exit code (0 for success, 1 for failure)
+    """
+    try:
+        client = _create_client(args)
+        response: RatingResponse = client.rate_agent(
+            path=args.path,
+            rating=args.rating
+        )
+
+        logger.info(f"✓ {response.message}")
+        logger.info(f"Average rating: {response.average_rating:.2f} stars")
+
+        return 0
+
+    except Exception as e:
+        logger.error(f"Failed to rate agent: {e}")
+        return 1
+
+
+def cmd_agent_rating(args: argparse.Namespace) -> int:
+    """
+    Get rating information for an agent.
+
+    Args:
+        args: Command arguments with path
+
+    Returns:
+        Exit code (0 for success, 1 for failure)
+    """
+    try:
+        client = _create_client(args)
+        response: RatingInfoResponse = client.get_agent_rating(path=args.path)
+
+        logger.info(f"\nRating for agent '{args.path}':")
+        logger.info(f"  Average: {response.num_stars:.2f} stars")
+        logger.info(f"  Total ratings: {len(response.rating_details)}")
+
+        if response.rating_details:
+            logger.info("\nIndividual ratings (most recent):")
+            # Show first 10 ratings
+            for detail in response.rating_details[:10]:
+                logger.info(f"  {detail.user}: {detail.rating} stars")
+
+            if len(response.rating_details) > 10:
+                logger.info(f"  ... and {len(response.rating_details) - 10} more")
+
+        return 0
+
+    except Exception as e:
+        logger.error(f"Failed to get ratings: {e}")
+        return 1
+
+
 def cmd_anthropic_list_servers(args: argparse.Namespace) -> int:
     """
     List all servers using Anthropic Registry API v0.1.
@@ -1480,6 +1560,29 @@ def main() -> int:
         help="Maximum number of results (default: 10)"
     )
 
+    # Agent rate command
+    agent_rate_parser = subparsers.add_parser("agent-rate", help="Rate an agent (1-5 stars)")
+    agent_rate_parser.add_argument(
+        "--path",
+        required=True,
+        help="Agent path (e.g., /code-reviewer)"
+    )
+    agent_rate_parser.add_argument(
+        "--rating",
+        required=True,
+        type=int,
+        choices=[1, 2, 3, 4, 5],
+        help="Rating value (1-5 stars)"
+    )
+
+    # Agent rating command
+    agent_rating_parser = subparsers.add_parser("agent-rating", help="Get rating information for an agent")
+    agent_rating_parser.add_argument(
+        "--path",
+        required=True,
+        help="Agent path (e.g., /code-reviewer)"
+    )
+
     # Anthropic Registry API Commands
 
     # Anthropic list servers command
@@ -1565,6 +1668,8 @@ def main() -> int:
         "agent-toggle": cmd_agent_toggle,
         "agent-discover": cmd_agent_discover,
         "agent-search": cmd_agent_search,
+        "agent-rate": cmd_agent_rate,
+        "agent-rating": cmd_agent_rating,
         "anthropic-list": cmd_anthropic_list_servers,
         "anthropic-versions": cmd_anthropic_list_versions,
         "anthropic-get": cmd_anthropic_get_server