KWDB MCP Server

KWDB MCP 服务

中文版

概述

KWDB MCP 服务是一种基于 MCP（Model Context Protocol）协议的服务端实现，可提供一组工具和资源，用于通过 MCP 协议与 KWDB 数据库交互并提供商业智能功能。KWDB MCP 服务支持读取、写入、查询、修改数据以及执行 DDL 操作。

架构

KWDB MCP 服务的核心流程由以下组件组成：

• 解析 MCP 协议：处理 MCP StdIO 或 HTTP SSE 请求。
• 调度 MCP 工具：根据 MCP 工具的类型分发 API 请求。
• 准备查询：为不含 LIMIT 子句的 SQL 查询自动添加 LIMIT 20 子句。
• 格式化查询结果：为所有 API 响应采用一致的 JSON 格式。

功能

• 读取操作：执行 SELECT、SHOW、EXPLAIN 等只读查询。
• 写入操作：执行 INSERT、UPDATE、DELETE 以及 CREATE、DROP、ALTER DDL 操作。
• 数据库信息：获取数据库信息，包括表及其架构。
• 检查工具：query-metrics（通过管理端 /restapi/ts/query 端点查询固定目录中的 32 项运行时指标）和 query-slow-sql（通过对 kwdb_internal.node_statement_statistics 执行 SELECT 查询获取排名前 N 的慢 SQL 语句）——两者均从现有数据库 URL 获取凭据，并支持 TLS 和不安全的 KaiwuDB 部署。
• 语法指南：通过提示词访问全面的 KWDB 语法指南。
• 标准 API 响应：提供一致的错误处理机制。
  • 工具错误：错误信息会封装在带有 isError 标志的结果对象中。

  {
    "content": [{"type": "text", "text": "Query error: error details"}],
    "isError": true
  }
  

  • 资源错误：直接返回标准 JSON-RPC 错误响应。

  {
    "jsonrpc": "2.0",
    "id": 1,
    "error": {
      "code": -32002,  // RESOURCE_NOT_FOUND: resource does not exist
      "message": "handler not found for resource URI 'kwdb://table/nonexistent': resource not found"
    }
  }
  

  或内部处理错误：

  {
    "jsonrpc": "2.0",
    "id": 1,
    "error": {
      "code": -32603,  // INTERNAL_ERROR: internal resource processing error
      "message": "failed to get table schema for 'tablename': database connection error"
    }
  }
  

  • 成功响应：工具返回结果对象，资源返回内容数组。
• 自动添加 LIMIT：为不含 LIMIT 子句的 SELECT 查询自动添加 LIMIT 20 子句，以避免结果集过大。

安全性

KWDB MCP 服务提供以下安全措施：

• 为读取和写入操作提供独立的工具。
• 验证查询，确保其符合预期的操作类型。
• 针对未经授权的操作打印明确的错误消息。

MCP 资源

MCP 资源允许 KWDB MCP Server 向 MCP 客户端公开数据和内容，供其读取并用作大模型交互的上下文。KWDB MCP Server 提供以下 MCP 资源：

资源	URI 格式	说明	示例
产品信息	kwdb://product_info	产品信息，包括版本和支持的功能	kwdb://product_info/
数据库元数据	kwdb://db_info/{database_name}	特定数据库的信息，包括引擎类型、注释和表	kwdb://db_info/db_shig
表架构	kwdb://table/{table_name}	特定表的架构，包括列和查询示例	kwdb://table/user_profile

MCP 工具

MCP 工具使 KWDB MCP Server 能够向 MCP 客户端公开可执行的功能。借助 MCP 工具，大模型可以与外部系统交互。KWDB MCP Server 提供以下 MCP 工具。

read-query

KWDB MCP Server 执行 SELECT、SHOW、EXPLAIN 语句和其他只读查询，以从数据库读取数据。read_query 函数会以数组格式返回 SQL 语句的查询结果。此外，对于不包含 LIMIT 子句的 SELECT 查询，KWDB MCP Server 会自动添加 LIMIT 20 子句，以避免结果集过大。

示例：

-- Query table data.
SELECT * FROM users LIMIT 10;

-- List all created tables.
SHOW TABLES;

-- Execute a SQL query and generate details about the SQL query.
EXPLAIN ANALYZE SELECT * FROM orders WHERE user_id = 1;

write-query

KWDB MCP Server 执行数据修改查询，包括 DML 和 DDL 操作。

示例：

-- Insert data into the table.
INSERT INTO users (name, email) VALUES ('John Doe', '[email protected]');

-- Update data in the table.
UPDATE users SET email = '[email protected]' WHERE id = 1;

-- Remove data from the table.
DELETE FROM users WHERE id = 1;

-- Create a table.
CREATE TABLE products (id SERIAL PRIMARY KEY, name TEXT, price DECIMAL);

-- Add a column to a table.
ALTER TABLE products ADD COLUMN description TEXT;

-- Remove a table.
DROP TABLE products;

query-metrics

KWDB MCP Server 可通过数据库管理 /ts/query API 查询历史运行时指标。该工具接受固定目录中的 32 项检查指标（QPS、CPU、内存、延迟、存储、集群、网络），这些指标定义在 docs/design-tls-inspection-tools.md 中。每次调用都需要提供 metric_names、start_ms、end_ms 和 sample_ms。Basic Auth 凭据取自连接字符串中的 user:password。

这 32 项指标涵盖以下类别（全部为 derivative: "none"）：

类别	示例
基本	cr.node.liveness.livenodes、cr.node.sys.uptime
系统	cr.node.sys.cpu.user.percent、cr.store.capacity、cr.node.sys.rss
SQL 工作负载	cr.node.sql.query.count、cr.node.exec.latency-p99
存储	cr.store.totalbytes、cr.store.livebytes
集群	cr.store.replicas、cr.store.ranges.unavailable
网络	cr.node.clock-offset.meannanos

示例：

{
  "metric_names": ["cr.node.sql.query.count", "cr.node.sys.cpu.user.percent"],
  "start_ms": 1775035140000,
  "end_ms": 1775035740000,
  "sample_ms": 60000
}

成功响应（上游 /ts/query 成功时返回 code: 0）：

{
  "status": "success",
  "type": "metrics_inspection",
  "data": {
    "code": 0,
    "desc": ""
  },
  "error": null
}

query-slow-sql

KWDB MCP Server 可通过对集群端系统表 kwdb_internal.node_statement_statistics 执行 SELECT 查询慢 SQL 语句。该工具接受可选参数 limit（默认值为 10）、min_latency_ms（默认值为 0）和 sort_by（默认值为 service_lat；支持 run_lat、plan_lat、count）。结果包含查询文本、四个延迟字段（单位为毫秒）和执行次数。

无论选择何种 sort_by，筛选始终针对 service_latency_ms 执行。默认调用会返回按平均服务延迟排序的前 10 条语句。

示例：

{
  "limit": 10,
  "min_latency_ms": 100,
  "sort_by": "service_lat"
}

成功响应（为简洁起见，已截断）：

{
  "data": [
    {
      "id": "1",
      "fingerprint": "1",
      "query": "SELECT count(_), max(\"timestamp\") FROM [DELETE FROM system.rangelog WHERE ...]",
      "service_latency_ms": 3.805022,
      "run_latency_ms": 0.649384,
      "plan_latency_ms": 1.041746,
      "count": 1
    }
  ],
  "status": "success",
  "type": "slow_sql_inspection"
}

query-metrics 和 query-slow-sql 都会复用同一个 X-Database-URI 标头（或默认连接池），并根据已保存的凭据生成 Basic Auth；管理端点 URL 会根据 DB URL 的主机自动生成。TLS 端点会跳过证书验证，以符合 KaiwuDB 使用自签名证书的惯例。

MCP 提示词

MCP 提示词支持 KWDB MCP Server 定义可复用的提示词模板和工作流，MCP 客户端可轻松将其呈现给用户和大模型。它们提供了一种强大的方式，用于标准化和共享常见的大模型交互。KWDB MCP Server 提供以下 MCP 提示词：

类型	提示词名称	描述
数据库说明	db_description	全面介绍 KWDB 数据库，包括核心功能、支持的特性和使用场景。
语法指南	syntax_guide	全面的 KWDB 语法指南，包括常见查询示例和最佳实践。
集群管理	cluster_management	全面的 KWDB 集群管理指南，包括节点管理、负载均衡和监控。
数据迁移	data_migration	KWDB 数据迁入和迁出的指南，包括导入／导出方法和最佳实践。
安装	installation	在各种环境中安装和部署 KWDB 的分步指南。
性能调优	performance_tuning	KWDB 性能优化指南，包括查询优化、索引策略和系统级调优。
问题排查	troubleshooting	诊断和解决 KWDB 常见问题与错误的指南。
备份与恢复	backup_restore	全面的 KWDB 数据库备份和恢复指南，包括策略、工具和最佳实践。
DBA 模板	dba_template	编写 MCP 提示词的模板和指南。

添加 MCP 提示词

MCP 提示词是存储在 pkg/prompts/docs/ 目录中的 Markdown 文件。使用 Go 的 embed 包编译 KWDB MCP Server 时，这些文件会嵌入二进制文件。目前，KWDB MCP Server 提供以下提示词文件：

• pkg/prompts/docs/ReadExamples.md：包含读取查询示例（使用 SELECT 语句）。
• pkg/prompts/docs/WriteExamples.md：包含写入查询示例（使用 INSERT、UPDATE、DELETE、CREATE、ALTER 语句）。
• pkg/prompts/docs/DBDescription.md：包含数据库说明。
• pkg/prompts/docs/SyntaxGuide.md：包含 SQL 语法指南。
• pkg/prompts/docs/ClusterManagementGuide.md：包含集群管理指南。
• pkg/prompts/docs/DataMigrationGuide.md：包含数据迁移指南。
• pkg/prompts/docs/InstallationGuide.md：包含安装指南。
• pkg/prompts/docs/PerformanceTuningGuide.md：包含性能调优指南。
• pkg/prompts/docs/TroubleShootingGuide.md：包含问题排查指南。
• pkg/prompts/docs/BackupRestoreGuide.md：包含备份与恢复指南。
• pkg/prompts/docs/DBATemplate.md：包含数据库管理模板。

添加 MCP 提示词的步骤如下：

1. 在 pkg/prompts/docs/ 目录中创建 Markdown 文件，例如 new_usecase.md。
2. 在 pkg/prompts/prompts.go 文件中添加变量和加载代码。
3. 为新的 MCP 提示词创建注册函数。
4. 在 pkg/prompts/prompts.go 文件的 registerUseCasePrompts() 中添加对该注册函数的调用。
5. 更新 README 文件。

有关如何添加 MCP 提示词的详情，请参阅 pkg/prompts/prompts.go 文件中的注释。

修改 MCP 提示词

如需修改 MCP 提示词，请按以下步骤操作：

1. 编辑 pkg/prompts/docs/ 目录中的特定 Markdown 文件。
2. 运行 make build 命令以重新构建应用程序。更新后的 MCP 提示词将嵌入二进制文件中。

从源代码构建

前提条件

• 安装 Go 1.23 或更高版本。
• 下载并安装 PostgreSQL 驱动程序 lib/pq。
• 安装并启动 KWDB，配置身份验证方式并创建数据库。详情请参阅 KWDB 文档网站。
• 创建一个在表和数据库上具有适当权限的用户。详情请参阅创建用户。

步骤

1. 克隆代码仓库。

   git clone https://gitee.com/kwdb/kwdb-mcp-server
   cd kwdb-mcp-server
   

2. 安装依赖项。

   make deps
   

3. 构建应用程序。

   make build
   

构建成功后，应用程序将采用以下结构。

kwdb-mcp-server/
├── bin/
│   └── kwdb-mcp-server      # Binary executable file
├── cmd/
│   └── kwdb-mcp-server/
│       └── main.go           # The main application
├── pkg/
│   ├── db/
│   │   └── db.go             # Database operations
│   ├── prompts/
│   │   ├── prompts.go        # MCP Prompts
│   │   └── docs/             # MCP Prompts files
│   │       ├── ReadExamples.md     # Read query examples
│   │       ├── WriteExamples.md    # Write query examples
│   │       ├── DBDescription.md    # Database descriptions
│   │       ├── SyntaxGuide.md      # SQL Syntax guide
│   │       ├── ClusterManagementGuide.md # Cluster management guide
│   │       ├── DataMigrationGuide.md    # Data migration guide
│   │       ├── InstallationGuide.md      # Installation guide
│   │       ├── PerformanceTuningGuide.md # Performance tunning
│   │       ├── TroubleShootingGuide.md   # Troubleshooting guide
│   │       ├── BackupRestoreGuide.md     # Backup and restore guide
│   │       └── DBATemplate.md            # DBA templates
│   ├── resources/
│   │   └── resources.go      # MCP Resources
│   ├── server/
│   │   └── server.go         # KWDB MCP Server configurations
│   ├── tools/
│   │   └── tools.go          # MCP Tools
│   └── version/
│       └── version.go        # Version information
├── Makefile                  # Commands for building and running the KWDB MCP Server
└── README.md                 # README file

启动 KWDB MCP 服务

KWDB MCP 服务支持三种传输模式：

• StdIO（标准输入/输出）模式：使用标准输入/输出进行通信。这是默认模式。
• HTTP 模式（推荐）：使用 HTTP 进行通信。这是推荐用于生产环境的模式。
• SSE（服务器发送事件）模式（已弃用）：使用 HTTP POST 和 SSE 进行通信。此模式即将弃用。

运行模式

• 单数据库（兼容模式）：以可选的 PostgreSQL 连接字符串作为第一个参数启动服务（或通过 Makefile 中的 CONNECTION_STRING 设置）。服务会初始化默认连接池。调用 read-query 和 write-query 工具时可以不带 X-Database-URI 请求头；它们会使用此默认连接池。
• 无状态多租户模式：启动服务时不提供连接字符串（例如，./bin/kwdb-mcp-server 或 ./bin/kwdb-mcp-server -t http -p 8080）。在调用工具之前，服务不会连接任何数据库。每次调用 read-query 和 write-query 时，必须在请求头中发送包含完整 PostgreSQL 连接字符串的 X-Database-URI；否则工具会返回错误：missing X-Database-URI header。
• 自动推导管理端点：检查工具（query-metrics、query-slow-sql）会根据连接字符串中的主机推导管理端点 URL（默认端口为 8080），并从同一连接字符串中推导 Basic Auth 凭据。无需单独配置管理端点；连接字符串中的 sslmode 和证书路径会决定通过 http 还是 https 访问管理端点。如需为单个请求覆盖推导出的管理端点 URL，请发送 X-Admin-Base-URL。

---

StdIO 模式

• 运行 KWDB MCP 服务（单数据库模式下可选连接字符串）：

  ./bin/kwdb-mcp-server "postgresql://<username>:<password>@<hostname>:<port>/<database_name>?sslmode=disable"
  

• 也可以不提供连接字符串，以无状态模式运行；此时，每次调用 read-query / write-query 都必须发送 X-Database-URI 标头。检查工具（query-metrics、query-slow-sql）会自动从同一连接字符串派生管理端点 URL 和 Basic Auth；发送 X-Admin-Base-URL 可覆盖派生的 URL。

  ./bin/kwdb-mcp-server
  

• 使用 Makefile 运行 KWDB MCP 服务：

  CONNECTION_STRING="postgresql://<username>:<password>@<hostname>:<port>/<database_name>?sslmode=disable" make run
  

参数：

• username：连接 KWDB 数据库的用户名。
• password：用于身份验证的密码。
• hostname：KWDB 数据库的 IP 地址。
• port：连接 KWDB 数据库的端口。
• database_name：要访问的 KWDB 数据库名称。
• sslmode：SSL 模式。支持的值：disable、allow、prefer、require、verify-ca、verify-full。详情请参阅 SSL 模式参数。

---

HTTP 模式（推荐）

• 以 HTTP 模式运行 KWDB MCP 服务：

  CONNECTION_STRING="postgresql://<username>:<password>@<hostname>:<port>/<database_name>?sslmode=disable" PORT=8080 make run-http
  

• HTTP 服务默认监听 0.0.0.0:<port>，MCP 端点为 http://<host>:<port>/mcp。以无连接字符串的方式启动（无状态模式）时，客户端必须在每次调用 read-query / write-query 时发送 X-Database-URI 请求标头。

• 检查工具（query-metrics、query-slow-sql）会从 X-Database-URI 连接字符串派生 Basic Auth 和管理端点 URL；发送 X-Admin-Base-URL 可覆盖派生的 URL。

• HTTPS（TLS） 为可选项：传入 --tls-cert 和 --tls-key，并指定 PEM 文件路径。之后，服务将以 TLS 方式监听；MCP 端点为 https://<host>:<port>/mcp。如果只设置其中一个标志，进程将报错退出。TLS 通过 mcp-go 的 WithTLSCert 实现（要求 mcp-go v0.39+）。

  ./bin/kwdb-mcp-server -t http -p 8443 --tls-cert /path/to/cert.pem --tls-key /path/to/key.pem "postgresql://..."
  

参数：

• -t 或 --transport：传输类型，支持 stdio、sse、http。
  • stdio：标准输入/输出模式
  • sse：SSE 模式（已弃用）
  • http：HTTP 模式（推荐）
• -p 或 --port：KWDB MCP 服务的监听端口，默认为 8080。
• --tls-cert / --tls-key：可选。HTTP 模式 HTTPS 所用的 PEM 证书和私钥。必须同时设置；仅在 -t http 时生效。
• username：连接 KWDB 数据库的用户名。
• password：用于身份验证的密码。
• hostname：KWDB 数据库的 IP 地址。
• port：连接 KWDB 数据库的端口。
• database_name：要访问的 KWDB 数据库名称。
• sslmode：SSL 模式。支持的值：disable、allow、prefer、require、verify-ca、verify-full。详情请参阅 SSL 模式参数。

---

SSE 模式（已弃用）

注意

SSE 模式已弃用，并将在未来版本中移除。如果可能，请使用 HTTP 模式。

• 以 SSE 模式运行 KWDB MCP Server（也可以省略 CONNECTION_STRING 以使用无状态模式；此时客户端必须在每次调用工具时发送 X-Database-URI）：

  CONNECTION_STRING="postgresql://<username>:<password>@<hostname>:<port>/<database_name>?sslmode=disable" PORT=8080 make run-sse
  

参数：

• -t 或 --transport：传输类型，支持 stdio、sse、http。
  • stdio：标准输入/输出模式
  • sse：SSE 模式（已弃用）
  • http：HTTP 模式（推荐）
• -p 或 --port：KWDB MCP Server 的监听端口，默认值为 8080。
• username：连接 KWDB 数据库的用户名。
• password：身份验证密码。
• hostname：KWDB 数据库的 IP 地址。
• port：连接 KWDB 数据库的端口。
• database_name：要访问的 KWDB 数据库名称。
• sslmode：SSL 模式。支持的值：disable、allow、prefer、require、verify-ca、verify-full。详情请参阅 SSL 模式参数。

与大模型 Agent 集成

有关 KWDB MCP Server 如何与大模型 Agent 集成的详情，请参阅与大模型 Agent 集成。

故障排查

有关 KWDB MCP Server 故障排查的详情，请参阅故障排查。

文档

有关 KWDB MCP Server 的文档，请参阅 KWDB 文档网站。

后续改进

• 查询历史：实现查询历史功能。
• 远程模式：支持连接远程 KWDB MCP Server。
• 改进优化建议：增强查询优化建议。
• 指标资源：添加数据库指标。

贡献

欢迎贡献！请随时提交问题和拉取请求。

许可证

本项目采用 MIT 许可证。

致谢

• mark3labs/mcp-go - MCP Go 服务端框架
• lib/pq - PostgreSQL Go 驱动程序

其他

kwdb-mcp-server 已被 MCP Review 收录并认证