KWDB MCP服务器

中文版

概述

KWDB MCP服务器是基于主控程序（模型上下文协议）协议，它提供了一组工具和资源，用于与KWDB数据库交互，并通过MCP协议提供商业智能功能。KWDB MCP服务器支持读取、写入、查询、修改数据和执行DDL操作。

建筑

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

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

![](./docs/asset/kwdb_mcp_server_design_en.png)

特性

读取操作：执行 SELECT, SHOW, EXPLAIN，以及其他只读查询。
写入操作：执行 INSERT, UPDATE, DELETE，以及 CREATE, DROP, ALTER DDL操作。
数据库信息：获取有关数据库的信息，包括表及其模式。
语法指南：通过Prompts访问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 20 条款to SELECT 没有a的查询 LIMIT 条款。

安全

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

为读写操作提供单独的工具。
有效的查询，以确保它们与预期的操作类型匹配。
为未经授权的操作打印清晰的错误消息。

![](./docs/asset/mcp-server-security_en.png)

MCP资源

MCP资源允许KWDB MCP服务器公开MCP客户端可以读取的数据和内容，并用作LLM交互的上下文。KWDB MCP服务器提供以下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服务器能够向MCP客户端公开可执行功能。通过MCP工具，LLM可以与外部系统交互。KWDB MCP服务器提供以下MCP工具。

读取查询

KWDB MCP服务器执行 SELECT, SHOW, EXPLAIN 以从数据库读取数据。这 read_query 函数以SQL语句的数组格式返回查询结果。此外，KWDB MCP服务器将自动添加 LIMIT 20 条款to SELECT 没有a的查询 LIMIT 子句以防止大型结果集。

示例：

-- 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;

写查询

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

示例：

-- Insert data into the table.
INSERT INTO users (name, email) VALUES ('John Doe', 'john@example.com');

-- Update data in the table.
UPDATE users SET email = 'new-email@example.com' 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;

查询度量历史记录

KWDB MCP服务器可以通过数据库管理员查询历史运行时指标 /ts/query API此工具接受毫秒时间戳，将字符串聚合转换为后端枚举值，并规范响应中的时间戳。

示例：

{
  "start_ms": 1775035140000,
  "end_ms": 1775035740000,
  "sample_ms": 60000,
  "queries": [
    {
      "name": "cr.node.sql.query.count",
      "downsampler": "avg",
      "source_aggregator": "sum",
      "derivative": "rate"
    }
  ]
}

MCP提示

MCP Prompts使KWDB MCP服务器能够定义可重用的提示模板和工作流，MCP客户端可以轻松地向用户和LLM展示。它们提供了一种强大的方法来标准化和共享常见的LLM交互。KWDB MCP服务器提供以下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/ 目录。在使用Go编译KWDB MCP服务器时，这些文件被嵌入到二进制文件中 embed 包裹。目前，KWDB MCP服务器提供以下提示文件：

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提示，请执行以下步骤：

在中创建Markdown文件 pkg/prompts/docs/ 目录，例如 new_usecase.md.
在中添加变量和负载代码 pkg/prompts/prompts.go 文件。
为新的MCP提示创建注册功能。
将注册函数调用添加到 registerUseCasePrompts() 在 pkg/prompts/prompts.go 文件。
更新 README 文件。

有关如何添加MCP提示的详细信息，请参阅 pkg/prompts/prompts.go 文件。

修改MCP提示

要修改MCP提示，请执行以下步骤：

在中编辑特定的Markdown文件 pkg/prompts/docs/ 目录。
跑吧 make build 命令重建应用程序。更新的MCP提示将嵌入二进制文件中。

从源代码构建

先决条件

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

步骤

克隆存储库。

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

安装依赖项。

   make deps

构建应用程序。

   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连接字符串作为第一个参数启动服务器（或通过 CONNECTION_STRING 在Makefile中）。服务器初始化默认连接池。工具 read-query 和 write-query 可以被称为没有这 X-Database-URI 头球他们使用这个默认池。
无国籍多租户：启动服务器没有连接字符串（例如。 ./bin/kwdb-mcp-server 或 ./bin/kwdb-mcp-server -t http -p 8080).在调用工具之前，服务器不会打开任何数据库。每 read-query 和 write-query 呼叫必须发送请求标头 X-Database-URI 带有完整的PostgreSQL连接字符串；否则工具返回错误： missing X-Database-URI header.
管理员端点默认值：历史指标查询使用数据库管理员HTTP端点。您可以通过以下方式设置默认值 --admin-base-url，或发送 X-Admin-Base-URL 每次工具调用。如果两者都没有提供， query-metrics-history 回报 missing X-Admin-Base-URL header.

______________________________________________________________________

标准IO模式

运行KWDB MCP服务器（在单DB模式下使用可选连接字符串）：

  ./bin/kwdb-mcp-server "postgresql://:
@:
/?sslmode=disable"

或者在无状态模式下不使用连接字符串运行；每个 read-query / write-query 呼叫必须发送 X-Database-URI 头球历史指标调用还必须提供 X-Admin-Base-URL 除非您使用启动服务器 --admin-base-url.

  ./bin/kwdb-mcp-server

使用Makefile运行KWDB MCP服务器：

  CONNECTION_STRING="postgresql://:
@:
/?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://:
@:
/?sslmode=disable" PORT=8080 make run-http

HTTP服务侦听 `0.0.0.0:

默认情况下，MCP端点为 http://: /mcp。当在没有连接字符串的情况下启动时（无状态模式），客户端必须发送 X-Database-URI 每个请求头 read-query / write-query` 电话。

对于 query-metrics-history，客户端必须发送 X-Admin-Base-URL 每次工具调用时，除非服务器已启动 --admin-base-url.

HTTPS（TLS） 可选：通过两者 --tls-cert 和 --tls-key 使用PEM文件路径。然后，服务器使用TLS进行监听；MCP端点为 `https://:

/mcp如果只设置了这两个标志中的一个，则进程将退出并返回错误。TLS是通过以下方式实现的 [mcp走](https://github.com/mark3labs/mcp-go) WithTLSCert` （要求mcp达到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.
--admin-base-url：可选。目标KWDB实例的默认管理员HTTP基本URL，由使用 query-metrics-history.
--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服务器（或省略 CONNECTION_STRING 无状态模式；那么客户端必须发送 X-Database-URI 每次工具调用）：

  CONNECTION_STRING="postgresql://:
@:
/?sslmode=disable" PORT=8080 make run-sse

参数：

-t 或 --transport：运输类型，支架 stdio, sse, http.

- stdio：标准输入/输出模式 - sse：SSE模式（已弃用） - http：HTTP模式（推荐）

-p 或 --port：KWDB MCP服务器的侦听端口，默认为 8080.
username：连接到KWDB数据库的用户名。
password：身份验证密码。
hostname：KWDB数据库的IP地址。
port：用于连接KWDB数据库的端口。
database_name：要访问的KWDB数据库的名称。
sslmode：SSL模式。支持的值： disable, allow, prefer, require, verify-ca, verify-full。有关详细信息，请参阅 SSL模式参数.

与LLM代理集成

有关KWDB MCP服务器如何与LLM代理集成的详细信息，请参阅与LLM代理集成.

故障排除

有关如何对KWDB MCP服务器进行故障排除的详细信息，请参阅故障排除.

文档

有关KWDB MCP服务器的文档，请参阅 KWDB文档网站.

未来改进

\[ \] 查询历史：实现查询历史功能。
\[x\] 远程模式：支持连接到远程KWDB MCP服务器。
\[x\] 改进的优化建议：增强查询优化建议。
\[ \] 度量资源：a添加数据库指标。

贡献

欢迎投稿！请随时提交问题和拉取请求。

许可证

该项目根据MIT许可证获得许可。

致谢

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

其他

kwdb-mcp服务器由以下机构索引和认证 MCP审查

Kwdb MCP Server

快速接入

详细介绍

KWDB MCP服务器

概述

建筑

特性

安全

MCP资源

MCP工具

读取查询

写查询

查询度量历史记录

MCP提示

添加MCP提示

修改MCP提示

从源代码构建

先决条件

步骤

启动KWDB MCP服务器

标准IO模式

HTTP模式（推荐）

SSE模式（已弃用）

与LLM代理集成

故障排除

文档

未来改进

贡献

许可证

致谢

其他

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP