From a03a763edd22b9ed478192d58715416a8880453a Mon Sep 17 00:00:00 2001 From: Andreas Motl Date: Sat, 17 May 2025 14:59:24 +0200 Subject: [PATCH 01/10] README: Refactoring. Emphasize AI assistant use per "Quickstart Guide" --- README.md | 128 ++++++++++++++++++++++++++++++++++--------------- pyproject.toml | 2 +- 2 files changed, 90 insertions(+), 40 deletions(-) diff --git a/README.md b/README.md index 462717f..0a1fad1 100644 --- a/README.md +++ b/README.md @@ -21,32 +21,93 @@ ## About -The CrateDB MCP Server is suitable for Text-to-SQL and documentation retrieval, -specializing on the CrateDB database. +The CrateDB MCP Server for natural language Text-to-SQL and documentation +retrieval specializes in CrateDB database clusters. The Model Context Protocol ([MCP]) is a protocol that standardizes providing -context to LLMs like Claude, ChatGPT, and MistralAI. +context to language models and AI assistants. -## Features +### Introduction -The CrateDB MCP Server lets these LLMs operate directly on CrateDB, enabling -use cases like: +The CrateDB Model Context Protocol (MCP) Server connects AI assistants directly +to your CrateDB clusters and the CrateDB knowledge base, enabling seamless +interaction through natural language. -- Answer questions about your data and database state. -- Help you debug and optimize queries directly on the database, for tasks - like optimizing queries using CrateDB-specific capabilities and syntax. -- Have general conversations about any details of CrateDB and CrateDB Cloud. +It serves as a bridge between AI tools and your analytics database, +allowing you to analyze data, the cluster state, troubleshoot issues, and +perform operations using conversational prompts. -To use an MCP server, you need a [client that supports] the protocol. The most -notable ones are Claude Desktop, ChatGPT desktop, OpenAI agents SDK, and Cursor. +**Experimental:** Please note that the CrateDB MCP Server is an experimental +feature provided as-is without warranty or support guarantees. Enterprise +customers should use this feature at their own discretion. -### Details +### Quickstart Guide + +The CrateDB MCP Server is compatible with AI assistants that support the Model +Context Protocol (MCP), either using standard input/output (stdio), +server-sent events (SSE), or HTTP Streams (streamable-http). + +To use the MCP server, you need a [client that supports] the protocol. The most +notable ones are ChatGPT, Claude, Cursor, GitHub Copilot, Mistral AI, +OpenAI Agents SDK, Windsurf, and others. + +The `uvx` launcher command is provided by the [uv] package manager. +The [installation docs](#install) section includes guidelines how to +install it on your machine. + +#### Claude, Cursor, Windsurf + +Add the following configuration to your AI assistant's settings to enable the +CrateDB MCP Server: +```json +{ + "mcpServers": { + "cratedb-mcp": { + "command": "uvx", + "args": ["cratedb-mcp", "serve"], + "env": { + "CRATEDB_CLUSTER_URL": "http://localhost:4200/", + "CRATEDB_MCP_TRANSPORT": "stdio" + } + } + } +} +``` + +#### VS Code Copilot Chat + +Add the following configuration to your VS Code settings: +```json +{ + "mcp": { + "servers": { + "cratedb-mcp": { + "command": "uvx", + "args": ["cratedb-mcp", "serve"], + "env": { + "CRATEDB_CLUSTER_URL": "http://localhost:4200/", + "CRATEDB_MCP_TRANSPORT": "stdio" + } + } + } + }, + "chat.mcp.enabled": true +} +``` + +## Handbook + +This section includes detailed information about how to configure and +operate the CrateDB MCP Server. + +### What's inside The application includes two independent subsystems: The Text-to-SQL API talks to a CrateDB database cluster, while the documentation server looks up guidelines specific to CrateDB topics based on user input on demand, for example, from , to provide the most accurate possible information. -Relevant information is relayed per [cratedb-outline.yaml]. +Relevant information is relayed per [cratedb-outline.yaml] through the +[cratedb-about] package. - Database / Text-to-SQL: `get_health`, `get_table_metadata`, `query_sql` - Documentation server: `get_cratedb_documentation_index`, `fetch_cratedb_docs` @@ -63,7 +124,7 @@ Remember that LLMs can still hallucinate and give incorrect answers. Please explore other [example questions] from a shared collection. -## Security considerations +### Security considerations **By default, the application will access the database in read-only mode.** @@ -73,7 +134,12 @@ All other operations will raise a `ValueError` exception, unless the `CRATEDB_MCP_PERMIT_ALL_STATEMENTS` environment variable is set to a truthy value. This is **not** recommended. -## Install +### Install + +The configuration snippets for AI assistants are using the `uvx` launcher +of the [uv] package manager to start the application ephemerally. +This section demonstrates how to install the application persistently. + ```shell uv tool install --upgrade cratedb-mcp ``` @@ -85,11 +151,11 @@ Notes: ``` - We recommend to use `uv tool install` to install the program "user"-wide into your environment so you can invoke it from anywhere across your terminal - sessions or MCP client programs like Claude. + sessions or MCP client programs / AI assistants. - If you are unable to use `uv tool install`, you can use `uvx cratedb-mcp` to acquire the package and run the application ephemerally. -## Configure +### Configure Configure the `CRATEDB_CLUSTER_URL` environment variable to match your CrateDB instance. For example, when connecting to CrateDB Cloud, use a value like @@ -109,7 +175,8 @@ in seconds. The `CRATEDB_MCP_DOCS_CACHE_TTL` environment variable (default: 3600) defines the cache lifetime for documentation resources in seconds. -## Usage +### Usage + Start MCP server with `stdio` transport (default). ```shell cratedb-mcp serve --transport=stdio @@ -125,24 +192,6 @@ cratedb-mcp serve --transport=streamable-http Alternatively, use the `CRATEDB_MCP_TRANSPORT` environment variable instead of the `--transport` option. -### Anthropic Claude -To use the MCP version within Claude Desktop, you can use the following configuration: - -```json -{ - "mcpServers": { - "my_cratedb": { - "command": "uvx", - "args": ["cratedb-mcp", "serve"], - "env": { - "CRATEDB_CLUSTER_URL": "http://localhost:4200/", - "CRATEDB_MCP_TRANSPORT": "stdio" - } - } - } -} -``` - ### Dry-run You can use [mcptools], a Swiss Army Knife for MCP Servers, to talk to the @@ -176,13 +225,14 @@ mcpt call \ uvx cratedb-mcp serve ``` -## Development +### Development To learn how to set up a development sandbox, see the [development documentation](./DEVELOP.md). -[client that supports]: https://modelcontextprotocol.io/clients#feature-support-matrix +[client that supports]: https://modelcontextprotocol.io/clients [CrateDB]: https://cratedb.com/database +[cratedb-about]: https://pypi.org/project/cratedb-about/ [cratedb-outline.yaml]: https://github.com/crate/about/blob/v0.0.4/src/cratedb_about/outline/cratedb-outline.yaml [example questions]: https://github.com/crate/about/blob/v0.0.4/src/cratedb_about/query/model.py#L17-L44 [MCP]: https://modelcontextprotocol.io/introduction diff --git a/pyproject.toml b/pyproject.toml index 997435d..103c6ba 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -7,7 +7,7 @@ requires = [ [project] name = "cratedb-mcp" -description = "CrateDB MCP Server for Text-to-SQL and documentation retrieval." +description = "CrateDB MCP Server for natural language Text-to-SQL and documentation retrieval." readme = "README.md" keywords = [ "cratedb", From 0b84d2acda62e18f4309b2056c26df4be639859f Mon Sep 17 00:00:00 2001 From: Andreas Motl Date: Sat, 17 May 2025 15:40:50 +0200 Subject: [PATCH 02/10] README: Copy-editing. This and that. --- README.md | 46 ++++++++++++++++++++++++++++++---------------- 1 file changed, 30 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 0a1fad1..c40a652 100644 --- a/README.md +++ b/README.md @@ -48,7 +48,7 @@ Context Protocol (MCP), either using standard input/output (stdio), server-sent events (SSE), or HTTP Streams (streamable-http). To use the MCP server, you need a [client that supports] the protocol. The most -notable ones are ChatGPT, Claude, Cursor, GitHub Copilot, Mistral AI, +notable ones are ChatGPT, Claude, Cline, Cursor, GitHub Copilot, Mistral AI, OpenAI Agents SDK, Windsurf, and others. The `uvx` launcher command is provided by the [uv] package manager. @@ -98,31 +98,42 @@ Add the following configuration to your VS Code settings: ## Handbook This section includes detailed information about how to configure and -operate the CrateDB MCP Server. +operate the CrateDB MCP Server, and to learn about the [MCP tools] it +provides. + +Tools are a powerful primitive in the Model Context Protocol (MCP) that enable +servers to expose executable functionality to clients. Through tools, LLMs can +interact with external systems, perform computations, and take actions in the +real world. ### What's inside -The application includes two independent subsystems: The Text-to-SQL API talks -to a CrateDB database cluster, while the documentation server looks up guidelines -specific to CrateDB topics based on user input on demand, for example, from -, to provide the most accurate possible information. -Relevant information is relayed per [cratedb-outline.yaml] through the -[cratedb-about] package. +The CrateDB MCP Server provides two families of tools. + +The **Text-to-SQL API** talks to a CrateDB database cluster to inquire database +and table metadata, and table content. +
+Tool names are: `get_health`, `get_table_metadata`, `query_sql` -- Database / Text-to-SQL: `get_health`, `get_table_metadata`, `query_sql` -- Documentation server: `get_cratedb_documentation_index`, `fetch_cratedb_docs` +The **Documentation API** looks up guidelines specific to CrateDB topics, +to provide the most accurate information possible. +Relevant information is pulled from , curated per +[cratedb-outline.yaml] through the [cratedb-about] package. +
+Tool names are: `get_cratedb_documentation_index`, `fetch_cratedb_docs` ### Examples -These are examples of questions that have been tested and validated by the team. -Remember that LLMs can still hallucinate and give incorrect answers. +We collected a few examples of questions that have been tested and validated by +the team, so you may also want to try them. Please remember that LLMs can still +hallucinate and give incorrect answers. * Optimize this query: "SELECT * FROM movies WHERE release_date > '2012-12-1' AND revenue" * Tell me about the health of the cluster * What is the storage consumption of my tables, give it in a graph. * How can I format a timestamp column to '2019 Jan 21'. -Please explore other [example questions] from a shared collection. +Please also explore the [example questions] from another shared collection. ### Security considerations @@ -137,8 +148,9 @@ truthy value. This is **not** recommended. ### Install The configuration snippets for AI assistants are using the `uvx` launcher -of the [uv] package manager to start the application ephemerally. -This section demonstrates how to install the application persistently. +of the [uv] package manager to start the application after installing it, +like the `npx` launcher is doing it for JavaScript and TypeScript applications. +This section uses `uv tool install` to install the application persistently. ```shell uv tool install --upgrade cratedb-mcp @@ -227,15 +239,17 @@ mcpt call \ ### Development -To learn how to set up a development sandbox, see the [development documentation](./DEVELOP.md). +To learn how to set up a development sandbox, see the [development documentation]. [client that supports]: https://modelcontextprotocol.io/clients [CrateDB]: https://cratedb.com/database [cratedb-about]: https://pypi.org/project/cratedb-about/ [cratedb-outline.yaml]: https://github.com/crate/about/blob/v0.0.4/src/cratedb_about/outline/cratedb-outline.yaml +[development documentation]: https://github.com/crate/cratedb-mcp/blob/main/DEVELOP.md [example questions]: https://github.com/crate/about/blob/v0.0.4/src/cratedb_about/query/model.py#L17-L44 [MCP]: https://modelcontextprotocol.io/introduction +[MCP tools]: https://modelcontextprotocol.io/docs/concepts/tools [mcptools]: https://github.com/f/mcptools [uv]: https://docs.astral.sh/uv/ From d07e74c1153b1843df2ee15ba4d865cbcb14c2e4 Mon Sep 17 00:00:00 2001 From: Andreas Motl Date: Sat, 17 May 2025 16:19:02 +0200 Subject: [PATCH 03/10] README: Bundle "Examples" section. Refactor `mcptools` to `examples`. --- README.md | 68 +++++++++++++------------------------------- examples/mcptools.sh | 24 ++++++++++++++++ 2 files changed, 43 insertions(+), 49 deletions(-) create mode 100644 examples/mcptools.sh diff --git a/README.md b/README.md index c40a652..361ff42 100644 --- a/README.md +++ b/README.md @@ -47,9 +47,9 @@ The CrateDB MCP Server is compatible with AI assistants that support the Model Context Protocol (MCP), either using standard input/output (stdio), server-sent events (SSE), or HTTP Streams (streamable-http). -To use the MCP server, you need a [client that supports] the protocol. The most -notable ones are ChatGPT, Claude, Cline, Cursor, GitHub Copilot, Mistral AI, -OpenAI Agents SDK, Windsurf, and others. +To use the MCP server, you need a [client that supports][MCP clients] the +protocol. The most notable ones are ChatGPT, Claude, Cline, Cursor, GitHub +Copilot, Mistral AI, OpenAI Agents SDK, Windsurf, and others. The `uvx` launcher command is provided by the [uv] package manager. The [installation docs](#install) section includes guidelines how to @@ -110,31 +110,18 @@ real world. The CrateDB MCP Server provides two families of tools. -The **Text-to-SQL API** talks to a CrateDB database cluster to inquire database +The **Text-to-SQL tools** talk to a CrateDB database cluster to inquire database and table metadata, and table content.
Tool names are: `get_health`, `get_table_metadata`, `query_sql` -The **Documentation API** looks up guidelines specific to CrateDB topics, +The **documentation server tools** looks up guidelines specific to CrateDB topics, to provide the most accurate information possible. Relevant information is pulled from , curated per [cratedb-outline.yaml] through the [cratedb-about] package.
Tool names are: `get_cratedb_documentation_index`, `fetch_cratedb_docs` -### Examples - -We collected a few examples of questions that have been tested and validated by -the team, so you may also want to try them. Please remember that LLMs can still -hallucinate and give incorrect answers. - -* Optimize this query: "SELECT * FROM movies WHERE release_date > '2012-12-1' AND revenue" -* Tell me about the health of the cluster -* What is the storage consumption of my tables, give it in a graph. -* How can I format a timestamp column to '2019 Jan 21'. - -Please also explore the [example questions] from another shared collection. - ### Security considerations **By default, the application will access the database in read-only mode.** @@ -187,7 +174,7 @@ in seconds. The `CRATEDB_MCP_DOCS_CACHE_TTL` environment variable (default: 3600) defines the cache lifetime for documentation resources in seconds. -### Usage +### Operate Start MCP server with `stdio` transport (default). ```shell @@ -204,53 +191,36 @@ cratedb-mcp serve --transport=streamable-http Alternatively, use the `CRATEDB_MCP_TRANSPORT` environment variable instead of the `--transport` option. -### Dry-run +### Use -You can use [mcptools], a Swiss Army Knife for MCP Servers, to talk to the -CrateDB MCP Server from the command line. The following operations do not -require a language model. +To connect to the MCP server using any of the available [MCP clients], use one +of the AI assistant applications, or refer to the programs in the [examples folder]. -Install software packages. -```shell -brew tap f/mcptools -brew install mcp uv -``` +We collected a few example questions that have been tested and validated by +the team, so you may also want to try them to get started. Please remember +that LLMs can still hallucinate and give incorrect answers. -Explore the Text-to-SQL API. -```shell -mcpt call query_sql --params '{"query":"SELECT * FROM sys.summits LIMIT 3"}' uvx cratedb-mcp serve -``` -```shell -mcpt call get_table_metadata uvx cratedb-mcp serve -``` -```shell -mcpt call get_health uvx cratedb-mcp serve -``` +* Optimize this query: "SELECT * FROM movies WHERE release_date > '2012-12-1' AND revenue" +* Tell me about the health of the cluster +* What is the storage consumption of my tables, give it in a graph. +* How can I format a timestamp column to '2019 Jan 21'. -Exercise the documentation server API. -```shell -mcpt call get_cratedb_documentation_index uvx cratedb-mcp serve -``` -```shell -mcpt call \ - fetch_cratedb_docs --params '{"link":"https://cratedb.com/docs/cloud/en/latest/_sources/cluster/integrations/mongo-cdc.md.txt"}' \ - uvx cratedb-mcp serve -``` +Please also explore the [example questions] from another shared collection. ### Development To learn how to set up a development sandbox, see the [development documentation]. -[client that supports]: https://modelcontextprotocol.io/clients [CrateDB]: https://cratedb.com/database [cratedb-about]: https://pypi.org/project/cratedb-about/ [cratedb-outline.yaml]: https://github.com/crate/about/blob/v0.0.4/src/cratedb_about/outline/cratedb-outline.yaml [development documentation]: https://github.com/crate/cratedb-mcp/blob/main/DEVELOP.md [example questions]: https://github.com/crate/about/blob/v0.0.4/src/cratedb_about/query/model.py#L17-L44 +[examples folder]: https://github.com/crate/cratedb-mcp/tree/main/examples [MCP]: https://modelcontextprotocol.io/introduction +[MCP clients]: https://modelcontextprotocol.io/clients [MCP tools]: https://modelcontextprotocol.io/docs/concepts/tools -[mcptools]: https://github.com/f/mcptools [uv]: https://docs.astral.sh/uv/ [Bluesky]: https://bsky.app/search?q=cratedb diff --git a/examples/mcptools.sh b/examples/mcptools.sh new file mode 100644 index 0000000..082d3bd --- /dev/null +++ b/examples/mcptools.sh @@ -0,0 +1,24 @@ +#!/usr/bin/env sh + +# CrateDB MCP Server example with `mcptools` +# +# You can use the `mcptools` package, a Swiss Army Knife for MCP Servers, +# to talk to the CrateDB MCP Server from the command line. The following +# operations do not require a language model. +# +# -- https://github.com/f/mcptools +# +# Install software packages. +# brew tap f/mcptools +# brew install mcp uv + +# Explore the Text-to-SQL tools. +mcpt call query_sql --params '{"query":"SELECT * FROM sys.summits LIMIT 3"}' uvx cratedb-mcp serve +mcpt call get_table_metadata uvx cratedb-mcp serve +mcpt call get_health uvx cratedb-mcp serve + +# Exercise the documentation server tools. +mcpt call get_cratedb_documentation_index uvx cratedb-mcp serve +mcpt call \ + fetch_cratedb_docs --params '{"link":"https://cratedb.com/docs/cloud/en/latest/_sources/cluster/integrations/mongo-cdc.md.txt"}' \ + uvx cratedb-mcp serve From 552ed6460c6f72977223e49f69be448a53f6cac9 Mon Sep 17 00:00:00 2001 From: Andreas Motl Date: Sat, 17 May 2025 16:23:09 +0200 Subject: [PATCH 04/10] README: Add section "Project information" --- README.md | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 361ff42..e8108ae 100644 --- a/README.md +++ b/README.md @@ -207,9 +207,21 @@ that LLMs can still hallucinate and give incorrect answers. Please also explore the [example questions] from another shared collection. -### Development +## Project information -To learn how to set up a development sandbox, see the [development documentation]. +### Acknowledgements +Kudos to the authors of all the many software components and technologies +this project is building upon. + +### Contributing +The `cratedb-mcp` package is an open source project, and is [managed on +GitHub]. Contributions of any kind are welcome and appreciated. +To learn how to set up a development sandbox, please refer to the +[development documentation]. + +### Status +The software is in the alpha stage, please expect breaking changes. +Version pinning is strongly recommended, especially if you use it as a library. [CrateDB]: https://cratedb.com/database From 1a5688268c8fb605acf662960ed35053f6f6600f Mon Sep 17 00:00:00 2001 From: Andreas Motl Date: Sat, 17 May 2025 16:23:22 +0200 Subject: [PATCH 05/10] Chore: Update backlog --- docs/backlog.md | 58 ++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 52 insertions(+), 6 deletions(-) diff --git a/docs/backlog.md b/docs/backlog.md index e9d31aa..9e11a49 100644 --- a/docs/backlog.md +++ b/docs/backlog.md @@ -1,16 +1,44 @@ # CrateDB MCP backlog ## Iteration +1 -- Release v0.0.0 +- README: Provide guidelines on how to create a CrateDB read-only user +- CLI: Honor `--read-only` option flag + - https://fluxcd.control-plane.io/mcp/config/ +- mcptools: `mcpt call` does not exit with returncode != 0 when "Unknown tool:" happens +- Release v0.0.1 ## Iteration +2 +- Migrate to FastAPI 2.0 + - https://gofastmcp.com/getting-started/welcome#fastmcp-2-0-and-the-official-mcp-sdk + - https://gofastmcp.com/patterns/testing +- Install: Others also just use `docker` right away? Others discourage using `uvx`. + - https://github.com/ppl-ai/modelcontextprotocol/?tab=readme-ov-file#step-3-configure-claude-desktop + - https://medium.com/@scalablecto/stop-running-your-mcp-tools-via-npx-uvx-right-now-380d1ab99d3f +- Ecosystem: Link to 3rd-party installation instructions? + - https://code.visualstudio.com/docs/copilot/chat/mcp-servers#_add-an-mcp-server-to-your-workspace + - https://docs.cline.bot/mcp/configuring-mcp-servers + - https://docs.cline.bot/mcp/adding-mcp-servers-from-github + - https://docs.cline.bot/mcp/connecting-to-a-remote-server +- Ecosystem: Server Composition + - https://gofastmcp.com/servers/fastmcp#composing-servers + - https://gofastmcp.com/servers/composition + - https://github.com/f/mcptools/pull/41 + +## Iteration +3 +- Provide "instructions" + > For the best experience with the CrateDB MCP Server, it’s crucial to provide your + > AI assistant with proper instructions on how to interact. [...] The CrateDB MCP Server + > comes with a set of predefined instructions that you can copy from the `instructions.md` file. + - Blueprint: + - https://fluxcd.io/blog/2025/05/ai-assisted-gitops/ + - https://fluxcd.control-plane.io/mcp/prompt-engineering/ + - https://raw.githubusercontent.com/controlplaneio-fluxcd/distribution/refs/heads/main/docs/mcp/instructions.md - Docs: Load documentation index from a custom outline file - Naming things: Better names for API entrypoints? -- Enable MCP transport `streamable-http` -- SQL: Extract `SqlFilter` or `SqlGateway` functionality to `cratedb-sqlparse` -- Use `platformdirs.user_cache_dir` for Hishel, see `pueblo.cache -- UX: Improve documentation, generalizing beyond Claude -- UX: Make `streamable-http` the default transport +- Use `platformdirs.user_cache_dir` for Hishel, see `pueblo.cache` +- Refactoring + - Extract `SqlFilter` or `SqlGateway` functionality to the `cratedb-sqlparse` package + - Extract other utilities to the `pueblo` package ## Done - Make it work @@ -19,3 +47,21 @@ - Improve documentation - Format code, improve linting - Docs: About `CRATEDB_MCP_HTTP_TIMEOUT` +- Release v0.0.0 +- CLI: For real. Blueprint: https://fluxcd.control-plane.io/mcp/config/ +- Enable MCP transport `streamable-http` +- UX: Make `streamable-http` the default transport? => No. +- Docs: + > Claude, Cursor, and Windsurf vs. VS Code Copilot Chat + > -- https://fluxcd.control-plane.io/mcp/install/#configuration-with-ai-assistants +- Docs: + > Once installed, you can configure your AI assistant to use the Flux MCP Server. + > For Claude, Cursor, Windsurf, or GitHub Copilot add the following configuration + > to the MCP settings. + > -- https://fluxcd.io/blog/2025/05/ai-assisted-gitops/#getting-started +- Docs: Improve README. The Flux MCP Server and Operator are excellent blueprints. + https://github.com/controlplaneio-fluxcd/flux-operator + https://fluxcd.control-plane.io/mcp/ +- UX: Improve documentation, generalizing a bit beyond Claude only +- README: Use FastMCP client instead of `mcptools` program? => No. There is no FastMCP client. +- README: What's inside: Talk about "MCP tools" From 06e9bd2f9b9fab74efb19a03b06da48f476ed0da Mon Sep 17 00:00:00 2001 From: Andreas Motl Date: Sat, 17 May 2025 16:35:14 +0200 Subject: [PATCH 06/10] README: More copy-editing, also following suggestions by CodeRabbit --- README.md | 22 +++++++++++----------- docs/backlog.md | 3 ++- pyproject.toml | 2 +- 3 files changed, 14 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index e8108ae..c527919 100644 --- a/README.md +++ b/README.md @@ -21,7 +21,7 @@ ## About -The CrateDB MCP Server for natural language Text-to-SQL and documentation +The CrateDB MCP Server for natural-language Text-to-SQL and documentation retrieval specializes in CrateDB database clusters. The Model Context Protocol ([MCP]) is a protocol that standardizes providing @@ -48,11 +48,11 @@ Context Protocol (MCP), either using standard input/output (stdio), server-sent events (SSE), or HTTP Streams (streamable-http). To use the MCP server, you need a [client that supports][MCP clients] the -protocol. The most notable ones are ChatGPT, Claude, Cline, Cursor, GitHub -Copilot, Mistral AI, OpenAI Agents SDK, Windsurf, and others. +protocol. The most notable ones are ChatGPT, Claude, Cline Bot, Cursor, +GitHub Copilot, Mistral AI, OpenAI Agents SDK, Windsurf, and others. The `uvx` launcher command is provided by the [uv] package manager. -The [installation docs](#install) section includes guidelines how to +The [installation docs](#install) section includes guidelines on how to install it on your machine. #### Claude, Cursor, Windsurf @@ -148,7 +148,7 @@ Notes: ```shell {apt,brew,pipx,zypper} install uv ``` -- We recommend to use `uv tool install` to install the program "user"-wide +- We recommend using `uv tool install` to install the program "user"-wide into your environment so you can invoke it from anywhere across your terminal sessions or MCP client programs / AI assistants. - If you are unable to use `uv tool install`, you can use `uvx cratedb-mcp` @@ -200,10 +200,10 @@ We collected a few example questions that have been tested and validated by the team, so you may also want to try them to get started. Please remember that LLMs can still hallucinate and give incorrect answers. -* Optimize this query: "SELECT * FROM movies WHERE release_date > '2012-12-1' AND revenue" -* Tell me about the health of the cluster -* What is the storage consumption of my tables, give it in a graph. -* How can I format a timestamp column to '2019 Jan 21'. +- Optimize this query: "SELECT * FROM movies WHERE release_date > '2012-12-1' AND revenue" +- Tell me about the health of the cluster +- What is the storage consumption of my tables, give it in a graph. +- How can I format a timestamp column to '2019 Jan 21'? Please also explore the [example questions] from another shared collection. @@ -214,13 +214,13 @@ Kudos to the authors of all the many software components and technologies this project is building upon. ### Contributing -The `cratedb-mcp` package is an open source project, and is [managed on +The `cratedb-mcp` package is an open-source project, and is [managed on GitHub]. Contributions of any kind are welcome and appreciated. To learn how to set up a development sandbox, please refer to the [development documentation]. ### Status -The software is in the alpha stage, please expect breaking changes. +The software is in the alpha stage, so breaking changes may happen. Version pinning is strongly recommended, especially if you use it as a library. diff --git a/docs/backlog.md b/docs/backlog.md index 9e11a49..28d9eda 100644 --- a/docs/backlog.md +++ b/docs/backlog.md @@ -29,7 +29,8 @@ > For the best experience with the CrateDB MCP Server, it’s crucial to provide your > AI assistant with proper instructions on how to interact. [...] The CrateDB MCP Server > comes with a set of predefined instructions that you can copy from the `instructions.md` file. - - Blueprint: + + Blueprint: - https://fluxcd.io/blog/2025/05/ai-assisted-gitops/ - https://fluxcd.control-plane.io/mcp/prompt-engineering/ - https://raw.githubusercontent.com/controlplaneio-fluxcd/distribution/refs/heads/main/docs/mcp/instructions.md diff --git a/pyproject.toml b/pyproject.toml index 103c6ba..4842433 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -7,7 +7,7 @@ requires = [ [project] name = "cratedb-mcp" -description = "CrateDB MCP Server for natural language Text-to-SQL and documentation retrieval." +description = "CrateDB MCP Server for natural-language Text-to-SQL and documentation retrieval." readme = "README.md" keywords = [ "cratedb", From 2f8bb9bd9540298a2f8a47b5bdc390202fdc32fb Mon Sep 17 00:00:00 2001 From: Andreas Motl Date: Sat, 17 May 2025 23:06:54 +0200 Subject: [PATCH 07/10] Tests: Add software tests for `examples/mcptools.sh` --- .github/workflows/tests.yml | 4 ++++ examples/mcptools.sh | 9 ++++++++- tests/test_examples.py | 12 ++++++++++++ 3 files changed, 24 insertions(+), 1 deletion(-) mode change 100644 => 100755 examples/mcptools.sh create mode 100644 tests/test_examples.py diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index afe3ad4..0eebd6b 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -68,6 +68,10 @@ jobs: enable-cache: true version: "latest" + - name: Set up mcptools + run: | + go install github.com/f/mcptools/cmd/mcptools@latest + - name: Set up project run: | uv pip install --editable='.[all,develop,test]' diff --git a/examples/mcptools.sh b/examples/mcptools.sh old mode 100644 new mode 100755 index 082d3bd..7d0077c --- a/examples/mcptools.sh +++ b/examples/mcptools.sh @@ -1,4 +1,6 @@ -#!/usr/bin/env sh +#!/usr/bin/env bash + +set -euo pipefail # CrateDB MCP Server example with `mcptools` # @@ -12,6 +14,9 @@ # brew tap f/mcptools # brew install mcp uv +# Some systems do not provide the `mcpt` alias. +alias mcpt=mcptools + # Explore the Text-to-SQL tools. mcpt call query_sql --params '{"query":"SELECT * FROM sys.summits LIMIT 3"}' uvx cratedb-mcp serve mcpt call get_table_metadata uvx cratedb-mcp serve @@ -22,3 +27,5 @@ mcpt call get_cratedb_documentation_index uvx cratedb-mcp serve mcpt call \ fetch_cratedb_docs --params '{"link":"https://cratedb.com/docs/cloud/en/latest/_sources/cluster/integrations/mongo-cdc.md.txt"}' \ uvx cratedb-mcp serve + +echo "Ready." diff --git a/tests/test_examples.py b/tests/test_examples.py new file mode 100644 index 0000000..87db71d --- /dev/null +++ b/tests/test_examples.py @@ -0,0 +1,12 @@ +# ruff: noqa: S603, S607 +import subprocess +from shutil import which + +import pytest + + +@pytest.mark.skipif(not which("mcptools"), reason="requires mcptools") +def test_mcptools(): + proc = subprocess.run(["examples/mcptools.sh"], capture_output=True, timeout=15, check=True) + assert proc.returncode == 0 + assert b"Ready." in proc.stdout From cbd11d33adac21f50d32f63613bde51b7ed9df86 Mon Sep 17 00:00:00 2001 From: Andreas Motl Date: Sun, 18 May 2025 09:11:38 +0200 Subject: [PATCH 08/10] README: Add configuration sections about Goose and LibreChat --- README.md | 38 ++++++++++++++++++++++++++++++++++++++ docs/backlog.md | 9 ++++++++- 2 files changed, 46 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index c527919..0dd8835 100644 --- a/README.md +++ b/README.md @@ -95,6 +95,41 @@ Add the following configuration to your VS Code settings: } ``` +#### Goose +Configure `extensions` in your `~/.config/goose/config.yaml`. +See also [using Goose extensions]. +```yaml +extensions: + cratedb-mcp: + name: CrateDB MCP + type: stdio + cmd: uvx + args: + - cratedb-mcp + - serve + enabled: true + envs: + CRATEDB_CLUSTER_URL: "http://localhost:4200/" + CRATEDB_MCP_TRANSPORT: "stdio" + timeout: 300 +``` + +#### LibreChat +Configure `mcpServers` in your `librechat.yaml`. +See also [LibreChat and MCP] and [LibreChat MCP examples]. +```yaml +mcpServers: + cratedb-mcp: + type: stdio + command: uvx + args: + - cratedb-mcp + - serve + env: + CRATEDB_CLUSTER_URL: "http://localhost:4200/" + CRATEDB_MCP_TRANSPORT: "stdio" +``` + ## Handbook This section includes detailed information about how to configure and @@ -230,9 +265,12 @@ Version pinning is strongly recommended, especially if you use it as a library. [development documentation]: https://github.com/crate/cratedb-mcp/blob/main/DEVELOP.md [example questions]: https://github.com/crate/about/blob/v0.0.4/src/cratedb_about/query/model.py#L17-L44 [examples folder]: https://github.com/crate/cratedb-mcp/tree/main/examples +[LibreChat and MCP]: https://www.librechat.ai/docs/features/agents#model-context-protocol-mcp +[LibreChat MCP examples]: https://www.librechat.ai/docs/configuration/librechat_yaml/object_structure/mcp_servers [MCP]: https://modelcontextprotocol.io/introduction [MCP clients]: https://modelcontextprotocol.io/clients [MCP tools]: https://modelcontextprotocol.io/docs/concepts/tools +[using Goose extensions]: https://block.github.io/goose/docs/getting-started/using-extensions/ [uv]: https://docs.astral.sh/uv/ [Bluesky]: https://bsky.app/search?q=cratedb diff --git a/docs/backlog.md b/docs/backlog.md index 28d9eda..f9c4590 100644 --- a/docs/backlog.md +++ b/docs/backlog.md @@ -4,13 +4,14 @@ - README: Provide guidelines on how to create a CrateDB read-only user - CLI: Honor `--read-only` option flag - https://fluxcd.control-plane.io/mcp/config/ -- mcptools: `mcpt call` does not exit with returncode != 0 when "Unknown tool:" happens - Release v0.0.1 ## Iteration +2 - Migrate to FastAPI 2.0 - https://gofastmcp.com/getting-started/welcome#fastmcp-2-0-and-the-official-mcp-sdk - https://gofastmcp.com/patterns/testing +- README: Provide AI assistant snippets about configuring `sse` or `streamable-http` + transports, see LibreChat. - Install: Others also just use `docker` right away? Others discourage using `uvx`. - https://github.com/ppl-ai/modelcontextprotocol/?tab=readme-ov-file#step-3-configure-claude-desktop - https://medium.com/@scalablecto/stop-running-your-mcp-tools-via-npx-uvx-right-now-380d1ab99d3f @@ -19,6 +20,8 @@ - https://docs.cline.bot/mcp/configuring-mcp-servers - https://docs.cline.bot/mcp/adding-mcp-servers-from-github - https://docs.cline.bot/mcp/connecting-to-a-remote-server +- Ecosystem: Interoperability with tools of other frameworks (OpenAI, OpenRouter, LangChain) + - https://openrouter.ai/docs/use-cases/mcp-servers - Ecosystem: Server Composition - https://gofastmcp.com/servers/fastmcp#composing-servers - https://gofastmcp.com/servers/composition @@ -66,3 +69,7 @@ - UX: Improve documentation, generalizing a bit beyond Claude only - README: Use FastMCP client instead of `mcptools` program? => No. There is no FastMCP client. - README: What's inside: Talk about "MCP tools" +- README: Add configuration snippets for Goose and LibreChat + https://github.com/f/mcptools/issues/45 +- mcptools: `mcpt call` does not exit with returncode != 0 when "Unknown tool:" happens + https://github.com/f/mcptools/issues/53 From afaf7eb546742b32d5b86006a9ac64989957817b Mon Sep 17 00:00:00 2001 From: Andreas Motl Date: Sun, 18 May 2025 10:03:34 +0200 Subject: [PATCH 09/10] README: Improve configuration section about VS Code --- README.md | 21 ++++++++++++++++++--- 1 file changed, 18 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 0dd8835..cdd0e06 100644 --- a/README.md +++ b/README.md @@ -74,9 +74,9 @@ CrateDB MCP Server: } ``` -#### VS Code Copilot Chat - -Add the following configuration to your VS Code settings: +#### VS Code +[Add an MCP server to your VS Code user settings] to enable the MCP server +across all workspaces in your `settings.json` file. ```json { "mcp": { @@ -94,6 +94,18 @@ Add the following configuration to your VS Code settings: "chat.mcp.enabled": true } ``` +[Add an MCP server to your VS Code workspace] to configure an MCP server for a +specific workspace per `.vscode/mcp.json` file. In this case, omit the +top-level `mcp` element, and start from `servers` instead. + +Alternatively, VS Code can automatically detect and reuse MCP servers that +you defined in other tools, such as Claude Desktop. +See also [Automatic discovery of MCP servers]. +```json +{ + "chat.mcp.discovery.enabled": true +} +``` #### Goose Configure `extensions` in your `~/.config/goose/config.yaml`. @@ -259,6 +271,9 @@ The software is in the alpha stage, so breaking changes may happen. Version pinning is strongly recommended, especially if you use it as a library. +[Add an MCP server to your VS Code user settings]: https://code.visualstudio.com/docs/copilot/chat/mcp-servers#_add-an-mcp-server-to-your-user-settings +[Add an MCP server to your VS Code workspace]: https://code.visualstudio.com/docs/copilot/chat/mcp-servers#_add-an-mcp-server-to-your-workspace +[Automatic discovery of MCP servers]: https://code.visualstudio.com/docs/copilot/chat/mcp-servers#_automatic-discovery-of-mcp-servers [CrateDB]: https://cratedb.com/database [cratedb-about]: https://pypi.org/project/cratedb-about/ [cratedb-outline.yaml]: https://github.com/crate/about/blob/v0.0.4/src/cratedb_about/outline/cratedb-outline.yaml From b3d1d21a62df319dbed530dc9a3ba729b2887872 Mon Sep 17 00:00:00 2001 From: Andreas Motl Date: Sun, 18 May 2025 10:29:06 +0200 Subject: [PATCH 10/10] README: Improve configuration section about Claude-compatible JSON files --- README.md | 20 ++++++++++++++++---- docs/backlog.md | 5 ++++- 2 files changed, 20 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index cdd0e06..7048484 100644 --- a/README.md +++ b/README.md @@ -55,10 +55,14 @@ The `uvx` launcher command is provided by the [uv] package manager. The [installation docs](#install) section includes guidelines on how to install it on your machine. -#### Claude, Cursor, Windsurf - +#### Claude, Cline, Cursor, Roo Code, Windsurf Add the following configuration to your AI assistant's settings to enable the -CrateDB MCP Server: +CrateDB MCP Server. +- Claude: [`claude_desktop_config.json`](https://modelcontextprotocol.io/quickstart/user) +- Cline: [`cline_mcp_settings.json`](https://docs.cline.bot/mcp/configuring-mcp-servers) +- Cursor: [`~/.cursor/mcp.json` or `.cursor/mcp.json`](https://docs.cursor.com/context/model-context-protocol) +- Roo Code: [`mcp_settings.json` or `.roo/mcp.json`](https://docs.roocode.com/features/mcp/using-mcp-in-roo/) +- Windsurf: [`~/.codeium/windsurf/mcp_config.json`](https://docs.windsurf.com/windsurf/cascade/mcp) ```json { "mcpServers": { @@ -68,7 +72,15 @@ CrateDB MCP Server: "env": { "CRATEDB_CLUSTER_URL": "http://localhost:4200/", "CRATEDB_MCP_TRANSPORT": "stdio" - } + }, + "alwaysAllow": [ + "get_health", + "get_table_metadata", + "query_sql", + "get_cratedb_documentation_index", + "fetch_cratedb_docs" + ], + "disabled": false } } } diff --git a/docs/backlog.md b/docs/backlog.md index f9c4590..df1e226 100644 --- a/docs/backlog.md +++ b/docs/backlog.md @@ -11,7 +11,10 @@ - https://gofastmcp.com/getting-started/welcome#fastmcp-2-0-and-the-official-mcp-sdk - https://gofastmcp.com/patterns/testing - README: Provide AI assistant snippets about configuring `sse` or `streamable-http` - transports, see LibreChat. + transports, see Cline and LibreChat, by adding a section about how to connect to + existing MCP servers via URL endpoints. + - https://docs.cline.bot/mcp/connecting-to-a-remote-server + - https://www.librechat.ai/docs/configuration/librechat_yaml/object_structure/mcp_servers - Install: Others also just use `docker` right away? Others discourage using `uvx`. - https://github.com/ppl-ai/modelcontextprotocol/?tab=readme-ov-file#step-3-configure-claude-desktop - https://medium.com/@scalablecto/stop-running-your-mcp-tools-via-npx-uvx-right-now-380d1ab99d3f