Merge branch 'main' into mcp-integration-test

Author: junhaoliao

components/clp-mcp-server/clp_mcp_server/clp_mcp_server.py

@@ -2,17 +2,21 @@
 
 import ipaddress
 import logging
+import os
 import socket
 import sys
 from pathlib import Path
 
 import click
-from clp_py_utils.clp_config import CLPConfig
+from clp_py_utils.clp_config import CLPConfig, MCP_SERVER_COMPONENT_NAME
+from clp_py_utils.clp_logging import get_logger, get_logging_formatter, set_logging_level
 from clp_py_utils.core import read_yaml_config_file
 from pydantic import ValidationError
 
 from .server import create_mcp_server
 
+logger = get_logger(MCP_SERVER_COMPONENT_NAME)
+
 
 @click.command()
 @click.option(
@@ -34,10 +38,12 @@ def main(host: str, port: int, config_path: Path) -> int:
     :param config_path: The path to server's configuration file.
     :return: Exit code (0 for success, non-zero for failure).
     """
-    logging.basicConfig(
-        level=logging.INFO, format="%(asctime)s - %(name)s - %(levelname)s - %(message)s"
-    )
-    logger = logging.getLogger(__name__)
+    # Setup logging to file
+    log_file_path = Path(os.getenv("CLP_LOGS_DIR")) / "mcp_server.log"
+    logging_file_handler = logging.FileHandler(filename=log_file_path, encoding="utf-8")
+    logging_file_handler.setFormatter(get_logging_formatter())
+    logger.addHandler(logging_file_handler)
+    set_logging_level(logger, os.getenv("CLP_LOGGING_LEVEL"))
 
     exit_code = 0
 

components/clp-mcp-server/clp_mcp_server/server/server.py

@@ -4,6 +4,8 @@
 
 from clp_py_utils.clp_config import CLPConfig
 from fastmcp import Context, FastMCP
+from starlette.requests import Request
+from starlette.responses import PlainTextResponse
 
 from clp_mcp_server.clp_connector import ClpConnector
 
@@ -161,4 +163,14 @@ async def search_by_kql_with_timestamp_range(
 
         return await _execute_kql_query(ctx.session_id, kql_query, begin_ts, end_ts)
 
+    @mcp.custom_route("/health", methods=["GET"])
+    async def health_check(_request: Request) -> PlainTextResponse:
+        """
+        Health check endpoint.
+
+        :param _request: An HTTP request object.
+        :return: A plain text response indicating server is healthy.
+        """
+        return PlainTextResponse("OK")
+
     return mcp

components/clp-mcp-server/clp_mcp_server/server/session_manager.py

@@ -83,12 +83,15 @@ def cache_query_result_and_get_first_page(
         """
         :param results: Log entries from the query to cache.
         :return: Forwards `SessionState.get_page_data`'s return values.
-        :return: _GET_INSTRUCTIONS_NOT_RUN_ERROR if `get_instructions` has not been called in this
-            session.
+        :return: A dictionary with the following key-value pair on failures:
+            - "Error": An error message describing the failure.
         """
         if self._is_instructions_retrieved is False:
             return self._GET_INSTRUCTIONS_NOT_RUN_ERROR.copy()
 
+        if len(results) == 0:
+            return {"Error": "No log events found matching the KQL query."}
+
         self._cached_query_result = PaginatedQueryResult(
             log_entries=results, num_items_per_page=self._num_items_per_page
         )

components/clp-mcp-server/clp_mcp_server/server/utils.py

@@ -83,8 +83,9 @@ def format_query_results(query_results: list[dict[str, Any]]) -> list[str]:
     kv-pairs:
     - "timestamp": An integer representing the epoch timestamp in milliseconds.
     - "message": A string representing the log message.
+    - "link": A string representing the link to open the log viewer displaying the message.
 
-    The message will be formatted as `timestamp: <date string>, message: <message>`:
+    The message will be formatted as `timestamp: <date string>, message: <message>, link: <link>`.
 
     :param query_results: A list of dictionaries representing kv-pair log events.
     :return: A list of strings representing formatted log events.
@@ -105,7 +106,9 @@ def format_query_results(query_results: list[dict[str, Any]]) -> list[str]:
             logger.warning("Empty message attached to a log event: %s.", obj)
             continue
 
-        formatted_log_events.append(f"timestamp: {timestamp_str}, message: {message}")
+        link = obj["link"]
+
+        formatted_log_events.append(f"timestamp: {timestamp_str}, message: {message}, link: {link}")
 
     return formatted_log_events
 

components/clp-mcp-server/tests/server/test_utils.py

@@ -13,6 +13,8 @@
 class TestUtils:
     """Test suite for utility functions."""
 
+    LINK = "http://localhost:4000/"
+
     # Error Messages:
     INVALID_DATE_STRING_ERROR = "Invalid date string"
     INVALID_DATE_STRING_FORMAT_ERROR = "Timestamp must end with 'Z' to indicate UTC."
@@ -24,54 +26,68 @@ class TestUtils:
         {
             "timestamp": None,
             "message": '{"message":"Log with None timestamp"}\n',
+            "link": LINK
         },
         {
             "timestamp": "1729267200000",  # str instead of int
             "message": '{"message":"Log with str timestamp"}\n',
+            "link": LINK
         },
         {
             "timestamp": 1729267200000.0,  # float instead of int
             "message": '{"message":"Log with float timestamp"}\n',
+            "link": LINK
         },
     ]
     EXPECTED_INVALID_TYPE = [
-        'timestamp: N/A, message: {"message":"Log with None timestamp"}\n',
-        'timestamp: N/A, message: {"message":"Log with str timestamp"}\n',
-        'timestamp: N/A, message: {"message":"Log with float timestamp"}\n',
+        f'timestamp: N/A, message: {{"message":"Log with None timestamp"}}\n, link: {LINK}',
+        f'timestamp: N/A, message: {{"message":"Log with str timestamp"}}\n, link: {LINK}',
+        f'timestamp: N/A, message: {{"message":"Log with float timestamp"}}\n, link: {LINK}'
     ]
 
     # Test case: invalid timestamp values.
     INVALID_VALUE_ENTRIES = [
         {
             "timestamp": 9999999999999999,
             "message": '{"message":"Log with overflow timestamp"}\n',
+            "link": LINK
         },
         {
             "timestamp": -9999999999999999,
             "message": '{"message":"Log with negative overflow timestamp"}\n',
+            "link": LINK
         },
     ]
     EXPECTED_INVALID_VALUE = [
-        'timestamp: N/A, message: {"message":"Log with overflow timestamp"}\n',
-        'timestamp: N/A, message: {"message":"Log with negative overflow timestamp"}\n',
+        (
+            f'timestamp: N/A, message: {{"message":"Log with overflow timestamp"}}\n,'
+            f' link: {LINK}'
+        ),
+        (
+            f'timestamp: N/A, message: {{"message":"Log with negative overflow timestamp"}}\n,'
+            f' link: {LINK}'
+        )
     ]
 
     # Test case: missing timestamp and message fields.
     MISSING_TIMESTAMP_AND_MESSAGE_ENTRY = [
         {
             "_id": "test001",
+            "link": LINK
         },
         {
             "_id": "test002",
             "message": '{"message":"Log with no timestamp"}\n',
+            "link": LINK
         },
         {
             "_id": "test003",
             "timestamp": 0,
+            "link": LINK
         }
     ]
     EXPECTED_MISSING_TIMESTAMP_AND_MESSAGE = [
-        'timestamp: N/A, message: {"message":"Log with no timestamp"}\n',
+        f'timestamp: N/A, message: {{"message":"Log with no timestamp"}}\n, link: {LINK}',
     ]
 
     # Testing basic functionality.
@@ -83,6 +99,7 @@ class TestUtils:
             "orig_file_path": "/var/log/app.log",
             "archive_id": "abc123",
             "log_event_ix": 99,
+            "link": LINK
         },
         {
             "_id": "test001",
@@ -91,6 +108,7 @@ class TestUtils:
             "orig_file_path": "/var/log/app.log",
             "archive_id": "abc123",
             "log_event_ix": 100,
+            "link": LINK
         },
         {
             "_id": "test002",
@@ -102,6 +120,7 @@ class TestUtils:
             "orig_file_path": "/var/log/app.log",
             "archive_id": "abc124",
             "log_event_ix": 101,
+            "link": LINK
         },
         {
             "_id": "test003",
@@ -113,29 +132,42 @@ class TestUtils:
             "orig_file_path": "/var/log/app.log",
             "archive_id": "abc125",
             "log_event_ix": 102,
+            "link": (
+                "http://localhost:4000/streamFile"
+                "?dataset=default"
+                '&type=json'
+                "&streamId=abc125"
+                "&logEventIdx=102"
+            ),
         },
     ]
 
     EXPECTED_RESULTS = [
         (
             'timestamp: 2024-10-18T16:00:00.123Z, message: '
             '{"ts":1729267200123,"pid":1234,"tid":5678,'
-            '"message":"Log with millisecond precision"}\n'
+            '"message":"Log with millisecond precision"}\n, '
+            "link: http://localhost:4000/streamFile"
+            "?dataset=default"
+            '&type=json'
+            "&streamId=abc125"
+            "&logEventIdx=102"
+            
         ),
         (
-            'timestamp: 2024-10-18T16:00:00.000Z, message: '
-            '{"ts":1729267200000,"pid":1234,"tid":5678,'
-            '"message":"Log with zero milliseconds"}\n'
+            f'timestamp: 2024-10-18T16:00:00.000Z, message: '
+            f'{{"ts":1729267200000,"pid":1234,"tid":5678,'
+            f'"message":"Log with zero milliseconds"}}\n, link: {LINK}'
         ),
         (
-            'timestamp: 1970-01-01T00:00:00.000Z, message: '
-            '{"ts":0,"pid":null,"tid":null,'
-            '"message":"Log at epoch zero"}\n'
+            f'timestamp: 1970-01-01T00:00:00.000Z, message: '
+            f'{{"ts":0,"pid":null,"tid":null,'
+            f'"message":"Log at epoch zero"}}\n, link: {LINK}'
         ),
         (
-            'timestamp: N/A, message: '
-            '{"pid":null,"tid":null,'
-            '"message":"Log at epoch none"}\n'
+            f'timestamp: N/A, message: '
+            f'{{"pid":null,"tid":null,'
+            f'"message":"Log at epoch none"}}\n, link: {LINK}'
         ),
     ]
 

components/clp-mcp-server/tests/test_session_manager.py

@@ -27,6 +27,7 @@ class TestConstants:
     # Number of logs tested in unit test and its expected page counts
     EXPECTED_NUM_LOG_ENTRIES = 25
     EXPECTED_NUM_PAGES = 3
+    EMPTY_LOG_ENTRIES = 0
 
     # 0.5 second for fast expiration tests
     FAST_SESSION_TTL_SECONDS = 0.5
@@ -41,6 +42,7 @@ class TestConstants:
     EXCEEDS_MAX_CACHED_RESULTS_ERR = "exceeds maximum allowed cached results"
     INVALID_NUM_ITEMS_PER_PAGE_ERR = "must be a positive integer"
     GET_INSTRUCTIONS_NOT_CALLED_ERR = "Please call `get_instructions()`"
+    NO_RESULTS_FOUND_IN_KQL_QUERY_ERR = "No log events found matching the KQL query."
     NO_PREVIOUS_PAGINATED_RESPONSE_ERR = "No previous paginated response in this session."
     PAGE_INDEX_OUT_OF_BOUNDS_ERR = "Page index is out of bounds."
 
@@ -115,6 +117,28 @@ def test_query_result_initialization(self) -> None:
 class TestSessionState:
     """Unit tests for SessionState class."""
 
+    def test_error_handling(self) -> None:
+        """Validates error handling of `SessionState`."""
+        session = SessionState(
+            _num_items_per_page=TestConstants.ITEMS_PER_PAGE,
+            _session_id=TestConstants.TEST_SESSION_ID,
+            _session_ttl_seconds=TestConstants.SESSION_TTL_SECONDS
+        )
+
+        first_page = session.cache_query_result_and_get_first_page(
+            TestConstants.create_log_messages(TestConstants.EXPECTED_NUM_LOG_ENTRIES)
+        )
+
+        assert TestConstants.GET_INSTRUCTIONS_NOT_CALLED_ERR in first_page["Error"]
+        page_data = session.get_page_data(1)
+        assert TestConstants.GET_INSTRUCTIONS_NOT_CALLED_ERR in page_data["Error"]
+
+        _ = session.get_instructions()
+        first_page = session.cache_query_result_and_get_first_page(
+            TestConstants.create_log_messages(TestConstants.EMPTY_LOG_ENTRIES)
+        )
+        assert TestConstants.NO_RESULTS_FOUND_IN_KQL_QUERY_ERR in first_page["Error"]
+
     def test_get_page_data(self) -> None:
         """Validates pagination functionality is respecting the defined dictionary format."""
         session = SessionState(
@@ -162,22 +186,6 @@ def test_get_page_data(self) -> None:
         page_data = session.get_page_data(3)
         assert page_data["Error"] == TestConstants.PAGE_INDEX_OUT_OF_BOUNDS_ERR
 
-    def test_no_get_instruction(self) -> None:
-        """Validates error handling when `get_instructions()` has not been called."""
-        session = SessionState(
-            _num_items_per_page=TestConstants.ITEMS_PER_PAGE,
-            _session_id=TestConstants.TEST_SESSION_ID,
-            _session_ttl_seconds=TestConstants.SESSION_TTL_SECONDS
-        )
-
-        first_page = session.cache_query_result_and_get_first_page(
-            TestConstants.create_log_messages(TestConstants.EXPECTED_NUM_LOG_ENTRIES)
-        )
-
-        assert TestConstants.GET_INSTRUCTIONS_NOT_CALLED_ERR in first_page["Error"]
-        page_data = session.get_page_data(1)
-        assert TestConstants.GET_INSTRUCTIONS_NOT_CALLED_ERR in page_data["Error"]
-
     def test_session_expiration(self) -> None:
         """Validates session expiration check."""
         session = SessionState(