mcp-server-motherduck 0.2.1__tar.gz → 0.3__tar.gz

mcp_server_motherduck-0.3/.github/workflows/python-publish.yml

@@ -0,0 +1,33 @@
+name: Upload Python Package
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+  
+jobs:
+  pypi-publish:
+    name: python
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: "Set up Python"
+        uses: actions/setup-python@v5
+        with:
+          python-version-file: "pyproject.toml"
+
+      - name: Install the project
+        run: uv sync
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish package
+        run: uv publish

{mcp_server_motherduck-0.2.1 → mcp_server_motherduck-0.3}/.gitignore

@@ -1,3 +1,5 @@
+.DS_Store
+
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[cod]
@@ -94,6 +96,12 @@ ipython_config.py
 #   install all needed dependencies.
 #Pipfile.lock
 
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
 # poetry
 #   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
 #   This is especially recommended for binary packages to ensure reproducibility, and is more
@@ -106,8 +114,10 @@ ipython_config.py
 #pdm.lock
 #   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
 #   in version control.
-#   https://pdm.fming.dev/#use-with-ide
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
 .pdm.toml
+.pdm-python
+.pdm-build/
 
 # PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
 __pypackages__/
@@ -159,34 +169,8 @@ cython_debug/
 #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
 #.idea/
 
-# General
-.DS_Store
-.AppleDouble
-.LSOverride
-.idea/
-
-# Icon must end with two \r
-Icon
-
-# Thumbnails
-._*
-
-# Files that might appear in the root of a volume
-.DocumentRevisions-V100
-.fseventsd
-.Spotlight-V100
-.TemporaryItems
-.Trashes
-.VolumeIcon.icns
-.com.apple.timemachine.donotpresent
-
-# Directories potentially created on remote AFP share
-.AppleDB
-.AppleDesktop
-Network Trash Folder
-Temporary Items
-.apdisk
-
-# Node
-node_modules/
-dist/
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc

mcp_server_motherduck-0.3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 MotherDuck
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mcp_server_motherduck-0.3/PKG-INFO

@@ -0,0 +1,62 @@
+Metadata-Version: 2.4
+Name: mcp-server-motherduck
+Version: 0.3
+Summary: A MCP server for MotherDuck and local DuckDB
+Author-email: tdoehmen <till@motherduck.com>
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: duckdb>=1.1.3
+Requires-Dist: mcp>=1.0.0
+Description-Content-Type: text/markdown
+
+# mcp-server-motherduck MCP server
+
+An [MCP server](https://modelcontextprotocol.io/introduction) for MotherDuck and local DuckDB.
+
+## Components
+
+### Prompts
+
+The server provides one prompt:
+
+- duckdb-motherduck-prompt: A prompt to initialize a connection to duckdb or motherduck and start working with it
+
+### Tools
+
+The server offers one tool:
+
+- query: Execute a query on the MotherDuck (DuckDB) database
+  - Takes "query" as required string arguments
+
+This is because all the interactions with both the DuckDB and MotherDuck are done through writing SQL queries.
+
+## Usage with Claude Desktop
+
+Add the snippet below to your Claude Desktop config and make sure to set the HOME var to your home folder (needed by DuckDB).
+
+When using MotherDuck, you also need to set a [MotherDuck token](https://motherduck.com/docs/key-tasks/authenticating-and-connecting-to-motherduck/authenticating-to-motherduck/#storing-the-access-token-as-an-environment-variable) env var.
+
+On MacOS: `~/Library/Application\ Support/Claude/claude_desktop_config.json`
+
+On Windows: `%APPDATA%/Claude/claude_desktop_config.json`
+
+### Servers Configuration
+
+```
+"mcpServers": {
+  "mcp-server-motherduck": {
+    "command": "uvx",
+    "args": [
+      "mcp-server-motherduck"
+    ],
+    "env": {
+      "motherduck_token": "<your-motherduck-token>",
+      "HOME": "<your-home-folder-for-project-files>"
+    }
+  }
+}
+```
+
+## License
+
+This MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.

mcp_server_motherduck-0.3/README.md

@@ -0,0 +1,51 @@
+# mcp-server-motherduck MCP server
+
+An [MCP server](https://modelcontextprotocol.io/introduction) for MotherDuck and local DuckDB.
+
+## Components
+
+### Prompts
+
+The server provides one prompt:
+
+- duckdb-motherduck-prompt: A prompt to initialize a connection to duckdb or motherduck and start working with it
+
+### Tools
+
+The server offers one tool:
+
+- query: Execute a query on the MotherDuck (DuckDB) database
+  - Takes "query" as required string arguments
+
+This is because all the interactions with both the DuckDB and MotherDuck are done through writing SQL queries.
+
+## Usage with Claude Desktop
+
+Add the snippet below to your Claude Desktop config and make sure to set the HOME var to your home folder (needed by DuckDB).
+
+When using MotherDuck, you also need to set a [MotherDuck token](https://motherduck.com/docs/key-tasks/authenticating-and-connecting-to-motherduck/authenticating-to-motherduck/#storing-the-access-token-as-an-environment-variable) env var.
+
+On MacOS: `~/Library/Application\ Support/Claude/claude_desktop_config.json`
+
+On Windows: `%APPDATA%/Claude/claude_desktop_config.json`
+
+### Servers Configuration
+
+```
+"mcpServers": {
+  "mcp-server-motherduck": {
+    "command": "uvx",
+    "args": [
+      "mcp-server-motherduck"
+    ],
+    "env": {
+      "motherduck_token": "<your-motherduck-token>",
+      "HOME": "<your-home-folder-for-project-files>"
+    }
+  }
+}
+```
+
+## License
+
+This MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.

mcp_server_motherduck-0.3/makefile

@@ -0,0 +1,6 @@
+.ONESHELL:
+
+.PHONY: publish
+
+publish:
+	uv publish --token $(PYPI_KEY)

{mcp_server_motherduck-0.2.1 → mcp_server_motherduck-0.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mcp-server-motherduck"
-version = "0.2.1"
+version = "0.3"
 description = "A MCP server for MotherDuck and local DuckDB"
 readme = "README.md"
 requires-python = ">=3.10"

mcp_server_motherduck-0.3/src/mcp_server_motherduck/__init__.py

@@ -0,0 +1,19 @@
+from . import server
+import asyncio
+import argparse
+
+
+def main():
+    """Main entry point for the package."""
+    parser = argparse.ArgumentParser(description="MotherDuck MCP Server")
+    parser.add_argument(
+        "--db-path",
+        help="Path to local DuckDB database file",
+    )
+
+    args = parser.parse_args()
+    asyncio.run(server.main(db_path=args.db_path))
+
+
+# Optionally expose other important items at package level
+__all__ = ["main", "server"]

mcp_server_motherduck-0.2.1/src/mcp_server_motherduck/server.py → mcp_server_motherduck-0.3/src/mcp_server_motherduck/prompt.py

@@ -1,32 +1,20 @@
-import asyncio
-
-from mcp.server.models import InitializationOptions
-import mcp.types as types
-from mcp.server import NotificationOptions, Server
-from pydantic import AnyUrl
-import mcp.server.stdio
-import os
-import duckdb
-
-PROMPT_TEMPLATE = """
-The assistant's goal is to help users interact with DuckDB/MotherDuck databases effectively. 
+PROMPT_TEMPLATE = """The assistant's goal is to help users interact with DuckDB or MotherDuck databases effectively. 
 Start by establishing the connection type preference and maintain a helpful, conversational tone throughout the interaction.
+
 <mcp>
 Tools:
-- "initialize-connection": Creates connection to DuckDB or MotherDuck
-- "read-schemas": Retrieves table schemas from specified database
-- "execute-query": Runs SQL queries and returns results
+- "query": Runs SQL queries and returns results
 </mcp>
 
 <workflow>
 1. Connection Setup:
    - Ask whether user prefers MotherDuck or local DuckDB
-   - Use initialize-connection with chosen type
+   - Use query with the chosen type
    - Store and display available databases if successful
 
 2. Database Exploration:
    - When user mentions data analysis needs, identify target database
-   - Use read-schemas to fetch table information
+   - Use query to fetch table information
    - Present schema details in user-friendly format
 
 3. Query Execution:
@@ -49,7 +37,7 @@ Tools:
 </workflow>
 
 <conversation-flow>
-1. Start with: "Hi! Would you prefer to connect to MotherDuck or use a local DuckDB instance?"
+1. Start with: "Hi! What query would you like to run on your database?"
 
 2. After connection:
    - Acknowledge success/failure
@@ -112,7 +100,7 @@ Here are some DuckDB SQL syntax specifics you should be aware of:
 - DuckDB has built-in functions for regex regexp_matches(column, regex), regexp_replace(column, regex), and regexp_extract(column, regex).
 - DuckDB has a way to quickly get a subset of your data with `SELECT * FROM large_table USING SAMPLE 10%;`
 
-DuckDB Functions:
+Common DuckDB Functions:
 `count`: Calculates the total number of rows returned by a SQL query result. This function is commonly used to determine the row count of a SELECT operation., Parameters: ['result: The result object']
 `sum`: Calculates the total of all non-null values in a specified column or expression across rows., Parameters: ['arg: Values to be aggregated']
 `max`: Returns the largest value from all values in a specified column or expression., Parameters: ['arg: expression to evaluate maximum', "n: top 'n' value list size(optional)"]
@@ -143,7 +131,7 @@ DuckDB Functions:
 `now`: Obtains the current date and time at the start of the current transaction, using the system's time zone., Parameters: ['None: No parameters required(optional)']
 `group_concat`: Concatenates column string values using a specified separator, respecting the provided order., Parameters: ['arg: The column to concatenate', 'sep: Separator between concatenated values(optional)', 'ORDER BY: Specifies order of concatenation(optional)']
 
-DuckDB Statements:
+Common DuckDB Statements:
 `FROM`: The FROM clause specifies the source of the data for the query. It can include a single table, multiple joined tables, or subqueries. The JOIN clause is used to combine rows from two or more tables based on a related column between them. There are several types of joins, including INNER, OUTER, CROSS, NATURAL, SEMI, ANTI, LATERAL, POSITIONAL, ASOF, and self-joins., Examples: ['SELECT * FROM table_name;', 'FROM table_name SELECT *;', 'FROM table_name;', 'SELECT tn.* FROM table_name tn;', 'SELECT * FROM schema_name.table_name;', 'SELECT t.i FROM range(100) AS t(i);', "SELECT * FROM 'test.csv';", 'SELECT * FROM (SELECT * FROM table_name);', 'SELECT t FROM t;', "SELECT t FROM (SELECT unnest(generate_series(41, 43)) AS x, 'hello' AS y) t;", 'SELECT * FROM table_name JOIN other_table ON table_name.key = other_table.key;', 'SELECT * FROM table_name TABLESAMPLE 10%;', 'SELECT * FROM table_name TABLESAMPLE 10 ROWS;', 'FROM range(100) AS t(i) SELECT sum(t.i) WHERE i % 2 = 0;', 'SELECT a.*, b.* FROM a CROSS JOIN b;', 'SELECT a.*, b.* FROM a, b;', 'SELECT n.*, r.* FROM l_nations n JOIN l_regions r ON (n_regionkey = r_regionkey);', 'SELECT * FROM city_airport NATURAL JOIN airport_names;', 'SELECT * FROM city_airport JOIN airport_names USING (iata);', 'SELECT * FROM city_airport SEMI JOIN airport_names USING (iata);', 'SELECT * FROM city_airport WHERE iata IN (SELECT iata FROM airport_names);', 'SELECT * FROM city_airport ANTI JOIN airport_names USING (iata);', 'SELECT * FROM city_airport WHERE iata NOT IN (SELECT iata FROM airport_names WHERE iata IS NOT NULL);', 'SELECT * FROM range(3) t(i), LATERAL (SELECT i + 1) t2(j);', 'SELECT * FROM generate_series(0, 1) t(i), LATERAL (SELECT i + 10 UNION ALL SELECT i + 100) t2(j);', 'SELECT * FROM trades t ASOF JOIN prices p ON t.symbol = p.symbol AND t.when >= p.when;', 'SELECT * FROM trades t ASOF LEFT JOIN prices p ON t.symbol = p.symbol AND t.when >= p.when;', 'SELECT * FROM trades t ASOF JOIN prices p USING (symbol, "when");', 'SELECT t.symbol, t.when AS trade_when, p.when AS price_when, price FROM trades t ASOF LEFT JOIN prices p USING (symbol, "when");', 'SELECT * FROM t AS t t1 JOIN t t2 USING(x);', 'FROM tbl SELECT i, s;', 'FROM tbl;']
 `SELECT`: The SELECT statement retrieves rows from the database. It is used to query the database and retrieve data according to specific requirements. The statement can include several clauses, such as FROM, WHERE, GROUP BY, ORDER BY, and LIMIT, to filter, organize, and limit the query results., Examples: ['SELECT * FROM tbl;', 'SELECT j FROM tbl WHERE i = 3;', 'SELECT i, sum(j) FROM tbl GROUP BY i;', 'SELECT * FROM tbl ORDER BY i DESC LIMIT 3;', 'SELECT * FROM t1 JOIN t2 USING (a, b);', 'SELECT #1, #3 FROM tbl;', 'SELECT DISTINCT city FROM addresses;', 'SELECT d FROM (SELECT 1 AS a, 2 AS b) d;', 'SELECT rowid, id, content FROM t;']
 `WHERE`: The WHERE clause specifies filters to apply to the data being queried, allowing selection of a specific subset of data. It is logically applied immediately after the FROM clause in a SQL query., Examples: ['SELECT * FROM table_name WHERE id = 3;', "SELECT * FROM table_name WHERE name ILIKE '%mark%';", 'SELECT * FROM table_name WHERE id = 3 OR id = 7;']
@@ -172,7 +160,7 @@ DuckDB Statements:
 `PIVOT`: The PIVOT statement in DuckDB allows distinct values within a column to be transformed into their own columns. The values within these new columns are calculated using an aggregate function on the subset of rows matching each distinct value. DuckDB supports both the SQL Standard PIVOT syntax, which requires explicit column names, and a simplified PIVOT syntax that can automatically detect which columns to create. The PIVOT statement is useful for reshaping data for analysis, similar to the way pivot tables work in spreadsheet software., Examples: ['PIVOT Cities ON Year USING sum(Population);', 'PIVOT Cities ON Year USING first(Population);', 'PIVOT Cities ON Year USING sum(Population) GROUP BY Country;', 'PIVOT Cities ON Year IN (2000, 2010) USING sum(Population) GROUP BY Country;', 'PIVOT Cities ON Country, Name USING sum(Population);', "PIVOT Cities ON Country || '_' || Name USING sum(Population);", 'PIVOT Cities ON Year USING sum(Population) AS total, max(Population) AS max GROUP BY Country;', 'PIVOT Cities ON Year USING sum(Population) GROUP BY Country, Name;', 'SELECT * FROM (PIVOT Cities ON Year USING sum(Population) GROUP BY Country) pivot_alias;']
 `FILTER`: The FILTER clause is used in conjunction with aggregate functions within a SELECT statement to filter the input data specifically for the aggregate function. This allows for conditions to be applied similar to a WHERE clause, but localized to the aggregate function. It is useful for scenarios like pivoting data and handling null values cleanly, particularly with functions like 'first', 'last', 'list', and 'array_agg'. FILTER cannot be used in window functions., Examples: ['SELECT count(*) FILTER (i <= 5) AS lte_five FROM generate_series(1, 10) tbl(i);', 'SELECT sum(i) FILTER (i <= 5) AS lte_five_sum FROM generate_series(1, 10) tbl(i);', 'SELECT count(i) FILTER (year = 2022) AS "2022" FROM stacked_data;', 'SELECT first(i) FILTER (year = 2022) AS "2022" FROM stacked_data;']
 
-DuckDB Types:
+Common DuckDB Types:
 `VARCHAR`: `VARCHAR` is a versatile data type used to store variable-length character strings, accommodating a wide range of text and string data without enforcing a specific length., Examples: ['CREATE TABLE people (name VARCHAR, age INTEGER);', "INSERT INTO documents (text) VALUES ('This is a VARCHAR example text.');", "SELECT * FROM employees WHERE department = 'Engineering';", 'ALTER TABLE students ADD COLUMN email VARCHAR;', "UPDATE orders SET status = 'Shipped' WHERE order_id = 102;", "COPY products TO 'products.csv' DELIMITER ',' HEADER;"]
 `INTEGER`: The INTEGER data type, with aliases such as int, signed, int4, int32, integer, and integral, represents whole numbers and is commonly used to store numeric data without fractional components., Examples: ['-- Assigning integer values to columns in a CREATE TABLE statement\nCREATE TABLE my_table (id INTEGER, age INTEGER);', '-- Inserting integer values as literals within an INSERT statement\nINSERT INTO my_table VALUES (1, 25);', '-- Using integer operations in a SELECT statement\nSELECT id + 10 AS new_id FROM my_table;', '-- Casting a float to an integer\nSELECT CAST(3.7 AS INTEGER) AS whole_number;', '-- Defining a column to only accept non-negative integers using a CHECK constraint\nCREATE TABLE my_table (id INTEGER CHECK (id >= 0));', '-- Using the INTEGER type in a primary key definition\nCREATE TABLE users (user_id INTEGER PRIMARY KEY, username VARCHAR);', '-- Updating integer columns\nUPDATE my_table SET age = age + 1 WHERE id = 1;', '-- Comparing integer values in a WHERE clause\nSELECT * FROM my_table WHERE age > 20;']
 `NULL`: The `NULL` type in SQL represents a missing or unknown value, allowing for fields within a table to be uninitialized or absent in data., Examples: ['SELECT NULL = NULL;', 'SELECT NULL IS NULL;', "INSERT INTO table_name (column1, column2) VALUES (NULL, 'data');", "SELECT coalesce(NULL, 'default_value');", 'UPDATE table_name SET column1 = NULL WHERE condition;', "SELECT CASE WHEN column IS NULL THEN 'Value is NULL' ELSE column END FROM table_name;"]
@@ -197,194 +185,11 @@ DuckDB Types:
 `SMALLINT`: The SMALLINT type, with aliases such as short, int2, smallint, and int16, represents a signed two-byte integer that can store whole numbers ranging from -32768 to 32767., Examples: ['CREATE TABLE test_table (id SMALLINT);', 'INSERT INTO test_table (id) VALUES (100);', 'SELECT * FROM test_table WHERE id BETWEEN -100 AND 100;', 'ALTER TABLE test_table ADD COLUMN new_column SMALLINT;', 'UPDATE test_table SET id = id + 1 WHERE id < 32767;']
 `BLOB`: The BLOB (Binary Large Object) type represents a variable-length binary data object, used for storing arbitrary binary data in the database, such as images or files, without any interpretation of its contents., Examples: ["-- Create a BLOB with a single byte\\nSELECT '\\xAA'::BLOB;\\n-- Result: \\xAA\\n\\n-- Create a BLOB with multiple bytes\\nSELECT '\\xAA\\xAB\\xAC'::BLOB;\\n-- Result: \\xAA\\xAB\\xAC\\n\\n-- Concatenate two BLOB values\\nSELECT '\\xAA'::BLOB || '\\xBB'::BLOB;\\n-- Result: \\xAABB\\n\\n-- Convert a BLOB to a hexadecimal string\\nSELECT hex('\\xAA\\xBB'::BLOB);\\n-- Result: AABB\\n\\n-- Decode a BLOB to a string, ensuring it is valid UTF-8\\nSELECT decode('\\xC3\\xBC'::BLOB);\\n-- Result: ü\\n\\n-- Read a BLOB from a file\\nSELECT read_blob('myfile.bin');\\n-- Result: Contents of 'myfile.bin' as a BLOB"]
 
-DuckDB Other Keywords:
-`SELECT`: The `SELECT` statement is used to query and retrieve data from tables, allowing for specification of columns, conditions, and data transformations., Examples: ['SELECT * FROM table_name;', 'SELECT column1, column2 FROM table_name WHERE condition;', 'SELECT DISTINCT column1 FROM table_name;', 'SELECT column1, COUNT(*) FROM table_name GROUP BY column1;', 'SELECT column1, column2 FROM table_name ORDER BY column1 DESC;', 'SELECT column1 AS alias FROM table_name;', 'SELECT t1.column1, t2.column2 FROM table1 t1 JOIN table2 t2 ON t1.id = t2.id;', 'SELECT column1 FROM table_name WHERE column2 IN (SELECT column2 FROM other_table);']
-`FROM`: The FROM clause is used to specify the data source for a SQL query, which can be a single table, a combination of tables joined together, or a subquery, and can optionally use a FROM-first syntax allowing query formation without a SELECT clause., Examples: ['SELECT * FROM table_name;', 'FROM table_name SELECT *;', 'FROM table_name;', 'SELECT tn.* FROM table_name tn;', 'SELECT * FROM schema_name.table_name;', 'SELECT t.i FROM range(100) AS t(i);', "SELECT * FROM 'test.csv';", 'SELECT * FROM (SELECT * FROM table_name);', 'SELECT t FROM t;', "SELECT t FROM (SELECT unnest(generate_series(41, 43)) AS x, 'hello' AS y) t;", 'SELECT * FROM table_name JOIN other_table ON table_name.key = other_table.key;', 'SELECT * FROM table_name TABLESAMPLE 10%;', 'SELECT * FROM table_name TABLESAMPLE 10 ROWS;', 'FROM range(100) AS t(i) SELECT sum(t.i) WHERE i % 2 = 0;']
+Common DuckDB Keywords:
 `AS`: The `AS` keyword in SQL is used to create an alias for columns or tables, helping to simplify query logic and improve readability., Examples: ['SELECT first_name AS name FROM employees;', 'SELECT department AS dept FROM company;', 'CREATE VIEW sales_report AS SELECT * FROM sales WHERE year = 2023;', 'SELECT product_name AS name, SUM(sales) AS total_sales FROM store GROUP BY product_name;', 'SELECT c.customer_id, c.name AS customer_name, o.order_id, o.total_amount AS amount FROM customers c INNER JOIN orders o ON c.customer_id = o.customer_id;']
-`BY`: "by" is used in SQL to specify sorting or grouping columns for organizing query results, such as in "ORDER BY" or "PARTITION BY" clauses., Examples: ['SELECT row_number() OVER (ORDER BY time) FROM sales;', 'SELECT amount - lag(amount) OVER (ORDER BY time) FROM sales;', 'SELECT amount / sum(amount) OVER (PARTITION BY region) FROM sales;', 'SELECT * FROM tbl ORDER BY column_name ASC;', 'SELECT MIN(salary) FROM employees GROUP BY department;']
-`AND`: "AND" is a logical operator used to combine multiple conditions in SQL queries, returning true only if all conditions are true., Examples: ["SELECT * FROM employees WHERE department = 'Sales' AND salary > 50000;", "SELECT * FROM orders WHERE order_date >= '2023-01-01' AND status = 'Pending';", "SELECT * FROM customers WHERE age > 21 AND city = 'New York';", "SELECT * FROM products WHERE category = 'Electronics' AND stock_quantity > 0;", "SELECT * FROM students WHERE grade = 'A' AND attendance_percentage > 90;"]
-`WHERE`: The `WHERE` clause in SQL is used to filter records that satisfy a specified boolean condition, determining which rows are returned in the result set., Examples: ["SELECT * FROM weather WHERE city = 'San Francisco' AND prcp > 0.0;", 'SELECT city, max(temp_lo) FROM weather GROUP BY city HAVING max(temp_lo) < 40;', "UPDATE weather SET temp_hi = temp_hi - 2, temp_lo = temp_lo - 2 WHERE date > '1994-11-28';", "DELETE FROM weather WHERE city = 'Hayward';"]
-`OR`: The `ORDER BY` clause sorts query results based on specified columns or expressions, with optional ascending or descending order and handling of NULL values., Examples: ['SELECT * FROM addresses ORDER BY city;', 'SELECT * FROM addresses ORDER BY city DESC NULLS LAST;', 'SELECT * FROM addresses ORDER BY city, zip;', 'SELECT * FROM addresses ORDER BY city COLLATE DE;', 'SELECT * FROM addresses ORDER BY ALL;', 'SELECT * FROM addresses ORDER BY ALL DESC;']
-`TABLE`: The `CREATE TABLE` statement in SQL is used to define a new table along with its columns and constraints, such as specifying data types, primary keys, unique constraints, and check constraints, among other options., Examples: ['CREATE TABLE t1 (i INTEGER, j INTEGER);', 'CREATE TABLE t1 (id INTEGER PRIMARY KEY, j VARCHAR);', 'CREATE TABLE t1 (id INTEGER, j VARCHAR, PRIMARY KEY (id, j));', 'CREATE TABLE t1 (i INTEGER NOT NULL, decimalnr DOUBLE CHECK (decimalnr < 10), date DATE UNIQUE, time TIMESTAMP);', 'CREATE TABLE t1 AS SELECT 42 AS i, 84 AS j;', "CREATE TABLE t1 AS FROM read_csv('path/file.csv');", 'CREATE TABLE t1 AS FROM t2 LIMIT 0;', "CREATE TEMP TABLE t1 AS SELECT * FROM read_csv('path/file.csv');", 'CREATE OR REPLACE TABLE t1 (i INTEGER, j INTEGER);', 'CREATE TABLE IF NOT EXISTS t1 (i INTEGER, j INTEGER);']
-`JOIN`: Joins are essential operations in SQL for combining tables based on related columns, helping to establish relationships and derive meaningful insights from separate datasets., Examples: ['SELECT * FROM table1 JOIN table2 ON table1.id = table2.id;', 'SELECT a.*, b.* FROM a LEFT JOIN b ON a.id = b.id;', 'SELECT * FROM a NATURAL JOIN b;', 'SELECT * FROM table1 CROSS JOIN table2;', 'SELECT * FROM table1 LEFT OUTER JOIN table2 ON table1.id = table2.id;', 'SELECT * FROM orders INNER JOIN customers ON orders.customer_id = customers.id;', 'SELECT t.*, s.value FROM table t LEFT LATERAL JOIN summary s ON t.id = s.id;', 'SELECT t.* FROM table1 t ANTI JOIN table2 s ON t.id = s.id;']
-`ON`: The `ON` keyword in SQL is used with various clauses and statements such as JOIN, UPDATE, DELETE, and ON CONFLICT to specify conditions for selecting, updating, or deleting rows that match specific criteria in relational databases., Examples: ['SELECT * FROM table1 INNER JOIN table2 ON table1.id = table2.id;', "UPDATE employees SET salary = salary * 1.1 ON department.id = employees.department_id WHERE department.name = 'Engineering';", "DELETE FROM orders WHERE orders.date < '2023-01-01' ON CONFLICT DO NOTHING;", "INSERT INTO products (id, name) VALUES (1, 'Widget') ON CONFLICT (id) DO UPDATE SET name = EXCLUDED.name;"]
-`NOT`: The `NOT` keyword in SQL is used to negate a condition, meaning it reverses the truth value of the condition it's used with., Examples: ['SELECT * FROM Students WHERE NOT (grade > 80);', 'SELECT * FROM Employees WHERE NOT EXISTS (SELECT * FROM Promotions WHERE Promotions.employee_id = Employees.id);', "SELECT * FROM Products WHERE NOT (name LIKE 'A%');", 'SELECT * FROM Orders WHERE order_date IS NOT NULL;', 'SELECT * FROM Library WHERE NOT (publication_year BETWEEN 1980 AND 2000);']
-`THEN`: The `FILTER` clause refines the input to an aggregate function in a `SELECT` statement, allowing different conditions for separate aggregates., Examples: ['SELECT count(*) AS total_rows, count(*) FILTER (i <= 5) AS lte_five, count(*) FILTER (i % 2 = 1) AS odds FROM generate_series(1, 10) tbl(i);', 'SELECT sum(i) FILTER (i <= 5) AS lte_five_sum, median(i) FILTER (i % 2 = 1) AS odds_median, median(i) FILTER (i % 2 = 1 AND i <= 5) AS odds_lte_five_median FROM generate_series(1, 10) tbl(i);', 'SELECT count(i) FILTER (year = 2022) AS "2022", count(i) FILTER (year = 2023) AS "2023", count(i) FILTER (year = 2024) AS "2024", count(i) FILTER (year = 2025) AS "2025", count(i) FILTER (year IS NULL) AS "NULLs" FROM stacked_data;', 'SELECT first(i) FILTER (year = 2022) AS "2022", first(i) FILTER (year = 2023) AS "2023", first(i) FILTER (year = 2024) AS "2024", first(i) FILTER (year = 2025) AS "2025", first(i) FILTER (year IS NULL) AS "NULLs" FROM stacked_data;']
-`END`: The FILTER clause is used to apply conditions to aggregate functions, allowing selective aggregation based on specific criteria within a SELECT statement., Examples: ['SELECT count(*) FILTER (i <= 5) AS lte_five FROM generate_series(1, 10) tbl(i);', 'SELECT sum(i) FILTER (i <= 5) AS lte_five_sum FROM generate_series(1, 10) tbl(i);', 'SELECT count(i) FILTER (year = 2022) AS "2022" FROM stacked_data;']
-`WHEN`: The `WHEN` keyword is used in a `CASE` statement to specify a condition that, if true, results in the execution of the corresponding expression., Examples: ["SELECT i, CASE WHEN i > 2 THEN 'Greater than 2' ELSE '2 or less' END FROM integers;", "SELECT i, CASE WHEN i = 1 THEN 'One' WHEN i = 2 THEN 'Two' ELSE 'Other' END FROM integers;", 'SELECT pretty_print_integer(n) AS result FROM numbers WHERE WHEN n > 1000 THEN true ELSE false;']
-`CASE`: The `CASE` statement in SQL is used for conditional logic in queries, allowing you to perform a switch based on a condition, similar to a ternary operator in programming languages., Examples: ['SELECT i, CASE WHEN i > 2 THEN 1 ELSE 0 END AS test FROM integers;', 'SELECT i, CASE WHEN i = 1 THEN 10 WHEN i = 2 THEN 20 ELSE 0 END AS test FROM integers;', 'SELECT i, CASE WHEN i = 1 THEN 10 END AS test FROM integers;', 'SELECT i, CASE i WHEN 1 THEN 10 WHEN 2 THEN 20 WHEN 3 THEN 30 END AS test FROM integers;']
-`NULL`: The NULL keyword in SQL represents a missing or unknown value, often used to indicate the absence of a definite value in a column., Examples: ["CREATE TABLE users (id INTEGER, name VARCHAR, age INTEGER); INSERT INTO users VALUES (1, 'Alice', NULL);", 'SELECT * FROM users WHERE age IS NULL;', 'UPDATE users SET age = 30 WHERE age IS NULL;', 'DELETE FROM users WHERE name IS NULL;', 'SELECT COALESCE(age, 0) AS age_with_default FROM users;', 'SELECT NULL = NULL; -- Returns NULL as NULL is not equal to anything, including itself', "SELECT ifnull(name, 'Unknown') FROM users -- Uses 'Unknown' if name is NULL;"]
 `DISTINCT`: The `DISTINCT` keyword is used in the SQL `SELECT` statement to ensure that only unique values are returned for specified columns, effectively removing duplicate rows from the result set., Examples: ['SELECT DISTINCT city FROM addresses;', 'SELECT DISTINCT ON(country) city, population FROM cities ORDER BY population DESC;']
-`DESC`: The keyword `desc` is used in SQL to describe the DESCENDING order in which query results should be sorted, often associated with the `ORDER BY` clause., Examples: ['SELECT name FROM employees ORDER BY salary DESC;', 'CREATE TABLE example (id INTEGER, name VARCHAR);', 'DESCRIBE example;', 'DESCRIBE SELECT * FROM example WHERE id < 10 ORDER BY name DESC;']
-`CREATE`: The `CREATE` keyword is used to define new database structures, such as tables or macros, in the SQL catalog., Examples: ['CREATE TABLE t1 (i INTEGER, j INTEGER);', "CREATE TEMP TABLE t1 AS SELECT * FROM read_csv('path/file.csv');", 'CREATE OR REPLACE TABLE t1 (i INTEGER, j INTEGER);', 'CREATE TABLE IF NOT EXISTS t1 (i INTEGER, j INTEGER);', 'CREATE TABLE nums AS SELECT i FROM range(0, 3) t(i);', 'CREATE TABLE t1 (x FLOAT, two_x AS (2 * x));', 'CREATE MACRO add(a, b) AS a + b;']
-`ORDER`: The `ORDER BY` clause is used to sort the rows returned by a SQL query based on specified columns, allowing for ascending or descending order and optional null order modifiers., Examples: ['SELECT * FROM addresses ORDER BY city;', 'SELECT * FROM addresses ORDER BY city DESC NULLS LAST;', 'SELECT * FROM addresses ORDER BY city, zip;', 'SELECT * FROM addresses ORDER BY city COLLATE DE;', 'SELECT * FROM addresses ORDER BY ALL;', 'SELECT * FROM addresses ORDER BY ALL DESC;']
-`ELSE`: The "ELSE" keyword in a CASE statement provides a default result when none of the "WHEN" conditions are met., Examples: ['SELECT i, CASE WHEN i > 2 THEN 1 ELSE 0 END AS test FROM integers;', 'SELECT i, CASE WHEN i = 1 THEN 10 WHEN i = 2 THEN 20 ELSE 0 END AS test FROM integers;', 'SELECT i, CASE WHEN i = 1 THEN 10 END AS test FROM integers;']
-`GROUP`: Grouping in SQL using clauses like GROUPING SETS, ROLLUP, and CUBE allows for performing aggregations across multiple dimensions within a single query., Examples: ['SELECT city, street_name, avg(income) FROM addresses GROUP BY GROUPING SETS ((city, street_name), (city), (street_name), ());', 'SELECT city, street_name, avg(income) FROM addresses GROUP BY CUBE (city, street_name);', 'SELECT city, street_name, avg(income) FROM addresses GROUP BY ROLLUP (city, street_name);', 'SELECT course, type, count(*) FROM students GROUP BY GROUPING SETS ((course, type), course, type, ());', 'SELECT y, q, m, GROUPING_ID(y, q, m) AS "grouping_id()" FROM days GROUP BY GROUPING SETS ((y, q, m), (y, q), (y), ()) ORDER BY y, q, m;']
-`IS`: The "IS" keyword is used in SQL to perform tests on values to check for NULL values or to use as part of statements like IS DISTINCT FROM which can handle NULLs in equality comparisons., Examples: ['SELECT 4 IS DISTINCT FROM NULL;', 'SELECT 4 IS NOT DISTINCT FROM 4;', 'SELECT NULL IS NULL;', 'SELECT NULL IS NOT NULL;']
-`REPLACE`: The `REPLACE` clause is used in a `SELECT` statement to replace specific columns with different expressions, effectively transforming the output of the `REPLACE` columns with the new specified expressions while retaining the rest of the columns unchanged., Examples: ['SELECT * REPLACE (lower(city) AS city) FROM addresses;', 'SELECT * REPLACE (col / 1000 AS col) FROM tbl;']
-`WITH`: The `WITH` clause allows defining common table expressions (CTEs) for simplifying complex queries by creating temporary result sets that can be referenced within the main SQL query., Examples: ['WITH cte AS (SELECT 42 AS x) SELECT * FROM cte;', 'WITH cte1 AS (SELECT 42 AS i), cte2 AS (SELECT i * 100 AS x FROM cte1) SELECT * FROM cte2;', 'WITH t(x) AS MATERIALIZED (SELECT * FROM t), SELECT * FROM t AS t1, t AS t2, t AS t3;', 'WITH RECURSIVE FibonacciNumbers AS (... recursive logic ...) SELECT ... FROM FibonacciNumbers;']
 `IN`: The `IN` keyword is used in SQL to specify a list of discrete values for a column to match against, typically in a `WHERE` clause, allowing for multiple specific conditions to be evaluated at once., Examples: ["SELECT * FROM employees WHERE department IN ('HR', 'Engineering', 'Marketing');", 'SELECT id, name FROM students WHERE grade IN (10, 11, 12);', "DELETE FROM orders WHERE order_status IN ('Cancelled', 'Returned');", "UPDATE items SET status = 'Unavailable' WHERE item_id IN (1001, 1002, 1003);", "SELECT * FROM logs WHERE severity IN ('ERROR', 'CRITICAL') ORDER BY timestamp DESC;"]
 `OVER`: The `OVER` clause in SQL specifies a window for evaluating window functions, allowing computations over a defined group of rows in a result set., Examples: ['SELECT row_number() OVER () FROM sales;', 'SELECT row_number() OVER (ORDER BY time) FROM sales;', 'SELECT row_number() OVER (PARTITION BY region ORDER BY time) FROM sales;', 'SELECT amount - lag(amount) OVER (ORDER BY time) FROM sales;', 'SELECT amount / sum(amount) OVER (PARTITION BY region) FROM sales;']
 `ALL`: The `ALL` keyword in SQL specifies that operations should retain all duplicate rows, as seen in commands like `UNION ALL`, `INTERSECT ALL`, and `EXCEPT ALL`, which follow bag semantics instead of eliminating duplicates., Examples: ['UNION ALL\n\n```sql\nSELECT * FROM range(2) t1(x)\nUNION ALL\nSELECT * FROM range(3) t2(x);\n```\nThis example demonstrates using `UNION ALL` to combine rows from two queries without eliminating duplicates.', 'INTERSECT ALL\n\n```sql\nSELECT unnest([5, 5, 6, 6, 6, 6, 7, 8]) AS x\nINTERSECT ALL\nSELECT unnest([5, 6, 6, 7, 7, 9]);\n```\nThis example shows using `INTERSECT ALL` to select rows that are present in both result sets, keeping duplicate values.', 'EXCEPT ALL\n\n```sql\nSELECT unnest([5, 5, 6, 6, 6, 6, 7, 8]) AS x\nEXCEPT ALL\nSELECT unnest([5, 6, 6, 7, 7, 9]);\n```\nThis example illustrates `EXCEPT ALL`, which selects all rows present in the first query but not in the second, without removing duplicates.', 'ORDER BY ALL\n\n```sql\nSELECT *\nFROM addresses\nORDER BY ALL;\n```\nThis SQL command uses `ORDER BY ALL` to sort the result set by all columns sequentially from left to right.']
 `LIKE`: The `LIKE` expression is used to determine if a string matches a specified pattern, allowing wildcard characters such as `_` to represent any single character and `%` to match any sequence of characters., Examples: ["SELECT 'abc' LIKE 'abc'; -- true", "SELECT 'abc' LIKE 'a%'; -- true", "SELECT 'abc' LIKE '_b_'; -- true", "SELECT 'abc' LIKE 'c'; -- false", "SELECT 'abc' LIKE 'c%'; -- false", "SELECT 'abc' LIKE '%c'; -- true", "SELECT 'abc' NOT LIKE '%c'; -- false", "SELECT 'abc' ILIKE '%C'; -- true"]
-`LEFT`: The `LEFT JOIN` keyword in SQL is used to combine rows from two or more tables based on a related column between them, but it will return all records from the left table and the matched records from the right table, with null values in columns of the right table where there is no match., Examples: ['SELECT customers.customer_id, orders.order_id FROM customers LEFT JOIN orders ON customers.customer_id = orders.customer_id;', 'SELECT city.name, weather.temp_lo FROM city LEFT JOIN weather ON city.name = weather.city;', 'SELECT a.id, b.value FROM table_a a LEFT JOIN table_b b ON a.id = b.a_id;', 'SELECT * FROM employees LEFT JOIN departments ON employees.department_id = departments.id;', 'SELECT students.name, grades.score FROM students LEFT JOIN grades ON students.id = grades.student_id WHERE grades.score IS NULL;']
 """
-
-server = Server("mcp-server-motherduck")
-
-conn = duckdb.connect()
-
-@server.list_resources()
-async def handle_list_resources() -> list[types.Resource]:
-    """
-    List available note resources.
-    Each note is exposed as a resource with a custom note:// URI scheme.
-    """
-    return []
-
-@server.read_resource()
-async def handle_read_resource(uri: AnyUrl) -> str:
-    """
-    Read a specific note's content by its URI.
-    The note name is extracted from the URI host component.
-    """
-    raise ValueError(f"Unsupported URI scheme: {uri.scheme}")
-
-@server.list_prompts()
-async def handle_list_prompts() -> list[types.Prompt]:
-    """
-    List available prompts.
-    Each prompt can have optional arguments to customize its behavior.
-    """
-    return [
-        types.Prompt(
-            name="duckdb-motherduck-initial-prompt",
-            description="A prompt to initialize a connection to duckdb or motherduck and start working with it",
-        )
-    ]
-
-@server.get_prompt()
-async def handle_get_prompt(
-        name: str, arguments: dict[str, str] | None
-) -> types.GetPromptResult:
-    """
-    Generate a prompt by combining arguments with server state.
-    The prompt includes all current notes and can be customized via arguments.
-    """
-    if name != "duckdb-motherduck-initial-prompt":
-        raise ValueError(f"Unknown prompt: {name}")
-
-    return types.GetPromptResult(
-        description=f"Initial prompt when interacting with DuckDB/MotherDuck",
-        messages=[
-            types.PromptMessage(
-                role="user",
-                content=types.TextContent(type="text", text=PROMPT_TEMPLATE),
-            )
-        ],
-    )
-
-@server.list_tools()
-async def handle_list_tools() -> list[types.Tool]:
-    """
-    List available tools.
-    Each tool specifies its arguments using JSON Schema validation.
-    """
-    return [
-        types.Tool(
-            name="initialize-connection",
-            description="Create a connection to either a local DuckDB or MotherDuck and retrieve available databases",
-            inputSchema={
-                "type": "object",
-                "properties": {
-                    "type": {"type": "string", "description": "Type of the database, either 'DuckDB' or 'MotherDuck'"},
-                },
-                "required": ["type"],
-            },
-        ),
-        types.Tool(
-            name="read-schemas",
-            description="Get table schemas from a specific DuckDB/MotherDuck database",
-            inputSchema={
-                "type": "object",
-                "properties": {
-                    "type": {"database_name": "string", "description": "name of the database"},
-                },
-                "required": ["database_name"],
-            },
-        ),
-        types.Tool(
-            name="execute-query",
-            description="Execute a query on the MotherDuck (DuckDB) database",
-            inputSchema={
-                "type": "object",
-                "properties": {
-                    "query": {"type": "string", "description": "SQL query to execute"},
-                },
-                "required": ["query"],
-            },
-        )
-    ]
-
-@server.call_tool()
-async def handle_call_tool(
-        name: str, arguments: dict | None
-) -> list[types.TextContent | types.ImageContent | types.EmbeddedResource]:
-    """
-    Handle tool execution requests.
-    Tools can modify server state and notify clients of changes.
-    """
-    global conn
-    if name == "initialize-connection":
-        type = arguments["type"].strip().upper()
-        if not type in ['DUCKDB', 'MOTHERDUCK']:
-            raise ValueError("Only 'DuckDB' or 'MotherDuck' are supported")
-        if type == 'MOTHERDUCK' and not os.getenv('motherduck_token'):
-            raise ValueError("Please set the `motherduck_token` environment variable.")
-        if type == 'MOTHERDUCK':
-            conn = duckdb.connect('md:')
-        elif type == 'DUCKDB':
-            conn = duckdb.connect()
-        databases = conn.execute("""select string_agg(database_name, ',\n')
-                                    from duckdb_databases() where database_name 
-                                    not in ('system', 'temp')""").fetchone()[0]
-        response = f'Connection to {type} successfully established. Here are the available databases: \n{databases}'
-        return [types.TextContent(type="text", text=response)]
-    if name == "read-schemas":
-        database = arguments["database_name"]
-        tables = conn.execute(f"""
-                    SELECT string_agg(regexp_replace(sql, 'CREATE TABLE ', 'CREATE TABLE '||database_name||'.'), '\n\n') as sql 
-                    FROM duckdb_tables()
-                    WHERE database_name = '{database}'""").fetchone()[0]
-        views = conn.execute(f"""
-                    SELECT string_agg(regexp_replace(sql, 'CREATE TABLE ', 'CREATE TABLE '||database_name||'.'), '\n\n') as sql 
-                    FROM duckdb_views()
-                    where schema_name not in ('information_schema', 'pg_catalog', 'localmemdb')
-                    and view_name not in ('duckdb_columns','duckdb_constraints','duckdb_databases','duckdb_indexes','duckdb_schemas','duckdb_tables','duckdb_types','duckdb_views','pragma_database_list','sqlite_master','sqlite_schema','sqlite_temp_master','sqlite_temp_schema')
-                    and database_name = '{database}'
-                    """).fetchone()[0]
-        results = f"Here are all tables: \n{tables} \n\n Here are all views: {views}"
-        return [types.TextContent(type="text", text=str(results))]
-    if name == "execute-query":
-        try:
-            results = conn.execute(arguments["query"]).fetchall()
-        except Exception as e:
-            raise ValueError('Error querying the database:'+str(e))
-        return [types.TextContent(type="text", text=str(results))]
-
-
-async def main():
-    # Run the server using stdin/stdout streams
-    async with mcp.server.stdio.stdio_server() as (read_stream, write_stream):
-        await server.run(
-            read_stream,
-            write_stream,
-            InitializationOptions(
-                server_name="motherduck",
-                server_version="0.1.0",
-                capabilities=server.get_capabilities(
-                    notification_options=NotificationOptions(),
-                    experimental_capabilities={},
-                ),
-            ),
-        )

mcp_server_motherduck-0.3/src/mcp_server_motherduck/server.py

@@ -0,0 +1,196 @@
+import os
+import logging
+import duckdb
+from pydantic import AnyUrl
+from typing import Literal
+import mcp.server.stdio
+import mcp.types as types
+from mcp.server import NotificationOptions, Server
+from mcp.server.models import InitializationOptions
+from .prompt import PROMPT_TEMPLATE
+
+SERVER_VERSION = "0.3"
+
+logger = logging.getLogger("mcp_server_motherduck")
+
+
+class DatabaseClient:
+    def __init__(self, db_path: str = None):
+        self.db_path, self.db_type = self._resolve_db_path_type(db_path)
+        self.conn = self._initialize_connection()
+
+    def _initialize_connection(self) -> duckdb.DuckDBPyConnection:
+        """Initialize connection to the MotherDuck or DuckDB database"""
+
+        logger.info(f"Connecting to {self.db_type} database: `{self.db_path}`")
+
+        return duckdb.connect(
+            self.db_path,
+            config={"custom_user_agent": f"mcp-server-motherduck/{SERVER_VERSION}"},
+        )
+
+    def _resolve_db_path_type(
+        self, db_path: str = None
+    ) -> tuple[str, Literal["duckdb", "motherduck"]]:
+        """Resolve and validate the database path"""
+        # Use MotherDuck if token is available and no path specified
+        if db_path is None and os.getenv("motherduck_token"):
+            logger.info("Using MotherDuck token to connect to database `md:`")
+            return "md:", "motherduck"
+
+        # Handle MotherDuck paths
+        if db_path and (db_path == "md:" or db_path.startswith("md:")):
+            if not os.getenv("motherduck_token"):
+                raise ValueError(
+                    "Please set the `motherduck_token` environment variable when using `md:` as db_path."
+                )
+            return db_path, "motherduck"
+
+        # Handle local database paths
+        if db_path:
+            if not os.path.exists(db_path):
+                raise FileNotFoundError(
+                    f"The database path `{db_path}` does not exist."
+                )
+            return db_path, "duckdb"
+
+        # Default to in-memory database
+        return ":memory:", "duckdb"
+
+    def query(self, query: str) -> str:
+        try:
+            return str(self.conn.execute(query).fetchall())
+        except Exception as e:
+            logger.error(f"Database error executing query: {e}")
+            raise ValueError(f"Error executing query: {e}")
+
+    def mcp_config(self) -> str:
+        """Used for debugging purposes to show the current MCP config"""
+        return {
+            "current_working_directory": os.getcwd(),
+            "database_type": self.db_type,
+            "database_path": self.db_path,
+        }
+
+
+async def main(db_path: str):
+    logger.info(f"Starting MotherDuck MCP Server with DB path: {db_path}")
+    server = Server("mcp-server-motherduck")
+    db_client = DatabaseClient(db_path=db_path)
+
+    logger.info("Registering handlers")
+
+    @server.list_resources()
+    async def handle_list_resources() -> list[types.Resource]:
+        """
+        List available note resources.
+        Each note is exposed as a resource with a custom note:// URI scheme.
+        """
+        logger.info("No resources available to list")
+        return []
+
+    @server.read_resource()
+    async def handle_read_resource(uri: AnyUrl) -> str:
+        """
+        Read a specific note's content by its URI.
+        The note name is extracted from the URI host component.
+        """
+        logger.info(f"Reading resource: {uri}")
+        raise ValueError(f"Unsupported URI scheme: {uri.scheme}")
+
+    @server.list_prompts()
+    async def handle_list_prompts() -> list[types.Prompt]:
+        """
+        List available prompts.
+        Each prompt can have optional arguments to customize its behavior.
+        """
+        logger.info("Listing prompts")
+        # TODO: Check where and how this is used, and how to optimize this.
+        # Check postgres and sqlite servers.
+        return [
+            types.Prompt(
+                name="duckdb-motherduck-initial-prompt",
+                description="A prompt to initialize a connection to duckdb or motherduck and start working with it",
+            )
+        ]
+
+    @server.get_prompt()
+    async def handle_get_prompt(
+        name: str, arguments: dict[str, str] | None
+    ) -> types.GetPromptResult:
+        """
+        Generate a prompt by combining arguments with server state.
+        The prompt includes all current notes and can be customized via arguments.
+        """
+        logger.info(f"Getting prompt: {name}::{arguments}")
+        # TODO: Check where and how this is used, and how to optimize this.
+        # Check postgres and sqlite servers.
+        if name != "duckdb-motherduck-initial-prompt":
+            raise ValueError(f"Unknown prompt: {name}")
+
+        return types.GetPromptResult(
+            description="Initial prompt for interacting with DuckDB/MotherDuck",
+            messages=[
+                types.PromptMessage(
+                    role="user",
+                    content=types.TextContent(type="text", text=PROMPT_TEMPLATE),
+                )
+            ],
+        )
+
+    @server.list_tools()
+    async def handle_list_tools() -> list[types.Tool]:
+        """
+        List available tools.
+        Each tool specifies its arguments using JSON Schema validation.
+        """
+        logger.info("Listing tools")
+        return [
+            types.Tool(
+                name="query",
+                description="Use this to execute a query on the MotherDuck or DuckDB database",
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "query": {
+                            "type": "string",
+                            "description": "SQL query to execute that is a dialect of DuckDB SQL",
+                        },
+                    },
+                    "required": ["query"],
+                },
+            ),
+        ]
+
+    @server.call_tool()
+    async def handle_tool_call(
+        name: str, arguments: dict | None
+    ) -> list[types.TextContent | types.ImageContent | types.EmbeddedResource]:
+        """
+        Handle tool execution requests.
+        Tools can modify server state and notify clients of changes.
+        """
+        logger.info(f"Calling tool: {name}::{arguments}")
+        try:
+            if name == "query":
+                tool_response = db_client.query(arguments["query"])
+                return [types.TextContent(type="text", text=str(tool_response))]
+
+        except Exception as e:
+            logger.error(f"Error executing tool {name}: {e}")
+            raise ValueError(f"Error executing tool {name}: {str(e)}")
+
+    # Run the server using stdin/stdout streams
+    async with mcp.server.stdio.stdio_server() as (read_stream, write_stream):
+        await server.run(
+            read_stream,
+            write_stream,
+            InitializationOptions(
+                server_name="motherduck",
+                server_version=SERVER_VERSION,
+                capabilities=server.get_capabilities(
+                    notification_options=NotificationOptions(),
+                    experimental_capabilities={},
+                ),
+            ),
+        )

{mcp_server_motherduck-0.2.1 → mcp_server_motherduck-0.3}/uv.lock

@@ -179,7 +179,7 @@ wheels = [
 
 [[package]]
 name = "mcp-server-motherduck"
-version = "0.2.1"
+version = "0.2.2"
 source = { editable = "." }
 dependencies = [
     { name = "duckdb" },

mcp_server_motherduck-0.2.1/PKG-INFO

@@ -1,115 +0,0 @@
-Metadata-Version: 2.3
-Name: mcp-server-motherduck
-Version: 0.2.1
-Summary: A MCP server for MotherDuck and local DuckDB
-Author-email: tdoehmen <till@motherduck.com>
-Requires-Python: >=3.10
-Requires-Dist: duckdb>=1.1.3
-Requires-Dist: mcp>=1.0.0
-Description-Content-Type: text/markdown
-
-# mcp-server-motherduck MCP server
-
-A MCP server for MotherDuck and local DuckDB 
-
-## Components
-
-### Resources
-
-### Prompts
-
-The server implements one prompt:
-- duckdb-motherduck-initial-prompt: A prompt to initialize a connection to duckdb or motherduck and start working with it
-
-### Tools
-
-The server implements three tools:
-- initialize-connection: Create a connection to either a local DuckDB or MotherDuck and retrieve available databases
-  - Takes "type" (DuckDB or MotherDuck) as input
-- read-schemas: Get table schemas from a specific DuckDB/MotherDuck database
-  - Takes "database_name" as required string arguments
-- execute-query: Execute a query on the MotherDuck (DuckDB) database
-  - Takes "query" as required string arguments
-
-## Configuration Claude Desktop
-
-Add the snippet below to your Claude Desktop config and make sure to set the HOME var to your home folder (needed by DuckDB). 
-
-When using MotherDuck, you also need to set a [MotherDuck token](https://motherduck.com/docs/key-tasks/authenticating-and-connecting-to-motherduck/authenticating-to-motherduck/#storing-the-access-token-as-an-environment-variable) env var.
-
-On MacOS: `~/Library/Application\ Support/Claude/claude_desktop_config.json`
-On Windows: `%APPDATA%/Claude/claude_desktop_config.json`
-
-### Servers Configuration
-```
-"mcpServers": {
-  "mcp-server-motherduck": {
-    "command": "uvx",
-    "args": [
-      "mcp-server-motherduck"
-    ],
-    "env": {
-      "motherduck_token": "",
-      "HOME": ""
-    }
-  }
-}
-```
-
-## Development
-
-### Building and Publishing
-
-To prepare the package for distribution:
-
-1. Sync dependencies and update lockfile:
-```bash
-uv sync
-```
-
-2. Build package distributions:
-```bash
-uv build
-```
-
-This will create source and wheel distributions in the `dist/` directory.
-
-3. Publish to PyPI:
-```bash
-uv publish
-```
-
-Note: You'll need to set PyPI credentials via environment variables or command flags:
-- Token: `--token` or `UV_PUBLISH_TOKEN`
-- Or username/password: `--username`/`UV_PUBLISH_USERNAME` and `--password`/`UV_PUBLISH_PASSWORD`
-
-### Debugging
-
-<details>
-  <summary>Development/Unpublished Servers Configuration</summary>
-  ```
-  "mcpServers": {
-    "mcp-server-motherduck": {
-      "command": "uv",
-      "args": [
-        "--directory",
-        "/Users/<username>/mcp-server/mcp-server-motherduck",
-        "run",
-        "mcp-server-motherduck"
-      ]
-    }
-  }
-  ```
-</details>
-
-Since MCP servers run over stdio, debugging can be challenging. For the best debugging
-experience, we strongly recommend using the [MCP Inspector](https://github.com/modelcontextprotocol/inspector).
-
-You can launch the MCP Inspector via [`npm`](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) with this command:
-
-```bash
-npx @modelcontextprotocol/inspector uv --directory /Users/<username>/mcp-server/mcp-server-motherduck run mcp-server-motherduck
-```
-
-
-Upon launching, the Inspector will display a URL that you can access in your browser to begin debugging.

mcp_server_motherduck-0.2.1/README.md

@@ -1,105 +0,0 @@
-# mcp-server-motherduck MCP server
-
-A MCP server for MotherDuck and local DuckDB 
-
-## Components
-
-### Resources
-
-### Prompts
-
-The server implements one prompt:
-- duckdb-motherduck-initial-prompt: A prompt to initialize a connection to duckdb or motherduck and start working with it
-
-### Tools
-
-The server implements three tools:
-- initialize-connection: Create a connection to either a local DuckDB or MotherDuck and retrieve available databases
-  - Takes "type" (DuckDB or MotherDuck) as input
-- read-schemas: Get table schemas from a specific DuckDB/MotherDuck database
-  - Takes "database_name" as required string arguments
-- execute-query: Execute a query on the MotherDuck (DuckDB) database
-  - Takes "query" as required string arguments
-
-## Configuration Claude Desktop
-
-Add the snippet below to your Claude Desktop config and make sure to set the HOME var to your home folder (needed by DuckDB). 
-
-When using MotherDuck, you also need to set a [MotherDuck token](https://motherduck.com/docs/key-tasks/authenticating-and-connecting-to-motherduck/authenticating-to-motherduck/#storing-the-access-token-as-an-environment-variable) env var.
-
-On MacOS: `~/Library/Application\ Support/Claude/claude_desktop_config.json`
-On Windows: `%APPDATA%/Claude/claude_desktop_config.json`
-
-### Servers Configuration
-```
-"mcpServers": {
-  "mcp-server-motherduck": {
-    "command": "uvx",
-    "args": [
-      "mcp-server-motherduck"
-    ],
-    "env": {
-      "motherduck_token": "",
-      "HOME": ""
-    }
-  }
-}
-```
-
-## Development
-
-### Building and Publishing
-
-To prepare the package for distribution:
-
-1. Sync dependencies and update lockfile:
-```bash
-uv sync
-```
-
-2. Build package distributions:
-```bash
-uv build
-```
-
-This will create source and wheel distributions in the `dist/` directory.
-
-3. Publish to PyPI:
-```bash
-uv publish
-```
-
-Note: You'll need to set PyPI credentials via environment variables or command flags:
-- Token: `--token` or `UV_PUBLISH_TOKEN`
-- Or username/password: `--username`/`UV_PUBLISH_USERNAME` and `--password`/`UV_PUBLISH_PASSWORD`
-
-### Debugging
-
-<details>
-  <summary>Development/Unpublished Servers Configuration</summary>
-  ```
-  "mcpServers": {
-    "mcp-server-motherduck": {
-      "command": "uv",
-      "args": [
-        "--directory",
-        "/Users/<username>/mcp-server/mcp-server-motherduck",
-        "run",
-        "mcp-server-motherduck"
-      ]
-    }
-  }
-  ```
-</details>
-
-Since MCP servers run over stdio, debugging can be challenging. For the best debugging
-experience, we strongly recommend using the [MCP Inspector](https://github.com/modelcontextprotocol/inspector).
-
-You can launch the MCP Inspector via [`npm`](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) with this command:
-
-```bash
-npx @modelcontextprotocol/inspector uv --directory /Users/<username>/mcp-server/mcp-server-motherduck run mcp-server-motherduck
-```
-
-
-Upon launching, the Inspector will display a URL that you can access in your browser to begin debugging.

mcp_server_motherduck-0.2.1/src/mcp_server_motherduck/__init__.py

@@ -1,9 +0,0 @@
-from . import server
-import asyncio
-
-def main():
-    """Main entry point for the package."""
-    asyncio.run(server.main())
-
-# Optionally expose other important items at package level
-__all__ = ['main', 'server']