项目简介

本项目 'mcp-sql' 是一个基于 Model Context Protocol (MCP) 的示例项目，展示了如何构建一个 MCP 服务器，该服务器允许大型语言模型 (LLM) 通过自然语言安全地与 SQLite 数据库进行交互。通过此项目，您可以了解 MCP 协议如何作为桥梁，连接 AI 系统与外部数据源和工具，实现更强大的应用。

主要功能点

MCP 服务器实现: 提供了一个基于 Python FastMCP 框架构建的 MCP 服务器 ('mcp_server.py')。
工具注册与执行: 服务器注册了一个名为 'query_data' 的工具，允许客户端（LLM）执行 SQL 查询语句。
安全数据库访问: LLM 客户端无法直接访问数据库，所有数据库操作都通过 MCP 服务器中定义的工具进行，保障数据安全。
自然语言接口: 通过 MCP 协议，LLM 可以将用户的自然语言查询转换为 SQL 语句，并执行查询，返回结果。
示例 Prompt 模板: 包含一个简单的 Prompt 模板 ('example_prompt')，虽然在本示例中未使用，但展示了 MCP 服务器定义和管理 Prompt 的能力。
Stdio 传输协议: 使用 Stdio 作为 MCP 服务器和客户端之间的通信协议，简化了本地演示的部署。

安装步骤

安装 Python 3.12+: 确保您的系统已安装 Python 3.12 或更高版本。
设置 Groq API 密钥: 在项目根目录下创建 '.env' 文件，并添加您的 Groq API 密钥：
```
GROQ_API_KEY=your_api_key_here
```
如果您没有 Groq API 密钥，您需要注册并获取。

安装依赖: 使用以下命令创建虚拟环境并安装项目依赖：

uv venv .venv --python=3.12
.venv\Scripts\activate  # 或 source .venv/bin/activate (Linux/macOS)
uv pip install -e .

初始化数据库 (可选): 如果需要重新初始化数据库，可以运行 'init_database.py' 脚本：
```
python src/mcp_sql/init_database.py
```

服务器配置

对于 MCP 客户端（例如 'mcp_client.py'），需要配置连接到 MCP 服务器的参数。本示例使用 Stdio 传输协议，以下是客户端需要配置的服务器信息：

{
  "server_name": "Demo",
  "transport": "stdio",
  "command": "python",
  "args": ["src/mcp_sql/mcp_server.py"]
}

参数说明:

'server_name': MCP 服务器的名称，本示例为 "Demo" (在 'mcp_server.py' 中定义)。
'transport': 使用的传输协议，本示例为 "stdio"。
'command': 启动 MCP 服务器的命令，这里使用 'python' 命令。
'args': 启动命令的参数，指定 MCP 服务器脚本的路径，即 '["src/mcp_sql/mcp_server.py"]'。

注意: 'mcp_client.py' 代码中已硬编码了这些配置，您无需手动配置，此处仅为说明 MCP 客户端如何连接到服务器。

基本使用方法

运行演示脚本: 双击运行 'run_sql_demo.bat' (Windows) 或手动执行以下命令 (Linux/macOS)：

start cmd /k ".venv\Scripts\activate && python src/mcp_sql/mcp_server.py"  # Windows
.venv/bin/activate && python src/mcp_sql/mcp_server.py & python src/mcp_sql/mcp_client.py # Linux/macOS (可能需要调整)

这将同时启动 MCP 服务器和客户端，并打开两个命令行窗口。

在客户端窗口输入自然语言查询: 在客户端窗口中，您可以输入自然语言查询，例如：
- 'all users'
- 'users older than 30'
- 'average age of users'
- 'add a new user named Alice Smith with email [email protected] and age 35'
查看查询结果: 客户端会将您的自然语言查询发送给 LLM，LLM 将调用 MCP 服务器提供的 'query_data' 工具执行 SQL 查询，并将结果返回到客户端窗口显示。
退出程序: 在客户端窗口输入 'exit' 或 'quit' 即可退出程序。

通过这个示例，您可以体验如何使用 MCP 协议和 MCP 服务器，构建能够安全有效地利用外部工具和数据源的 LLM 应用。

关键词

项目简介

主要功能点

安装步骤

服务器配置

基本使用方法

信息