MCP: Add example about MCP Alchemy

Author: amotl

framework/mcp/README.md

@@ -36,6 +36,10 @@ program.
   Server for JDBC] from the [quarkus-mcp-servers] package, providing a range
   of tools. It is written in Java, to be invoked with [JBang].
 
+- `example_mcp_alchemy.py`: Exercise communication using the [MCP Alchemy] MCP
+  server package, providing a range of tools. It is written in Python, and uses
+  [SQLAlchemy] and the [CrateDB SQLAlchemy dialect].
+
 ## Resources
 
 - Read a [brief introduction to MCP] by ByteByteGo.
@@ -124,10 +128,12 @@ 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 SQLAlchemy dialect]: https://cratedb.com/docs/sqlalchemy-cratedb/
 [DBHub]: https://github.com/bytebase/dbhub
 [Introduction to MCP]: https://modelcontextprotocol.io/introduction
 [JBang]: https://www.jbang.dev/
 [MCP]: https://modelcontextprotocol.io/
+[MCP Alchemy]: https://github.com/runekaagaard/mcp-alchemy
 [MCP Python SDK]: https://github.com/modelcontextprotocol/python-sdk
 [MCP SSE]: https://github.com/sidharthrajaram/mcp-sse
 [Model Context Protocol (MCP) @ CrateDB]: https://github.com/crate/crate-clients-tools/discussions/234
@@ -137,5 +143,6 @@ unlocking more details and features.
 [npx]: https://docs.npmjs.com/cli/v11/commands/npx
 [oterm configuration]: https://ggozad.github.io/oterm/tools/mcp/
 [quarkus-mcp-servers]: https://github.com/quarkiverse/quarkus-mcp-servers
+[SQLAlchemy]: https://sqlalchemy.org/
 [uv]: https://docs.astral.sh/uv/
 [Writing MCP Clients]: https://github.com/modelcontextprotocol/python-sdk?tab=readme-ov-file#writing-mcp-clients

framework/mcp/example_mcp_alchemy.py

@@ -0,0 +1,50 @@
+# MCP Alchemy Model Context Protocol Server for CrateDB
+# https://github.com/runekaagaard/mcp-alchemy
+#
+# 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
+import where
+
+from mcp_utils import McpDatabaseConversation
+
+# Create server parameters for stdio connection.
+server_params = StdioServerParameters(
+    command=where.first("mcp-alchemy"),
+    args=[],
+    env={"DB_URL": "crate://crate@localhost:4200/?schema=testdrive"},
+)
+
+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 content.
+            db = DatabaseAdapter("crate://crate@localhost:4200/")
+            db.run_sql("CREATE TABLE IF NOT EXISTS mcp_alchemy (id INT, data TEXT)")
+            db.run_sql("INSERT INTO mcp_alchemy (id, data) VALUES (42, 'Hotzenplotz')")
+            db.refresh_table("mcp_alchemy")
+
+            # Call a few tools.
+            await client.call_tool("execute_query", arguments={"query": "SELECT * FROM sys.summits ORDER BY height DESC LIMIT 3"})
+            await client.call_tool("all_table_names", arguments={})
+            await client.call_tool("filter_table_names", arguments={"q": "mcp"})
+            await client.call_tool("schema_definitions", arguments={"table_names": ["mcp_alchemy"]})
+
+
+if __name__ == "__main__":
+    import asyncio
+
+    asyncio.run(run())

framework/mcp/requirements.txt

@@ -1,2 +1,5 @@
 cratedb-toolkit
 mcp<1.5
+mcp-alchemy @ git+https://github.com/runekaagaard/mcp-alchemy.git@f42aaf0
+sqlalchemy-cratedb>=0.42.0.dev1
+where

framework/mcp/test.py

@@ -116,3 +116,40 @@ def test_dbhub():
     assert b"Getting prompt: explain_db" in p.stdout
     assert b"Table: mcp_dbhub in schema 'testdrive'" in p.stdout
     assert b"Structure:\\n- id (integer)\\n- data (text)" in p.stdout
+
+
+def test_mcp_alchemy():
+    """
+    Validate the MCP Alchemy server works well.
+
+    MCP Alchemy connects Claude Desktop directly to your databases.
+    MCP Alchemy is a MCP (model context protocol) server that gives the LLM access
+    to and knowledge about relational databases like SQLite, Postgresql, MySQL &
+    MariaDB, Oracle, MS-SQL, and CrateDB.
+
+    It is written in Python and uses SQLAlchemy.
+    https://github.com/runekaagaard/mcp-alchemy
+    """
+    p = run(f"{sys.executable} example_mcp_alchemy.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: execute_query" in p.stdout
+    assert b"mountain: Mont Blanc" in p.stdout
+
+    assert b"Calling tool: all_table_names" in p.stdout
+    assert b"mcp_alchemy" in p.stdout
+
+    assert b"Calling tool: filter_table_names" in p.stdout
+    assert b"mcp_alchemy" in p.stdout
+
+    assert b"Calling tool: schema_definitions" in p.stdout
+    assert b"id: INTEGER, nullable" in p.stdout
+    assert b"data: VARCHAR, nullable" in p.stdout