README: Improve unboxing experience

.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]'

README.md

@@ -21,49 +21,167 @@
 
 ## 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 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
-<https://cratedb.com/docs>, to provide the most accurate possible information.
-Relevant information is relayed per [cratedb-outline.yaml].
+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).
 
-- Database / Text-to-SQL: `get_health`, `get_table_metadata`, `query_sql`
-- Documentation server: `get_cratedb_documentation_index`, `fetch_cratedb_docs`
+To use the MCP server, you need a [client that supports][MCP clients] the
+protocol. The most notable ones are ChatGPT, Claude, Cline Bot, Cursor,
+GitHub Copilot, Mistral AI, OpenAI Agents SDK, Windsurf, and others.
 
-### Examples
+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.
 
-These are examples of questions that have been tested and validated by the team.
-Remember that LLMs can still hallucinate and give incorrect answers.
+#### Claude, Cline, Cursor, Roo Code, Windsurf
+Add the following configuration to your AI assistant's settings to enable the
+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": {
+    "cratedb-mcp": {
+      "command": "uvx",
+      "args": ["cratedb-mcp", "serve"],
+      "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
+    }
+  }
+}
+```
+
+#### 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": {
+    "servers": {
+      "cratedb-mcp": {
+        "command": "uvx",
+        "args": ["cratedb-mcp", "serve"],
+        "env": {
+          "CRATEDB_CLUSTER_URL": "http://localhost:4200/",
+          "CRATEDB_MCP_TRANSPORT": "stdio"
+        }
+      }
+    }
+  },
+  "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`.
+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
+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.
 
-* 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'.
+### What's inside
 
-Please explore other [example questions] from a shared collection.
+The CrateDB MCP Server provides two families of tools.
 
-## Security considerations
+The **Text-to-SQL tools** talk to a CrateDB database cluster to inquire database
+and table metadata, and table content.
+<br>
+Tool names are: `get_health`, `get_table_metadata`, `query_sql`
+
+The **documentation server tools** looks up guidelines specific to CrateDB topics,
+to provide the most accurate information possible.
+Relevant information is pulled from <https://cratedb.com/docs>, curated per
+[cratedb-outline.yaml] through the [cratedb-about] package.
+<br>
+Tool names are: `get_cratedb_documentation_index`, `fetch_cratedb_docs`
+
+### Security considerations
 
 **By default, the application will access the database in read-only mode.**
 
@@ -73,7 +191,13 @@ 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 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
 ```
@@ -83,13 +207,13 @@ 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 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 +233,8 @@ 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
 cratedb-mcp serve --transport=stdio
@@ -125,68 +250,54 @@ 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:
+### Use
 
-```json
-{
-  "mcpServers": {
-    "my_cratedb": {
-      "command": "uvx",
-      "args": ["cratedb-mcp", "serve"],
-      "env": {
-        "CRATEDB_CLUSTER_URL": "http://localhost:4200/",
-        "CRATEDB_MCP_TRANSPORT": "stdio"
-      }
-    }
-  }
-}
-```
+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].
 
-### Dry-run
+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.
 
-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.
+- 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'?
 
-Install software packages.
-```shell
-brew tap f/mcptools
-brew install mcp uv
-```
+Please also explore the [example questions] from another shared collection.
 
-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
-```
+## Project information
 
-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
-```
+### Acknowledgements
+Kudos to the authors of all the many software components and technologies
+this project is building upon.
 
-## Development
+### 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].
 
-To learn how to set up a development sandbox, see the [development documentation](./DEVELOP.md).
+### Status
+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.
 
 
-[client that supports]: https://modelcontextprotocol.io/clients#feature-support-matrix
+[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
+[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
-[mcptools]: https://github.com/f/mcptools
+[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