fixing error

Signed-off-by: IrushaBasukala <[email protected]>

Author: IrushaBasukala

MANIFEST.in

@@ -13,6 +13,7 @@ include Containerfile.lite
 include __init__
 include alembic.ini
 include tox.ini
+include alembic/README
 
 # 2️⃣  Top-level config, examples and helper scripts
 include *.py

mcpgateway/admin.py

@@ -3658,25 +3658,45 @@ async def admin_delete_root(uri: str, request: Request, user: str = Depends(requ
 
 #     # Return actual Pydantic model instances
 #     return {
-#         "tools": tool_metrics,          
+#         "tools": tool_metrics,
 #         "resources": resource_metrics,
 #         "servers": server_metrics,
 #         "prompts": prompt_metrics,
 #     }
 
+
 @admin_router.get("/metrics")
 async def get_aggregated_metrics(db: Session = Depends(get_db)) -> Dict[str, Any]:
+    """Retrieve aggregated metrics and top performers for all entity types.
+
+    This endpoint collects usage metrics and top-performing entities for tools,
+    resources, prompts, and servers by calling the respective service methods.
+    The results are compiled into a dictionary for administrative monitoring.
+
+    Args:
+        db (Session): Database session dependency for querying metrics.
+
+    Returns:
+        Dict[str, Any]: A dictionary containing aggregated metrics and top performers
+            for tools, resources, prompts, and servers. The structure includes:
+            - 'tools': Metrics for tools.
+            - 'resources': Metrics for resources.
+            - 'prompts': Metrics for prompts.
+            - 'servers': Metrics for servers.
+            - 'topPerformers': A nested dictionary with top 5 tools, resources, prompts,
+              and servers.
+    """
     metrics = {
-        "tools": await tool_service.aggregate_metrics(db),  
+        "tools": await tool_service.aggregate_metrics(db),
         "resources": await resource_service.aggregate_metrics(db),
         "prompts": await prompt_service.aggregate_metrics(db),
-        "servers": await server_service.aggregate_metrics(db),  
+        "servers": await server_service.aggregate_metrics(db),
         "topPerformers": {
             "tools": await tool_service.get_top_tools(db, limit=5),
             "resources": await resource_service.get_top_resources(db, limit=5),
             "prompts": await prompt_service.get_top_prompts(db, limit=5),
-            "servers": await server_service.get_top_servers(db, limit=5)
-        }
+            "servers": await server_service.get_top_servers(db, limit=5),
+        },
     }
     return metrics
 

mcpgateway/alembic/README.md

@@ -0,0 +1,172 @@
+# Alembic Migration Guide for `mcpgateway`
+
+> Creating, applying, and managing schema migrations with Alembic.
+
+---
+
+## Table of Contents
+
+1. [Why Alembic?](#why-alembic)
+2. [Prerequisites](#prerequisites)
+3. [Directory Layout](#directory-layout)
+4. [Everyday Workflow](#everyday-workflow)
+5. [Helpful Make Targets](#helpful-make-targets)
+6. [Troubleshooting](#troubleshooting)
+7. [Further Reading](#further-reading)
+
+---
+
+## Why Alembic?
+
+- **Versioned DDL** - Revisions are timestamped, diff-able, and reversible.
+- **Autogeneration** - Detects model vs. DB drift and writes `op.create_table`, `op.add_column`, etc.
+- **Multi-DB Support** - Works with SQLite, PostgreSQL, MySQL-anything SQLAlchemy supports.
+- **Zero Runtime Cost** - Only runs when you call it (dev, CI, deploy).
+
+---
+
+## Prerequisites
+
+```bash
+# Activate your virtual environment first
+pip install --upgrade alembic
+```
+
+You do not need to set up `alembic.ini`, `env.py`, or metadata wiring - they're already configured.
+
+---
+
+## Directory Layout
+
+```
+alembic.ini
+alembic/
+├── env.py
+├── script.py.mako
+└── versions/
+    ├── 20250626235501_initial_schema.py
+    └── ...
+```
+
+* `alembic.ini`: Configuration file
+* `env.py`: Connects Alembic to your models and DB settings
+* `script.py.mako`: Template for new revisions (keep this!)
+* `versions/`: Contains all migration scripts
+
+---
+
+## Everyday Workflow
+
+> **1 Edit → 2 Revision → 3 Upgrade**
+
+| Step                     | What you do                                                                   |
+| ------------------------ | ----------------------------------------------------------------------------- |
+| **1. Change models**     | Modify SQLAlchemy models in `mcpgateway.db` or its submodules.                |
+| **2. Generate revision** | Run: `MSG="add users table"` then `alembic revision --autogenerate -m "$MSG"` |
+| **3. Review**            | Open the new file in `alembic/versions/`. Verify the operations are correct.  |
+| **4. Upgrade DB**        | Run: `alembic upgrade head`                                                   |
+| **5. Commit**            | Run: `git add alembic/versions/*.py`                                          |
+
+### Other Common Commands
+
+```bash
+alembic -c mcpgateway/alembic.ini current             # Show current DB revision
+alembic history --verbose   # Show all migrations and their order
+alembic downgrade -1        # Roll back one revision
+alembic downgrade <rev>     # Roll back to a specific revision hash
+```
+
+---
+
+## ✅ Make Targets: Alembic Migration Commands
+
+These targets help you manage database schema migrations using Alembic.
+
+> You must have a valid `alembic/` setup and a working SQLAlchemy model base (`Base.metadata`).
+
+---
+
+### 💡 List all available targets (with help)
+
+```bash
+make help
+```
+
+This will include the Alembic section:
+
+```
+# 🛢️ Alembic tasks
+db-new        Autogenerate revision (MSG="title")
+db-up         Upgrade DB to head
+db-down       Downgrade one step (REV=-1 or hash)
+db-current    Show current DB revision
+db-history    List the migration graph
+```
+
+---
+
+### 🔨 Commands
+
+| Command                    | Description                                            |
+| -------------------------- | ------------------------------------------------------ |
+| `make db-new MSG="..."`    | Generate a new migration based on model changes.       |
+| `make db-up`               | Apply all unapplied migrations.                        |
+| `make db-down`             | Roll back the latest migration (`REV=-1` by default).  |
+| `make db-down REV=abc1234` | Roll back to a specific revision by hash.              |
+| `make db-current`          | Print the current revision ID applied to the database. |
+| `make db-history`          | Show the full migration history and graph.             |
+
+---
+
+### 📌 Examples
+
+```bash
+# Create a new migration with a custom message
+make db-new MSG="add users table"
+
+# Apply it to the database
+make db-up
+
+# Downgrade the last migration
+make db-down
+
+# Downgrade to a specific revision
+make db-down REV=cf1283d7fa92
+
+# Show the current applied revision
+make db-current
+
+# Show all migration history
+make db-history
+```
+
+---
+
+### 🛑 Notes
+
+* You must **edit models first** before `make db-new` generates anything useful.
+* Always **review generated migration files** before committing.
+* Don't forget to run `make db-up` on CI or deploy if using migrations to manage schema.
+
+---
+
+## Troubleshooting
+
+| Symptom                            | Cause / Fix                                                                                                                                           |
+| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Empty migration (`pass`)**       | Alembic couldn't detect models. Make sure all model classes are imported before `Base.metadata` is used (already handled in your `env.py`).           |
+| **`Can't locate revision ...`**    | You deleted or renamed a revision file that the DB is pointing to. Either restore it or run `alembic stamp base` and recreate the revision.           |
+| **`script.py.mako` missing**       | This file is required. Run `alembic init alembic` in a temp folder and copy the missing template into your project.                                   |
+| **SQLite foreign key limitations** | SQLite doesn't allow dropping constraints. Use `create table → copy → drop` flow manually, or plan around it.                                         |
+| **DB not updating**                | Did you forget to run `alembic upgrade head`? Check with `alembic -c mcpgateway/alembic.ini current`.                                                                           |
+| **Wrong DB URL or config errors**  | Confirm `settings.database_url` is valid. Check `env.py` and your `.env`/config settings. Alembic ignores `alembic.ini` for URLs in your setup.       |
+| **Model changes not detected**     | Alembic only picks up declarative models in `Base.metadata`. Ensure all models are imported and not behind `if TYPE_CHECKING:` or other lazy imports. |
+
+---
+
+## Further Reading
+
+* Official docs: [https://alembic.sqlalchemy.org](https://alembic.sqlalchemy.org)
+* Autogenerate docs: [https://alembic.sqlalchemy.org/en/latest/autogenerate.html](https://alembic.sqlalchemy.org/en/latest/autogenerate.html)
+
+---

mcpgateway/alembic/script.py.mako

@@ -0,0 +1,28 @@
+"""${message}
+
+Revision ID: ${up_revision}
+Revises: ${down_revision | comma,n}
+Create Date: ${create_date}
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+${imports if imports else ""}
+
+# revision identifiers, used by Alembic.
+revision: str = ${repr(up_revision)}
+down_revision: Union[str, Sequence[str], None] = ${repr(down_revision)}
+branch_labels: Union[str, Sequence[str], None] = ${repr(branch_labels)}
+depends_on: Union[str, Sequence[str], None] = ${repr(depends_on)}
+
+
+def upgrade() -> None:
+    """Upgrade schema."""
+    ${upgrades if upgrades else "pass"}
+
+
+def downgrade() -> None:
+    """Downgrade schema."""
+    ${downgrades if downgrades else "pass"}

mcpgateway/handlers/sampling.py

@@ -219,7 +219,7 @@ async def create_message(self, db: Session, request: Dict[str, Any]) -> CreateMe
             # TODO: Sample from selected model
             # For now return mock response
             response = self._mock_sample(messages=messages)
-    
+
             # Convert to result
             return CreateMessageResult(
                 content=TextContent(type="text", text=response),

mcpgateway/migrations/env.py

@@ -1,3 +1,8 @@
+"""Alembic environment configuration for database migrations.
+
+This module sets up the Alembic migration environment, configuring the database connection
+and metadata for running migrations in both online and offline modes.
+"""
 from logging.config import fileConfig
 
 from sqlalchemy import engine_from_config
@@ -73,6 +78,7 @@ def run_migrations_online() -> None:
 
 
 if context.is_offline_mode():
+
     run_migrations_offline()
 else:
     run_migrations_online()

mcpgateway/schemas.py

@@ -2571,10 +2571,22 @@ class GatewayTestResponse(BaseModelWithConfigDict):
 
 
 class TopPerformer(BaseModelWithConfigDict):
+    """Schema for representing top-performing entities with performance metrics.
+
+    Used to encapsulate metrics for entities such as prompts, resources, servers, or tools,
+    including execution count, average response time, success rate, and last execution timestamp.
+
+    Attributes:
+        id (Union[str, int]): Unique identifier for the entity.
+        name (str): Name of the entity (e.g., prompt name, resource URI, server name, or tool name).
+        execution_count (int): Total number of executions for the entity.
+        avg_response_time (Optional[float]): Average response time in seconds, or None if no metrics.
+        success_rate (Optional[float]): Success rate percentage, or None if no metrics.
+        last_execution (Optional[datetime]): Timestamp of the last execution, or None if no metrics.
+    """
     id: Union[str, int] = Field(..., description="Entity ID")
     name: str = Field(..., description="Entity name")
     execution_count: int = Field(..., description="Number of executions")
     avg_response_time: Optional[float] = Field(None, description="Average response time in seconds")
     success_rate: Optional[float] = Field(None, description="Success rate percentage")
     last_execution: Optional[datetime] = Field(None, description="Timestamp of last execution")
-

mcpgateway/services/gateway_service.py

@@ -176,9 +176,6 @@ class GatewayService:
     - Active/inactive status management
     """
 
-
-
-
     def __init__(self) -> None:
         """Initialize the gateway service.
 

mcpgateway/services/prompt_service.py

@@ -133,22 +133,41 @@ async def shutdown(self) -> None:
         self._event_subscribers.clear()
         logger.info("Prompt service shutdown complete")
 
-
     async def get_top_prompts(self, db: Session, limit: int = 5) -> List[TopPerformer]:
-        results = db.query(
-            DbPrompt.id,
-            DbPrompt.name,
-            func.count(PromptMetric.id).label('execution_count'),
-            func.avg(PromptMetric.response_time).label('avg_response_time'),
-            (func.sum(case((PromptMetric.is_success, 1), else_=0)) / func.count(PromptMetric.id) * 100).label('success_rate'),
-            func.max(PromptMetric.timestamp).label('last_execution')
-        ).outerjoin(
-            PromptMetric
-        ).group_by(
-            DbPrompt.id, DbPrompt.name
-        ).order_by(
-            desc('execution_count')
-        ).limit(limit).all()
+        """Retrieve the top-performing prompts based on execution count.
+
+    Queries the database to get prompts with their metrics, ordered by the number of executions
+    in descending order. Returns a list of TopPerformer objects containing prompt details and
+    performance metrics.
+
+    Args:
+        db (Session): Database session for querying prompt metrics.
+        limit (int, optional): Maximum number of prompts to return. Defaults to 5.
+
+    Returns:
+        List[TopPerformer]: A list of TopPerformer objects, each containing:
+            - id: Prompt ID.
+            - name: Prompt name.
+            - execution_count: Total number of executions.
+            - avg_response_time: Average response time in seconds, or None if no metrics.
+            - success_rate: Success rate percentage, or None if no metrics.
+            - last_execution: Timestamp of the last execution, or None if no metrics.
+    """
+        results = (
+            db.query(
+                DbPrompt.id,
+                DbPrompt.name,
+                func.count(PromptMetric.id).label("execution_count"),# pylint: disable=not-callable
+                func.avg(PromptMetric.response_time).label("avg_response_time"),
+                (func.sum(case((PromptMetric.is_success, 1), else_=0)) / func.count(PromptMetric.id) * 100).label("success_rate"),
+                func.max(PromptMetric.timestamp).label("last_execution"),
+            )
+            .outerjoin(PromptMetric)
+            .group_by(DbPrompt.id, DbPrompt.name)
+            .order_by(desc("execution_count"))
+            .limit(limit)
+            .all()
+        )
 
         return [
             TopPerformer(
@@ -157,8 +176,9 @@ async def get_top_prompts(self, db: Session, limit: int = 5) -> List[TopPerforme
                 execution_count=result.execution_count or 0,
                 avg_response_time=float(result.avg_response_time) if result.avg_response_time else None,
                 success_rate=float(result.success_rate) if result.success_rate else None,
-                last_execution=result.last_execution
-            ) for result in results
+                last_execution=result.last_execution,
+            )
+            for result in results
         ]
 
     def _convert_db_prompt(self, db_prompt: DbPrompt) -> Dict[str, Any]: