MCP: Add tool get_table_columns

Author: amotl

CHANGES.md

@@ -4,6 +4,7 @@
 - OCI: Added `curl` to image
 - MCP: Started using MCP tool descriptions from Python docstrings
 - Instructions: Copy-editing. Wording.
+- MCP: Added tool `get_table_columns`
 
 ## v0.0.5 - 2025-07-22
 - MCP: Fixed defunct `get_cratedb_documentation_index` tool

README.md

@@ -196,7 +196,7 @@ The CrateDB MCP Server provides two families of tools.
 The **Text-to-SQL tools** talk to a CrateDB database cluster to inquire database
 and table metadata, and table content.
 <br>
-Tool names are: `get_cluster_health`, `get_table_metadata`, `query_sql`
+Tool names are: `query_sql`, `get_table_columns`, `get_table_metadata`
 
 The **documentation server tools** looks up guidelines specific to CrateDB topics,
 to provide the most accurate information possible.
@@ -205,6 +205,8 @@ Relevant information is pulled from <https://cratedb.com/docs>, curated per
 <br>
 Tool names are: `get_cratedb_documentation_index`, `fetch_cratedb_docs`
 
+Health inquiry tool: `get_cluster_health`
+
 ### Install package
 
 The configuration snippets for AI assistants are using the `uvx` launcher

cratedb_mcp/core.py

@@ -10,6 +10,7 @@
     fetch_cratedb_docs,
     get_cluster_health,
     get_cratedb_documentation_index,
+    get_table_columns,
     get_table_metadata,
     query_sql,
 )
@@ -46,6 +47,13 @@ def add_tools(self):
                 tags={"text-to-sql"},
             )
         )
+        self.mcp.add_tool(
+            Tool.from_function(
+                fn=get_table_columns,
+                description=get_table_columns.__doc__,
+                tags={"text-to-sql"},
+            )
+        )
         self.mcp.add_tool(
             Tool.from_function(
                 fn=get_table_metadata,

cratedb_mcp/knowledge.py

@@ -9,6 +9,21 @@
 
 
 class Queries:
+    TABLES_COLUMNS = """
+SELECT
+    c.table_schema,
+    c.table_name,
+    c.column_name,
+    c.data_type,
+    c.is_nullable,
+    c.column_default
+FROM information_schema.columns c
+WHERE {where}
+ORDER BY
+    c.table_schema,
+    c.table_name,
+    c.ordinal_position
+    """
     TABLES_METADATA = """
 WITH partitions_health AS (SELECT table_name,
                                       table_schema,

cratedb_mcp/prompt/instructions.md

@@ -3,12 +3,14 @@
 Use all available tools for gathering accurate information.
 
 You have the following tools available:
-1. `get_table_metadata`: Return table metadata for all tables stored in CrateDB.
-2. `query_sql`: Execute an SQL query on CrateDB and return the results. Select only the columns you need (avoid `SELECT *`) and, where appropriate, add a `LIMIT` clause to keep result sets concise.
-3. `get_cratedb_documentation_index`: Return the table of contents for the curated CrateDB documentation index. Use it whenever you need to verify CrateDB-specific syntax.
-4. `fetch_cratedb_docs`: Given a `link` returned by `get_cratedb_documentation_index`, fetch the full content of that documentation page. Content can be quoted verbatim when answering questions about CrateDB.
+- `get_table_columns`: Return table column information for all tables stored in CrateDB.
+- `get_table_metadata`: Return table metadata for all tables stored in CrateDB.
+- `query_sql`: Execute an SQL query on CrateDB and return the results. Select only the columns you need (avoid `SELECT *`) and, where appropriate, add a `LIMIT` clause to keep result sets concise.
+- `get_cratedb_documentation_index`: Return the table of contents for the curated CrateDB documentation index. Use it whenever you need to verify CrateDB-specific syntax.
+- `fetch_cratedb_docs`: Given a `link` returned by `get_cratedb_documentation_index`, fetch the full content of that documentation page. Content can be quoted verbatim when answering questions about CrateDB.
 
 Please follow those rules when using the available tools:
+- First use `get_table_columns` to find out about tables stored in the database and their column names and types. Next, use `query_sql` to execute the SQL query.
 - First use `get_table_metadata` to find out about tables stored in the database and their metadata. Next, use `query_sql` to execute the SQL query.
 - First use `get_cratedb_documentation_index` to get an overview about curated documentation resources about CrateDB. Then, use `fetch_cratedb_docs` to retrieve individual pages by `link`.
 

cratedb_mcp/tool.py

@@ -28,6 +28,40 @@ def query_sql(query: str) -> dict:
     return query_cratedb(query)
 
 
+def get_table_columns() -> dict:
+    """
+    Return schema and column information for all tables stored in CrateDB from
+    its `information_schema` table. Use it to discover database entities you are
+    unfamiliar with, the column names are crucial for correctly formulating SQL
+    queries.
+
+    The returned fields are table_schema, table_name, column_name,
+    data_type, is_nullable, and column_default.
+
+    The returned sections are:
+    - user tables: includes all user-defined tables without system tables
+    - system tables: `information_schema`, `pg_catalog`, and `sys`.
+
+    """
+
+    variants = {
+        "user": """
+            table_schema != 'information_schema' AND
+            table_schema != 'pg_catalog' AND
+            table_schema != 'sys'
+        """,
+        "information_schema": "table_schema = 'information_schema'",
+        "pg_catalog": "table_schema = 'pg_catalog'",
+        "sys": "table_schema = 'sys'",
+    }
+
+    response = {}
+    for variant, where in variants.items():
+        query = Queries.TABLES_COLUMNS.format(where=where)
+        response[variant] = query_sql(query)
+    return response
+
+
 def get_table_metadata() -> dict:
     """
     Return table metadata for all tables stored in CrateDB.

examples/mcptools.sh

@@ -28,6 +28,7 @@ mcpt tools cratedb-mcp serve
 
 # Explore the Text-to-SQL tools.
 mcpt call query_sql --params '{"query":"SELECT * FROM sys.summits LIMIT 3"}' cratedb-mcp serve
+mcpt call get_table_columns cratedb-mcp serve
 mcpt call get_table_metadata cratedb-mcp serve
 mcpt call get_cluster_health cratedb-mcp serve
 

tests/test_examples.py

@@ -5,7 +5,7 @@
 
 
 def test_mcptools():
-    proc = subprocess.run(["examples/mcptools.sh"], capture_output=True, timeout=15, check=True)
+    proc = subprocess.run(["examples/mcptools.sh"], capture_output=True, timeout=20, check=True)
     assert proc.returncode == 0
     if b"Skipped." in proc.stdout:
         raise pytest.skip("mcptools not installed")

tests/test_knowledge.py

@@ -12,6 +12,7 @@ def test_documentation_index():
 
 
 def test_queries():
+    assert "information_schema.columns" in Queries.TABLES_COLUMNS
     assert "information_schema.tables" in Queries.TABLES_METADATA
     assert "partitions_health" in Queries.TABLES_METADATA
     assert "sys.health" in Queries.HEALTH

tests/test_mcp.py

@@ -4,6 +4,7 @@
     fetch_cratedb_docs,
     get_cluster_health,
     get_cratedb_documentation_index,
+    get_table_columns,
     get_table_metadata,
     query_sql,
 )
@@ -57,6 +58,18 @@ def test_query_sql_forbidden_sneak_value():
     assert ex.match("Only queries that have a SELECT statement are allowed")
 
 
+def test_get_table_columns():
+    response = str(get_table_columns())
+    assert "information_schema" in response
+    assert "pg_catalog" in response
+
+    # Verify the returned structure.
+    result = get_table_columns()
+    assert isinstance(result, dict)
+    expected_keys = {"user", "information_schema", "pg_catalog", "sys"}
+    assert set(result.keys()) == expected_keys
+
+
 def test_get_table_metadata():
     assert "partitions_health" in str(get_table_metadata())