CrateDB MCP 服务器使用说明

项目简介

CrateDB MCP Server 是一个实现了 Model Context Protocol (MCP) 的服务器，它充当 LLM 客户端和 CrateDB 数据库之间的桥梁。通过 MCP 协议，该服务器允许 LLM 安全、可控地访问 CrateDB 数据库中的数据和功能，从而实现诸如数据查询、数据库状态监控、查询优化建议等应用场景。

主要功能点

SQL 查询工具 (query_sql): 允许 LLM 执行 'SELECT' SQL 查询语句，从 CrateDB 数据库中检索数据。出于安全考虑，仅支持 'SELECT' 查询，禁止数据修改操作。
文档索引工具 (get_cratedb_documentation_index): 提供 CrateDB 官方文档的索引，包含文档名称、描述和链接，帮助 LLM 查找和利用 CrateDB 的官方文档知识。
文档获取工具 (fetch_cratedb_docs): 允许 LLM 根据提供的文档链接下载 CrateDB 官方文档内容，以便在回答用户问题时参考最新的文档信息。
表元数据工具 (get_table_metadata): 返回 CrateDB 数据库中所有表及其元数据的聚合信息，包括表名、模式、副本数、分片信息、健康状态、记录总数、存储大小等，帮助 LLM 理解数据库结构和状态。
集群健康状态工具 (get_health): 返回 CrateDB 集群的健康状态信息，帮助 LLM 监控数据库的运行状况。

安装步骤

克隆仓库:

git clone https://github.com/crate/cratedb-mcp.git
cd cratedb-mcp

安装依赖 (可选): 虽然仓库中没有明确的依赖声明，但根据代码推测，可能需要 'httpx' 库。如果运行出现模块缺失的错误，请使用 pip 安装：
```
pip install httpx
```
建议在虚拟环境中安装依赖。

服务器配置

MCP 客户端需要配置以下 JSON 格式信息以连接到 CrateDB MCP 服务器。请根据您的实际环境修改以下配置：

{
  "serverName": "cratedb-mcp-server",  // 服务器名称，客户端用于标识连接
  "command": "python",                 // 启动服务器的命令，这里使用 python 解释器
  "args": [                            // 启动命令的参数
    "-m",                             // -m 参数用于运行模块
    "cratedb_mcp"                     // 指定要运行的模块为 cratedb_mcp
  ],
  "env": {                             // 环境变量配置 (非常重要)
    "CRATEDB_MCP_HTTP_URL": "http://<your_cratedb_http_url>:4200"  // CrateDB 数据库的 HTTP API 地址，需要替换为你的 CrateDB 实例地址，端口默认为 4200
  }
}

配置说明:

'"serverName"': 自定义服务器名称，用于在 MCP 客户端中识别和管理连接。
'"command"': 指定用于启动服务器进程的命令。这里假设您已安装 Python 并且 'python' 命令在系统 PATH 中。
'"args"': 启动命令的参数。 '"-m cratedb_mcp"' 表示以模块方式运行 'cratedb_mcp' 包，即执行 'cratedb_mcp/main.py' 文件。
'"env"': 环境变量配置至关重要。'"CRATEDB_MCP_HTTP_URL"' 环境变量用于指定 CrateDB 数据库的 HTTP API 地址。请务必将其替换为您实际的 CrateDB HTTP API 地址 (例如 'http://localhost:4200' 或远程 CrateDB 集群的地址)。如果 CrateDB 运行在不同的主机或端口，请相应修改 URL。

启动服务器:

配置完成后，MCP 客户端应该能够使用上述配置启动 CrateDB MCP 服务器。在配置正确的情况下，服务器将在后台运行，并监听来自 MCP 客户端的请求。

基本使用方法

启动 CrateDB MCP 服务器: 通过 MCP 客户端提供的配置启动服务器。
客户端请求: LLM 客户端可以通过 MCP 协议向 CrateDB MCP 服务器发送 JSON-RPC 请求，调用预定义的工具 (如 'query_sql', 'get_table_metadata' 等)。
服务器响应: CrateDB MCP 服务器接收到请求后，会调用相应的 Python 函数执行操作 (例如执行 SQL 查询，获取元数据)，并将结果封装成 JSON-RPC 响应返回给客户端。
LLM 利用上下文: LLM 客户端接收到服务器返回的响应后，可以解析响应内容，提取数据库上下文信息，并用于生成更准确、更贴切用户需求的结果。

例如，一个典型的使用场景是：

LLM 客户端接收到用户问题 "查询电影表中 2012 年之后上映的电影名称"。

LLM 客户端调用 'query_sql' 工具，并构造如下的 SQL 查询语句作为参数：'"SELECT title FROM movies WHERE release_date > '2012-12-31'"'。
MCP 服务器执行该 SQL 查询，连接到配置的 CrateDB 数据库，执行查询，并将查询结果返回给 LLM 客户端。
LLM 客户端解析查询结果，并将结果呈现给用户。

通过这种方式，LLM 能够利用 CrateDB 数据库中的数据回答用户的问题，完成更复杂的数据库交互任务。

关键词