MCP: Add example about CrateDB MCP

Author: amotl

framework/mcp/README.md

@@ -46,6 +46,11 @@ program.
   and includes advanced client programs for Claude and Gemini that work out of the box.
   It is written in Python, optionally to be invoked with `uv` or `uvx`.
 
+- `example_cratedb_mcp.py`:
+  The [CrateDB MCP Server] specialises on advanced CrateDB SQL operations by blending in
+  knowledge base resources from CrateDB's documentation about query optimizations.
+  It is written in Python, optionally to be invoked with `uv` or `uvx`.
+
 ## Resources
 
 - Read a [brief introduction to MCP] by ByteByteGo.
@@ -134,6 +139,7 @@ unlocking more details and features.
 [Claude Desktop configuration]: https://github.com/modelcontextprotocol/servers?tab=readme-ov-file#using-an-mcp-client
 [connecting to an already running MCP server]: https://github.com/modelcontextprotocol/python-sdk/issues/145
 [CrateDB]: https://cratedb.com/database
+[CrateDB MCP Server]: https://github.com/crate/cratedb-mcp
 [CrateDB SQLAlchemy dialect]: https://cratedb.com/docs/sqlalchemy-cratedb/
 [DBHub]: https://github.com/bytebase/dbhub
 [Introduction to MCP]: https://modelcontextprotocol.io/introduction

framework/mcp/backlog.md

@@ -16,6 +16,7 @@
   - https://github.com/crate/crate/issues/11757
   - https://github.com/crate/crate/issues/12544
 - PG-MCP: Fix `/rowcount endpoint`
+  https://github.com/stuzero/pg-mcp-server/issues/10
 
 ## Iteration +2
 - General: Evaluate all connectors per `stdio` and `sse`, where possible

framework/mcp/example_cratedb_mcp.py

@@ -0,0 +1,52 @@
+# CrateDB MCP Server
+# https://github.com/crate/cratedb-mcp
+#
+# Derived from:
+# https://github.com/modelcontextprotocol/python-sdk?tab=readme-ov-file#writing-mcp-clients
+from cratedb_toolkit.util import DatabaseAdapter
+from mcp import ClientSession, StdioServerParameters
+from mcp.client.stdio import stdio_client
+
+from mcp_utils import McpDatabaseConversation
+
+# Create server parameters for stdio connection.
+server_params = StdioServerParameters(
+    command="cratedb-mcp",
+    args=[],
+    env={
+        "CRATEDB_MCP_HTTP_URL": "http://localhost:4200",
+        "CRATEDB_MCP_TRANSPORT": "stdio",
+    },
+)
+
+
+async def run():
+    async with stdio_client(server_params) as (read, write):
+        async with ClientSession(
+            read, write
+        ) as session:
+            # Initialize the connection
+            await session.initialize()
+
+            client = McpDatabaseConversation(session)
+            await client.inquire()
+
+            print("## MCP server conversations")
+            print()
+
+            # Provision database.
+            db = DatabaseAdapter("crate://crate@localhost:4200/")
+            db.run_sql("CREATE TABLE IF NOT EXISTS public.mcp_builtin (id INT, data TEXT)")
+            db.run_sql("INSERT INTO public.mcp_builtin (id, data) VALUES (42, 'Hotzenplotz')")
+            db.refresh_table("public.mcp_builtin")
+
+            # Call a few tools.
+            await client.call_tool("query_sql", arguments={"query": "SELECT * FROM sys.summits ORDER BY height DESC LIMIT 3"})
+            await client.call_tool("get_table_metadata", arguments={})
+            await client.call_tool("get_health", arguments={})
+
+
+if __name__ == "__main__":
+    import asyncio
+
+    asyncio.run(run())

framework/mcp/requirements.txt

@@ -1,5 +1,6 @@
+cratedb-mcp @ git+https://github.com/crate/cratedb-mcp@packaging-adjustments
 cratedb-toolkit
-mcp<1.6
+mcp<1.7
 mcp-alchemy @ git+https://github.com/runekaagaard/mcp-alchemy.git@b85aae6; python_version>='3.12'
 sqlalchemy-cratedb>=0.42.0.dev1
 where

framework/mcp/test.py

@@ -190,3 +190,35 @@ def test_pg_mcp():
 
     assert b"Getting prompt: nl_to_sql_prompt" in p.stdout
     assert b"You are an expert PostgreSQL database query assistant" in p.stdout
+
+
+def test_cratedb_mcp():
+    """
+    Validate the CrateDB MCP server works well.
+
+    It is written in Python and uses HTTP.
+    https://github.com/crate/cratedb-mcp
+    """
+    p = run(f"{sys.executable} example_cratedb_mcp.py")
+    assert p.returncode == 0
+
+    # Validate output specific to the MCP server.
+    assert b"Processing request of type" in p.stderr
+    assert b"ListPromptsRequest" in p.stderr
+    assert b"ListResourcesRequest" in p.stderr
+    assert b"ListToolsRequest" in p.stderr
+    assert b"CallToolRequest" in p.stderr
+
+    # Validate output specific to CrateDB.
+    assert b"Calling tool: query_sql" in p.stdout
+    assert b"cols:" in p.stdout
+    assert b"rows:" in p.stdout
+    assert b"Mont Blanc" in p.stdout
+
+    assert b"Calling tool: get_table_metadata" in p.stdout
+    assert b"- information_schema" in p.stdout
+    assert b"total_missing_shards: null" in p.stdout
+    assert b"table_name: table_partitions" in p.stdout
+
+    assert b"Calling tool: get_health" in p.stdout
+    assert b"underreplicated_shards" in p.stdout