关键词数据库-MCP服务器

Name: 关键词数据库-MCP服务器
Author: KWDB

作者：KWDB4 星标更新：2025-10-28

安装使用来源：spider==github.com

项目介绍

技术文档摘要

KWDB MCP Server

中文版

概述

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

架构

KWDB MCP Server 的核心过程由以下组件组成：

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

特性

读操作：执行 SELECT、SHOW、EXPLAIN 等只读查询。
写操作：执行 INSERT、UPDATE、DELETE 和 CREATE、DROP、ALTER DDL 操作。
数据库信息：获取有关数据库的信息，包括表及其模式。
语法指南：通过提示访问 KWDB 的综合语法指南。

标准 API 响应：提供一致的错误处理机制。

工具错误：错误信息被包装在带有 isError 标志的结果对象中。

{
  "content": [{"type": "text", "text": "查询错误：错误详情"}],
  "isError": true
}

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

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32002,  // RESOURCE_NOT_FOUND: 资源不存在
    "message": "未找到资源 URI 'kwdb://table/nonexistent' 的处理器：资源未找到"
  }
}

或内部处理错误：

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32603,  // INTERNAL_ERROR: 内部资源处理错误
    "message": "无法获取表 'tablename' 的模式：数据库连接错误"
  }
}

成功响应：工具返回结果对象，资源返回内容数组。

自动 LIMIT：通过自动为没有 LIMIT 子句的 SELECT 查询添加 LIMIT 20 子句来防止产生大量结果集。

安全性

KWDB MCP Server 提供了以下安全措施：

提供单独的读写操作工具。
验证查询以确保它们符合预期的操作类型。
对未经授权的操作打印清晰的错误消息。

MCP 资源

MCP 资源允许 KWDB MCP Server 暴露可以被 MCP 客户端读取的数据和内容，并将其用作 LLM 交互的上下文。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 工具，LLMs 可以与外部系统进行交互。KWDB MCP Server 提供以下 MCP 工具。

read-query

KWDB MCP Server 执行 SELECT、SHOW、EXPLAIN 语句和其他只读查询以从数据库中读取数据。read_query 函数以数组格式返回 SQL 语句的查询结果。此外，KWDB MCP Server 将自动为没有 LIMIT 子句的 SELECT 查询添加 LIMIT 20 子句以防止产生大量结果集。

示例：

-- 查询表数据。
SELECT * FROM users LIMIT 10;

-- 列出所有创建的表。
SHOW TABLES;

-- 执行 SQL 查询并生成关于 SQL 查询的详细信息。
EXPLAIN ANALYZE SELECT * FROM orders WHERE user_id = 1;

write-query

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

示例：

-- 向表中插入数据。
INSERT INTO users (name, email) VALUES ('John Doe', 'john@example.com');

-- 更新表中的数据。
UPDATE users SET email = 'new-email@example.com' WHERE id = 1;

-- 从表中删除数据。
DELETE FROM users WHERE id = 1;

-- 创建一个表。
CREATE TABLE products (id SERIAL PRIMARY KEY, name TEXT, price DECIMAL);

-- 向表中添加一列。
ALTER TABLE products ADD COLUMN description TEXT;

-- 删除一个表。
DROP TABLE products;

MCP 提示

MCP 提示使 KWDB MCP Server 能够定义 MCP 客户端可以轻松呈现给用户和 LLM 的可重用提示模板和工作流。它们提供了一种强大的方式来标准化和共享常见的 LLM 交互。KWDB MCP Server 提供以下 MCP 提示：

类型	提示名称	描述
数据库描述	`db_description`	包括核心功能、支持特性及使用场景的 KWDB 数据库的综合描述。
语法指南	`syntax_guide`	包括常见查询示例和最佳实践的 KWDB 综合语法指南。
集群管理	`cluster_management`	包括节点管理、负载均衡和监控的集群管理综合指南。
数据迁移	`data_migration`	包括导入/导出方法和最佳实践的数据迁移指南。
安装	`installation`	在各种环境中安装和部署 KWDB 的逐步指南。
性能调优	`performance_tuning`	包括查询优化、索引策略和系统级调优的性能优化指南。
故障排除	`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 提示，请遵循以下步骤：

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

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

修改 MCP 提示

要修改 MCP 提示，请遵循以下步骤：

编辑 pkg/prompts/docs/ 目录中的特定 Markdown 文件。
运行 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      # 二进制可执行文件
├── cmd/
│   └── kwdb-mcp-server/
│       └── main.go           # 主应用程序
├── pkg/
│   ├── db/
│   │   └── db.go             # 数据库操作
│   ├── prompts/
│   │   ├── prompts.go        # MCP 提示
│   │   └── docs/             # MCP 提示文件
│   │       ├── ReadExamples.md     # 读查询示例
│   │       ├── WriteExamples.md    # 写查询示例
│   │       ├── DBDescription.md    # 数据库描述
│   │       ├── SyntaxGuide.md      # SQL 语法指南
│   │       ├── ClusterManagementGuide.md # 集群管理指南
│   │       ├── DataMigrationGuide.md    # 数据迁移指南
│   │       ├── InstallationGuide.md      # 安装指南
│   │       ├── PerformanceTuningGuide.md # 性能调优
│   │       ├── TroubleShootingGuide.md   # 故障排除指南
│   │       ├── BackupRestoreGuide.md     # 备份和恢复指南
│   │       └── DBATemplate.md            # DBA 模板
│   ├── resources/
│   │   └── resources.go      # MCP 资源
│   ├── server/
│   │   └── server.go         # KWDB MCP Server 配置
│   ├── tools/
│   │   └── tools.go          # MCP 工具
│   └── version/
│       └── version.go        # 版本信息
├── Makefile                  # 构建和运行 KWDB MCP Server 的命令
└── README.md                 # README 文件

启动 KWDB MCP Server

KWDB MCP Server 支持三种传输模式：

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

StdIO 模式

使用 PostgreSQL 连接字符串运行 KWDB MCP Server：

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

使用 Makefile 运行 KWDB MCP Server：

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 Server：

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。

参数：

-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 模式参数。

SSE 模式（已弃用）

注意

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

在 SSE 模式下运行 KWDB MCP Server：

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 模式参数。

与 LLM 代理集成

有关 KWDB MCP Server 如何与 LLM 代理集成的详细信息，请参阅与 LLM 代理集成。

故障排除

有关如何排查 KWDB MCP Server 故障的详细信息，请参阅故障排除。

文档

有关 KWDB MCP Server 的文档，请参阅 [KWDB 文档网站](https://www.kaiwudb.com/kaiwudb_docs/#/oss_dev/development/connect-k