#149: Optimised resources (#150)

Author: ahsimb

doc/changes/unreleased.md

@@ -8,3 +8,7 @@
 * #141: Added annotations to the tools.
 * #144: Added a reserved words resource.
 * #146: Added a resource listing builtin functions.
+
+## Refactoring
+
+* #149: Optimised resources in terms of token usage.

exasol/ai/mcp/server/main.py

@@ -17,10 +17,12 @@
     str_to_bool,
 )
 from exasol.ai.mcp.server.mcp_resources import (
+    builtin_function_categories,
     describe_builtin_function,
     list_builtin_functions,
 )
 from exasol.ai.mcp.server.mcp_server import ExasolMCPServer
+from exasol.ai.mcp.server.meta_query import SysInfoType
 from exasol.ai.mcp.server.server_settings import (
     ExaDbResult,
     McpServerSettings,
@@ -350,49 +352,80 @@ def list_sql_types() -> ExaDbResult:
         return mcp_server.list_sql_types()
 
     @mcp_server.resource(
-        uri="system://system-tables",
+        uri="system://system-table/list",
         description="List of Exasol system tables.",
         annotations={"readOnlyHint": True, "idempotentHint": True},
     )
-    def list_system_tables() -> ExaDbResult:
-        return mcp_server.list_system_tables()
+    def list_system_tables() -> list[str]:
+        return mcp_server.list_system_tables(SysInfoType.SYSTEM)
 
     @mcp_server.resource(
-        uri="system://statistics-tables",
+        uri="system://system-table/details/{name}",
+        description="Information about an Exasol system table with the specified name.",
+        annotations={"readOnlyHint": True, "idempotentHint": True},
+    )
+    def describe_system_table(name: str) -> ExaDbResult:
+        return mcp_server.describe_system_table(SysInfoType.SYSTEM, name)
+
+    @mcp_server.resource(
+        uri="system://statistics-table/list",
         description="List of Exasol statistics tables.",
         annotations={"readOnlyHint": True, "idempotentHint": True},
     )
-    def list_statistics_tables() -> ExaDbResult:
-        return mcp_server.list_statistics_tables()
+    def list_statistics_tables() -> list[str]:
+        return mcp_server.list_system_tables(SysInfoType.STATISTICS)
 
     @mcp_server.resource(
-        uri="dialect://reserved-keywords",
-        description="List of Exasol reserved keywords.",
+        uri="system://statistics-table/details/{name}",
+        description="Information about an Exasol statistics table with the specified name.",
         annotations={"readOnlyHint": True, "idempotentHint": True},
     )
-    def list_reserved_keywords() -> ExaDbResult:
-        return mcp_server.list_reserved_keywords()
+    def describe_statistics_table(name) -> ExaDbResult:
+        return mcp_server.describe_system_table(SysInfoType.STATISTICS, name)
 
     @mcp_server.resource(
-        uri="dialect://built-in-functions/list/{category}",
+        uri="dialect://keyword/reserved/{letter}",
         description=(
-            "List of Exasol built-in functions by category. Categories: numeric, "
-            "string, date-time, geospatial, bitwise, conversion, other-scalar, "
-            "aggregate, analytic. A function can belong to more than one category."
+            "List of Exasol keywords that are reserved words, "
+            "and start from a given letter."
         ),
         annotations={"readOnlyHint": True, "idempotentHint": True},
     )
-    def _list_builtin_functions(category: str) -> ExaDbResult:
-        return list_builtin_functions(category)
+    def list_reserved_keywords(letter) -> list[str]:
+        return mcp_server.list_keywords(True, letter)
 
     @mcp_server.resource(
-        uri="dialect://built-in-functions/details/{name}",
+        uri="dialect://keyword/non-reserved/{letter}",
         description=(
-            "Information about a built-in function with the specified name. "
-            "May include usage notes and one or more examples."
+            "List of Exasol keywords that are not reserved words, "
+            "and start from a given letter."
         ),
         annotations={"readOnlyHint": True, "idempotentHint": True},
     )
+    def list_non_reserved_keywords(letter: str) -> list[str]:
+        return mcp_server.list_keywords(False, letter)
+
+    @mcp_server.resource(
+        uri="dialect://built-in-function/categories",
+        description="Exasol built-in function categories.",
+        annotations={"readOnlyHint": True, "idempotentHint": True},
+    )
+    def _builtin_function_categories() -> list[str]:
+        return builtin_function_categories()
+
+    @mcp_server.resource(
+        uri="dialect://built-in-function/list/{category}",
+        description="List of Exasol built-in functions in the specified category.",
+        annotations={"readOnlyHint": True, "idempotentHint": True},
+    )
+    def _list_builtin_functions(category: str) -> list[str]:
+        return list_builtin_functions(category)
+
+    @mcp_server.resource(
+        uri="dialect://built-in-function/details/{name}",
+        description="Information about a built-in function with the specified name.",
+        annotations={"readOnlyHint": True, "idempotentHint": True},
+    )
     def _describe_builtin_function(name: str) -> ExaDbResult:
         return describe_builtin_function(name)
 

exasol/ai/mcp/server/mcp_resources.py

@@ -1,5 +1,6 @@
 import importlib.resources
 import json
+from functools import cache
 from typing import Any
 
 from exasol.ai.mcp.server.server_settings import ExaDbResult
@@ -8,25 +9,33 @@
 PACKAGE_RESOURCES = f"{__package__}.resources"
 
 
-def list_builtin_functions(category: str) -> ExaDbResult:
+@cache
+def load_builtin_func_list() -> list[dict[str, Any]]:
+    with importlib.resources.open_text(PACKAGE_RESOURCES, BUILTIN_FUNCTIONS_JSON) as f:
+        return json.load(f)
+
+
+def builtin_function_categories() -> list[str]:
+    """
+    Returns a list of builtin function categories.
+    """
+    func_list = load_builtin_func_list()
+    categories: set[str] = set()
+    for func_info in func_list:
+        categories.update(func_info["types"])
+    return sorted(categories)
+
+
+def list_builtin_functions(category: str) -> list[str]:
     """
     Selects the list of builtin functions of the specified type (category), reading
-    the resource json. Only takes the name and the description fields.
+    the resource json. Returns only the function names.
     """
-    with importlib.resources.open_text(PACKAGE_RESOURCES, BUILTIN_FUNCTIONS_JSON) as f:
-        func_list: list[dict[str, Any]] = json.load(f)
-    allowed_fields = ["name", "description"]
+    func_list = load_builtin_func_list()
     category = category.lower()
-    selected_info = [
-        {
-            field_name: field_value
-            for field_name, field_value in func_info.items()
-            if field_name in allowed_fields
-        }
-        for func_info in func_list
-        if category in func_info["types"]
+    return [
+        func_info["name"] for func_info in func_list if category in func_info["types"]
     ]
-    return ExaDbResult(selected_info)
 
 
 def describe_builtin_function(name: str) -> ExaDbResult:
@@ -35,8 +44,7 @@ def describe_builtin_function(name: str) -> ExaDbResult:
     Returns all fields. Some functions, for example TO_CHAR, can have information in
     more than one row.
     """
-    with importlib.resources.open_text(PACKAGE_RESOURCES, BUILTIN_FUNCTIONS_JSON) as f:
-        func_list: list[dict[str, Any]] = json.load(f)
+    func_list = load_builtin_func_list()
     name = name.upper()
     selected_info = [func_info for func_info in func_list if func_info["name"] == name]
     return ExaDbResult(selected_info)

exasol/ai/mcp/server/mcp_server.py

@@ -101,6 +101,10 @@ def remove_info_column(result: list[dict[str, Any]]) -> list[dict[str, Any]]:
     return result
 
 
+def _take_column(column_name: str, result: ExaDbResult) -> list[str]:
+    return [row[column_name] for row in result.result]
+
+
 class ExasolMCPServer(FastMCP):
     """
     An Exasol MCP server based on FastMCP.
@@ -341,14 +345,18 @@ def list_sql_types(self) -> ExaDbResult:
         query = ExasolMetaQuery.get_sql_types()
         return self._execute_meta_query(query)
 
-    def list_system_tables(self) -> ExaDbResult:
-        query = self.meta_query.get_system_tables(SysInfoType.SYSTEM)
-        return self._execute_meta_query(query)
+    def list_system_tables(self, info_type: SysInfoType) -> list[str]:
+        query = self.meta_query.get_system_tables(info_type)
+        return _take_column(
+            self.config.tables.name_field, self._execute_meta_query(query)
+        )
 
-    def list_statistics_tables(self) -> ExaDbResult:
-        query = self.meta_query.get_system_tables(SysInfoType.STATISTICS)
+    def describe_system_table(
+        self, info_type: SysInfoType, table_name: str
+    ) -> ExaDbResult:
+        query = self.meta_query.get_system_tables(info_type, table_name)
         return self._execute_meta_query(query)
 
-    def list_reserved_keywords(self) -> ExaDbResult:
-        query = ExasolMetaQuery.get_reserved_keywords()
-        return self._execute_meta_query(query)
+    def list_keywords(self, reserved: bool, letter: str) -> list[str]:
+        query = ExasolMetaQuery.get_keywords(reserved, letter)
+        return _take_column("KEYWORD", self._execute_meta_query(query))

exasol/ai/mcp/server/meta_query.py

@@ -474,11 +474,17 @@ def get_sql_types() -> str:
         )
         return query.sql(dialect="exasol", identify=True)
 
-    def get_system_tables(self, info_type: SysInfoType) -> str:
+    def get_system_tables(
+        self, info_type: SysInfoType, table_name: str | None = None
+    ) -> str:
         """
         Collects names and comments for the system or statistics tables and views.
+        The output will be restricted to one table if it's name is specified.
         """
         conf = self._config.tables
+        predicates = [self._get_column_eq_predicate("SCHEMA_NAME", info_type.value)]
+        if table_name:
+            predicates.append(self._get_column_eq_predicate("OBJECT_NAME", table_name))
         query = (
             exp.Select()
             .select(
@@ -487,20 +493,27 @@ def get_system_tables(self, info_type: SysInfoType) -> str:
                 exp.column("OBJECT_COMMENT").as_(conf.comment_field),
             )
             .from_(exp.Table(this="EXA_SYSCAT", db="SYS"))
-            .where(exp.column("SCHEMA_NAME").eq(exp.Literal.string(info_type.value)))
+            .where(*predicates)
         )
         return query.sql(dialect="exasol", identify=True)
 
     @staticmethod
-    def get_reserved_keywords() -> str:
+    def get_keywords(reserved: bool, letter: str) -> str:
         """
-        The query returns a list of reserved words.
+        The query returns a list of keywords that start from the given letter.
+        The list is restricted to keywords that are either reserved words or not
+        reserver words, as per the argument.
         """
         query = (
             exp.Select()
             .select(exp.column("KEYWORD"))
             .from_(exp.Table(this="EXA_SQL_KEYWORDS", db="SYS"))
-            .where(exp.column("RESERVED").eq(exp.Boolean(this=True)))
-            .order_by(exp.column("RESERVED"))
+            .where(
+                exp.column("RESERVED").eq(exp.Boolean(this=reserved)),
+                exp.func("LEFT", exp.column("KEYWORD"), 1).eq(
+                    exp.Literal.string(letter.upper())
+                ),
+            )
+            .order_by(exp.column("KEYWORD"))
         )
         return query.sql(dialect="exasol", identify=True)