使用说明

项目简介

本项目是基于 Microsoft Semantic Kernel 开发的数据库Agent MCP服务器，旨在为大型语言模型（LLM）客户端提供通过自然语言查询数据库的能力。它利用Semantic Kernel的强大功能，将数据库操作封装成易于LLM调用的工具，并通过模型上下文协议（MCP）以标准化的方式对外提供服务。

主要功能点

自然语言数据库查询： 允许LLM客户端使用自然语言提问，服务器将其转换为SQL查询并在数据库中执行，返回结果。
数据库Schema记忆： 服务器能够学习并记忆数据库的schema信息，包括表结构和关系，从而更准确地理解用户查询。
质量保证： 内置查询质量保证功能，例如查询相关性过滤，以降低不安全或无效查询的风险。
Docker部署： 支持Docker镜像部署，方便快捷地在容器化环境中运行和管理服务器。
多种数据库支持： 理论上支持Semantic Kernel和.NET Data Provider支持的多种数据库，如SQL Server, SQLite, MySQL, PostgreSQL等。
SSE和HTTP端点暴露： 通过Server-Sent Events (SSE) 和 HTTP 协议提供MCP服务，方便LLM客户端连接。

安装步骤

环境准备： 确保已安装 .NET 8.0 SDK 和 Docker (如果选择Docker部署)。
Docker镜像部署 (推荐): 使用Docker命令直接拉取并运行预构建的MCP服务器镜像。
```
docker run -it --rm -p 8080:5000 ghcr.io/kbeaugrand/database-mcp-server
```
你也可以根据需要通过环境变量配置数据库连接、AI模型等参数，详细参数见 服务器配置 部分。
本地构建运行 (进阶):

a. 克隆仓库 https://github.com/kbeaugrand/SemanticKernel.Agents.DatabaseAgent 到本地。

b. 导航到 'src/SemanticKernel.Agents.DatabaseAgent.MCPServer' 目录。

c. 使用 .NET CLI 构建项目：
```
dotnet build
```
d. 运行 MCP 服务器：
```
dotnet run
```
你可以在 'appsettings.json' 或环境变量中配置服务器参数，详细参数见 服务器配置 部分。

服务器配置

MCP 服务器主要通过环境变量进行配置 (Docker 部署) 或 'appsettings.json' 文件 (本地运行)。以下是关键配置参数，在MCP客户端配置连接时需要提供类似信息：

{
  "serverName": "DatabaseAgentMCP",
  "command": "docker run",
  "args": [
    "ghcr.io/kbeaugrand/database-mcp-server",
    "-p", "8080:5000",
    "-e", "DATABASE_PROVIDER=sqlite",  // 数据库提供商，例如：sqlite, sqlserver, mysql, postgresql
    "-e", "DATABASE_CONNECTION_STRING=\"Data Source=northwind.db;Mode=ReadWrite\"", // 数据库连接字符串
    "-e", "MEMORY_KIND=Volatile", // 内存存储类型，例如：Volatile (内存), SQLite, Qdrant
    "-e", "KERNEL_COMPLETION=gpt4omini", // 用于补全服务的Kernel名称
    "-e", "KERNEL_EMBEDDING=textembeddingada002", // 用于embedding服务的Kernel名称
    "-e", "SERVICES_GPT4OMINI_TYPE=AzureOpenAI", // 补全服务类型，例如：AzureOpenAI, Ollama
    "-e", "SERVICES_GPT4OMINI_ENDPOINT=https://xxx.openai.azure.com/", // 补全服务API端点
    "-e", "SERVICES_GPT4OMINI_AUTH=APIKey", // 补全服务认证方式，例如：APIKey
    "-e", "SERVICES_GPT4OMINI_API_KEY=xxx", // 补全服务API Key
    "-e", "SERVICES_GPT4OMINI_DEPLOYMENT=gpt-4o-mini", // 补全服务部署名称
    "-e", "SERVICES_TEXTEMBEDDINGADA002_TYPE=AzureOpenAI", // Embedding服务类型
    "-e", "SERVICES_TEXTEMBEDDINGADA002_ENDPOINT=https://xxx.openai.azure.com/", // Embedding服务API端点
    "-e", "SERVICES_TEXTEMBEDDINGADA002_AUTH=APIKey", // Embedding服务认证方式
    "-e", "SERVICES_TEXTEMBEDDINGADA002_API_KEY=xxx", // Embedding服务API Key
    "-e", "SERVICES_TEXTEMBEDDINGADA002_DEPLOYMENT=text-embedding-ada-002" // Embedding服务部署名称
  ]
}

参数注释:

'DATABASE_PROVIDER': 指定数据库类型，根据实际使用的数据库选择，例如 'sqlite', 'sqlserver', 'mysql', 'postgresql' 等。
'DATABASE_CONNECTION_STRING': 数据库连接字符串，根据所选数据库类型配置。
'MEMORY_KIND': 指定向量数据库的存储类型，'Volatile' 表示使用内存存储（重启后数据丢失），'SQLite' 或 'Qdrant' 为持久化存储。
'KERNEL_COMPLETION', 'KERNEL_EMBEDDING': 指定 Semantic Kernel 中配置的用于补全和 embedding 服务的名称。
'SERVICES_*': 以 'SERVICES_' 开头的环境变量用于配置具体的AI服务，例如 'AzureOpenAI' 或 'Ollama'。需要根据所选的AI服务，配置相应的 'TYPE', 'ENDPOINT', 'AUTH', 'API_KEY', 'DEPLOYMENT' 等参数。示例中配置了 Azure OpenAI 的 'gpt4omini' (Completion) 和 'textembeddingada002' (Embedding) 服务。

注意: 请根据实际使用的数据库、AI模型服务以及网络环境，修改上述配置参数。特别是 'DATABASE_CONNECTION_STRING' 和 'SERVICES_*' 相关参数需要替换为真实有效的值。

基本使用方法

启动 MCP 服务器: 根据 安装步骤 中的方法启动服务器，确保服务器成功运行并监听在指定的端口 (默认为 8080)。
配置 MCP 客户端: 在您的 MCP 客户端应用中，配置连接到本 MCP 服务器。需要提供服务器地址 (例如 'http://localhost:8080' 如果使用 SSE 传输) 以及 服务器配置 中描述的配置信息 (例如 JSON 格式的 'command' 和 'args')。
发送工具调用请求: 使用 MCP 客户端向服务器发送 'CallTool' 请求，工具名称为 'DatabaseAgentMCP' (或您在 'serverName' 中配置的名称)，请求参数 'arguments' 中包含 'message' 字段，其值为自然语言形式的数据库查询问题。
接收查询结果: 服务器会处理您的查询，执行SQL，并将查询结果以文本形式 (Markdown 格式) 通过 MCP 响应返回给客户端。

示例查询: 假设您想知道有多少客户，您可以向 MCP 服务器发送如下 'CallTool' 请求， 'message' 参数设置为 "How many customers do I have?"。服务器将返回包含查询结果的 MCP 响应。

{
  "jsonrpc": "2.0",
  "method": "CallTool",
  "params": {
    "name": "DatabaseAgentMCP",
    "arguments": {
      "message": "How many customers do I have?"
    }
  },
  "id": "123"
}

关键词