Merge branch 'main' into bundle-mariadb

Author: junhaoliao

README.md

@@ -3,6 +3,7 @@
 [![Open bug reports](https://img.shields.io/github/issues/y-scope/clp/bug?label=bugs)](https://github.com/y-scope/clp/issues?q=is%3Aissue+is%3Aopen+label%3Abug)
 [![Open feature requests](https://img.shields.io/github/issues/y-scope/clp/enhancement?label=feature-requests)](https://github.com/y-scope/clp/issues?q=is%3Aissue+is%3Aopen+label%3Aenhancement)
 [![Discord][badge-discord]][yscope-community-discord]
+[![Slack][badge-slack]][yscope-community-slack]
 [![CLP on Zulip][badge-zulip]][yscope-community-zulip]
 
 YScope's Compressed Log Processor (CLP) compresses your logs, and allows you to search the
@@ -89,14 +90,16 @@ You can use GitHub issues to [report a bug][bug-report] or [request a feature][f
 Need help? Join us on one of our community servers:
 
 * [![Discord][badge-discord]][yscope-community-discord]
+* [![Slack][badge-slack]][yscope-community-slack]
 * [![CLP on Zulip][badge-zulip]][yscope-community-zulip]
 
 # Next Steps
 
 This is our open-source release which we will be constantly updating with bug fixes, features, etc.
 If you would like a feature or want to report a bug, please file an issue and we'll be happy to engage.
 
-[badge-discord]: https://img.shields.io/discord/1377353873068392580?style=flat&logo=discord&logoColor=white&label=Discord&labelColor=%235561f5
+[badge-discord]: https://img.shields.io/discord/1377353873068392580?style=flat&logo=discord&logoColor=white&label=Discord&labelColor=5561f5
+[badge-slack]: https://img.shields.io/badge/Slack-yscope--community-1e724f?style=flat&logo=slack&logoColor=white&labelColor=4A154B
 [badge-zulip]: https://img.shields.io/badge/Zulip-yscope--clp-1888FA?logo=zulip
 [bug-report]: https://github.com/y-scope/clp/issues/new?assignees=&labels=bug&template=bug-report.yml
 [build-package]: http://docs.yscope.com/clp/main/dev-docs/building-package
@@ -118,4 +121,5 @@ If you would like a feature or want to report a bug, please file an issue and we
 [re2]: https://github.com/google/re2
 [uber-blog]: https://www.uber.com/en-US/blog/reducing-logging-cost-by-two-orders-of-magnitude-using-clp
 [yscope-community-discord]: https://discord.gg/7kZA2m5G87
+[yscope-community-slack]: https://communityinviter.com/apps/yscopecommunity/yscope-community
 [yscope-community-zulip]: https://yscope-clp.zulipchat.com

components/clp-mcp-server/README.md

@@ -49,6 +49,14 @@ For more details on Claude Desktop MCP setup, see the
 
 > **Warning:** 🚧 This section is still under construction.
 
+## Testing
+
+Use the following command to run all unit tests:
+
+```shell
+uv test pytest
+```
+
 [claude-desktop]: https://claude.ai/download
 [claude-desktop-mcp-doc]: https://modelcontextprotocol.io/docs/develop/connect-local-servers
 [mcp]: https://modelcontextprotocol.io/docs/getting-started/intro

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

@@ -0,0 +1,28 @@
+"""Constants for CLP MCP server."""
+
+EXPIRED_SESSION_SWEEP_INTERVAL_SECONDS = 600  # 10 minutes
+NUM_ITEMS_PER_PAGE = 10
+MAX_CACHED_RESULTS = 1000
+# 10 minutes
+SESSION_TTL_SECONDS = 600
+
+SERVER_NAME = "clp-mcp-server"
+
+# fmt: off
+SYSTEM_PROMPT = (
+"You are an AI assistant that helps users query a log database using KQL (Kibana Query Language)."
+" You should generate a KQL query that accurately expresses the user's intent. The generated KQL"
+" query should be as specific as possible to minimize the number of log messages returned.\n\n"
+"You should consider the following guidelines to generate KQL queries efficiently:\n"
+"- Use specific field names and values to narrow down the search.\n"
+"- Avoid using wildcards (`*`) unless absolutely necessary, as they can lead to large result"
+" sets.\n"
+"- Use logical operators (`AND`, `OR`, `NOT`) to combine one or more key-value searches.\n"
+"- Consider the time range of the logs you are searching. If the user specifies a time range,"
+" include it in the KQL query.\n"
+"- If the user query is ambiguous or lacks detail, ask clarifying questions to better understand"
+" their intent before generating the KQL query.\n"
+"- Always ensure that the generated KQL query is syntactically correct and can be executed without"
+" errors."
+)
+# fmt: on

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

@@ -2,25 +2,10 @@
 
 from typing import Any
 
-from fastmcp import FastMCP
+from fastmcp import Context, FastMCP
 
-
-class ProtocolConstant:
-    """Constants for the CLP MCP Server."""
-
-    SERVER_NAME = "clp-mcp-server"
-
-    # Tool names
-    TOOL_HELLO_WORLD = "hello_world"
-    TOOL_GET_SERVER_INFO = "get_server_info"
-
-    @classmethod
-    def get_capabilities(cls) -> list[str]:
-        """
-        Gets the capabilities of the server.
-        :return: A list of tool names supported by the server.
-        """
-        return [cls.TOOL_HELLO_WORLD, cls.TOOL_GET_SERVER_INFO]
+from . import constants
+from .session_manager import SessionManager
 
 
 def create_mcp_server() -> FastMCP:
@@ -31,22 +16,44 @@ def create_mcp_server() -> FastMCP:
     :raise: Propagates `FastMCP.__init__`'s exceptions.
     :raise: Propagates `FastMCP.tool`'s exceptions.
     """
-    mcp = FastMCP(name=ProtocolConstant.SERVER_NAME)
+    mcp = FastMCP(name=constants.SERVER_NAME)
+
+    session_manager = SessionManager(session_ttl_seconds=constants.SESSION_TTL_SECONDS)
 
-    @mcp.tool()
-    def get_server_info() -> dict[str, Any]:
+    @mcp.tool
+    async def get_instructions(ctx: Context) -> str:
         """
-        Gets the MCP server's information.
+        Gets a pre-defined "system prompt" that guides the LLM behavior.
+        This function must be invoked before any other `FastMCP.tool`.
 
-        :return: The server's information with a list of capabilities.
+        :param ctx: The `FastMCP` context containing the metadata of the underlying MCP session.
+        :return: A string of "system prompt".
         """
-        return {
-            "name": ProtocolConstant.SERVER_NAME,
-            "capabilities": ProtocolConstant.get_capabilities(),
-            "status": "running",
-        }
+        await session_manager.start()
+        return session_manager.get_or_create_session(ctx.session_id).get_instructions()
+
+    @mcp.tool
+    async def get_nth_page(page_index: int, ctx: Context) -> dict[str, Any]:
+        """
+        Retrieves the n-th page of a paginated response with the paging metadata from the previous
+        query.
+
+        :param page_index: Zero-based index, e.g., 0 for the first page.
+        :param ctx: The `FastMCP` context containing the metadata of the underlying MCP session.
+        :return: A dictionary containing the following key-value pairs on success:
+            - "items": A list of log entries in the requested page.
+            - "num_total_pages": Total number of pages available from the query as an integer.
+            - "num_total_items": Total number of log entries available from the query as an integer.
+            - "num_items_per_page": Number of log entries per page.
+            - "has_next": Whether a page exists after the returned one.
+            - "has_previous": Whether a page exists before the returned one.
+        :return: A dictionary with the following key-value pair on failures:
+            - "Error": An error message describing the failure.
+        """
+        await session_manager.start()
+        return session_manager.get_nth_page(ctx.session_id, page_index)
 
-    @mcp.tool()
+    @mcp.tool
     def hello_world(name: str = "clp-mcp-server user") -> dict[str, Any]:
         """
         Provides a simple hello world greeting.
@@ -56,7 +63,7 @@ def hello_world(name: str = "clp-mcp-server user") -> dict[str, Any]:
         """
         return {
             "message": f"Hello World, {name.strip()}!",
-            "server": ProtocolConstant.SERVER_NAME,
+            "server": constants.SERVER_NAME,
             "status": "running",
         }