# SQLite MCP 服务器

一个基于Python实现的SQLite标准MCP（Model Context Protocol）服务器，支持数据库的读写操作，使用Docker进行容器化部署，以stdio模式运行，支持自然语言交互。

## 功能特性

- 🔍 **SQL查询执行**: 支持SELECT查询语句
- ✏️ **数据更新操作**: 支持INSERT、UPDATE、DELETE语句
- 📋 **表管理**: 列出所有表、查看表结构、创建新表
- 🗣️ **自然语言交互**: 支持中文自然语言建表和查询
- 🔒 **并发控制**: 支持多Agent并发访问和事务管理
- 🐳 **Docker部署**: 完整的容器化支持
- ⚙️ **配置管理**: 灵活的环境变量配置
- 📝 **日志记录**: 完整的操作日志记录
- 🧪 **测试覆盖**: 完整的测试和演示脚本
- 🌐 **stdio模式**: 标准MCP协议，支持自然语言交互
- 📋 **初始化脚本**: 支持配置文件方式启动和初始化
- 🚀 **一键启动**: Docker拉起即可使用，无需额外脚本

## 项目结构

```
db/
├── config/                 # 配置模块
│   ├── __init__.py
│   ├── settings.py        # 应用配置
│   └── example.env        # 示例环境配置
├── database/              # 数据库模块
│   ├── __init__.py
│   ├── connection.py      # 数据库连接管理
│   ├── advanced_connection.py  # 高级连接管理
│   └── multi_agent_manager.py  # 多Agent管理器
├── mcp/                   # MCP服务器模块
│   ├── __init__.py
│   ├── server.py          # 标准MCP服务器实现
│   ├── simple_server.py   # 简化MCP服务器实现
│   ├── enhanced_server.py # 增强版MCP服务器（支持并发）
│   └── natural_language_server.py # 自然语言MCP服务器
├── init/                  # 初始化脚本
│   └── init.sql          # 数据库初始化SQL脚本
├── examples/              # 使用示例
│   ├── usage_examples.md  # 详细使用示例
│   ├── concurrent_usage_example.py # 并发使用示例
│   ├── multi_agent_concurrency_example.py # 多Agent并发示例
│   └── natural_language_example.py # 自然语言使用示例
├── docs/                  # 文档
│   ├── usage_guide.md     # 使用指南
│   ├── concurrency_control.md # 并发控制文档
│   ├── multi_agent_concurrency.md # 多Agent并发文档
│   └── natural_language_usage.md # 自然语言使用指南
├── data/                  # 数据目录（Docker卷挂载）
├── main.py               # 主程序入口 (stdio模式)
├── main_enhanced.py      # 增强版主程序（支持并发）
├── main_natural_language.py # 自然语言主程序
├── test_server.py        # 测试脚本
├── test_stdio.py         # stdio模式测试脚本
├── demo.py               # 演示脚本
├── query.sh              # 简化查询脚本
├── requirements.txt      # Python依赖
├── Dockerfile           # Docker镜像配置
├── docker-compose.yml   # Docker Compose配置
├── .gitignore           # Git忽略文件
├── .dockerignore        # Docker忽略文件
└── README.md            # 项目说明
```

## 快速开始

### 方法1: Docker启动（推荐）

1. **克隆项目**
   ```bash
   git clone <repository-url>
   cd db
   ```

2. **启动服务器**
   ```bash
   # 标准模式
   docker-compose up --build
   
   # 增强模式（支持并发）
   docker-compose -f docker-compose.yml up --build enhanced
   
   # 自然语言模式
   docker-compose -f docker-compose.yml up --build natural-language
   ```

3. **服务器将自动初始化数据库并进入stdio模式**

### 方法2: 本地启动

```bash
# 标准模式
python main.py

# 增强模式（支持并发）
python main_enhanced.py

# 自然语言模式
python main_natural_language.py
```

### 方法3: 直接Docker调用

```bash
# 构建镜像
docker-compose build

# 查询数据库信息
./query.sh info

# 查询所有用户
./query.sh users

# 执行自定义查询
./query.sh query "SELECT * FROM products"
```

### 方法4: 本地开发

1. **创建虚拟环境**
   ```bash
   python3 -m venv venv
   source venv/bin/activate
   ```

2. **安装依赖**
   ```bash
   pip install -r requirements.txt
   ```

3. **运行测试**
   ```bash
   python test_server.py
   ```

## 服务器模式

### 1. 标准模式 (main.py)
- 基本的SQL操作
- 单线程安全
- 适合单Agent使用

### 2. 增强模式 (main_enhanced.py)
- 支持多Agent并发
- 事务管理和乐观锁
- 一致性控制
- 适合多Agent协作

### 3. 自然语言模式 (main_natural_language.py)
- 支持中文自然语言建表
- 自然语言查询和更新
- 自动SQL生成
- 适合非技术用户

## 自然语言功能

### 自然语言建表
```bash
# 使用自然语言创建表
描述: "创建一个用户表，包含姓名、年龄、邮箱字段"
```

生成的SQL:
```sql
CREATE TABLE 用户 (姓名 TEXT, 年龄 INTEGER, 邮箱 TEXT)
```

### 自然语言查询
```bash
# 使用自然语言查询
描述: "查询所有年龄大于18的用户"
```

生成的SQL:
```sql
SELECT * FROM users WHERE age > 18
```

### 自然语言插入
```bash
# 使用自然语言插入数据
描述: "向用户表插入一个叫张三的用户，年龄25岁"
```

生成的SQL:
```sql
INSERT INTO users (name, age) VALUES ('张三', 25)
```

## 配置说明

### 环境变量

| 变量名 | 默认值 | 说明 |
|--------|--------|------|
| `DATABASE_PATH` | `data/sqlite.db` | 数据库文件路径 |
| `INIT_SCRIPT` | `init/init.sql` | 初始化SQL脚本路径 |
| `LOG_LEVEL` | `INFO` | 日志级别 |
| `AGENT_ID` | 自动生成 | Agent唯一标识符 |
| `USE_THREAD_SAFE` | `false` | 是否使用线程安全模式 |

### 初始化脚本

服务器启动时会自动执行 `init/init.sql` 脚本，用于：
- 创建数据库表结构
- 插入初始数据
- 设置数据库约束

示例初始化脚本：
```sql
-- 创建用户表
CREATE TABLE IF NOT EXISTS users (
    id INTEGER PRIMARY KEY,
    name TEXT NOT NULL,
    email TEXT UNIQUE,
    age INTEGER,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- 插入示例数据
INSERT OR IGNORE INTO users (id, name, email, age) VALUES 
(1, '张三', 'zhangsan@example.com', 25);
```

## 使用方法

### 简化查询脚本

使用 `query.sh` 脚本进行快速查询：

```bash
# 获取数据库信息
./query.sh info

# 列出所有表
./query.sh tables

# 查询所有用户
./query.sh users

# 执行自定义SQL查询
./query.sh query "SELECT * FROM products WHERE price > 100"

# 查看表结构
./query.sh describe users
```

### 直接Docker调用

```bash
# 基本格式
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "工具名", "arguments": {参数}}}' | docker run --rm -i -v $(pwd)/data:/app/data -v $(pwd)/config:/app/config -v $(pwd)/init:/app/init -e DATABASE_PATH=/app/data/sqlite.db -e INIT_SCRIPT=/app/init/init.sql db-sqlite-mcp-server
```

## MCP工具说明

### 标准模式工具

#### 1. sql_query
执行SQL查询语句，返回查询结果。

**参数:**
- `query` (string, 必需): SQL查询语句
- `params` (array, 可选): 查询参数列表

**示例:**
```json
{
  "query": "SELECT * FROM users WHERE age > ?",
  "params": ["18"]
}
```

#### 2. sql_update
执行SQL更新语句（INSERT、UPDATE、DELETE）。

**参数:**
- `query` (string, 必需): SQL更新语句
- `params` (array, 可选): 更新参数列表

**示例:**
```json
{
  "query": "INSERT INTO users (name, age) VALUES (?, ?)",
  "params": ["张三", "25"]
}
```

#### 3. list_tables
列出数据库中的所有表。

**参数:** 无

#### 4. describe_table
描述指定表的结构。

**参数:**
- `table_name` (string, 必需): 表名

#### 5. create_table
创建新表。

**参数:**
- `table_name` (string, 必需): 表名
- `columns` (string, 必需): 列定义SQL语句

#### 6. database_info
获取数据库基本信息。

**参数:** 无

### 增强模式工具

除了标准工具外，还包含：

#### 7. sql_transaction
执行事务操作。

**参数:**
- `operations` (array, 必需): 操作列表
- `isolation_level` (string, 可选): 隔离级别

#### 8. agent_status
获取当前Agent状态。

**参数:** 无

#### 9. transaction_history
获取事务历史记录。

**参数:**
- `limit` (integer, 可选): 返回记录数量限制

### 自然语言模式工具

#### 10. natural_language_query
使用自然语言进行查询。

**参数:**
- `description` (string, 必需): 自然语言查询描述

#### 11. natural_language_create_table
使用自然语言创建表。

**参数:**
- `description` (string, 必需): 自然语言表结构描述

#### 12. natural_language_insert
使用自然语言插入数据。

**参数:**
- `description` (string, 必需): 自然语言插入描述

#### 13. natural_language_update
使用自然语言更新数据。

**参数:**
- `description` (string, 必需): 自然语言更新描述

## 并发控制

### 多Agent并发
- 支持多个MCP Agent同时访问数据库
- 使用文件锁和事务管理确保数据一致性
- 支持乐观锁和悲观锁机制

### 事务隔离
- 支持不同的事务隔离级别
- 防止脏读、不可重复读和幻读
- 自动冲突检测和解决

## 开发指南

### 添加新工具
1. 在对应的服务器类中添加工具定义
2. 实现工具的处理方法
3. 在 `_call_tool` 方法中添加路由

### 扩展自然语言功能
1. 在 `natural_language_server.py` 中添加新的解析方法
2. 更新字段类型映射
3. 添加相应的测试用例

## 测试

### 运行测试
```bash
# 标准模式测试
python test_server.py

# 自然语言功能测试
python examples/natural_language_example.py

# 并发功能测试
python examples/multi_agent_concurrency_example.py
```

### 测试覆盖
- 基本SQL操作
- 自然语言解析
- 并发控制
- 错误处理
- 性能测试

## 部署

### Docker部署
```bash
# 构建镜像
docker-compose build

# 启动服务
docker-compose up -d

# 查看日志
docker-compose logs -f
```

### 生产环境
- 使用持久化存储
- 配置日志轮转
- 设置监控告警
- 定期备份数据

## 贡献

欢迎提交Issue和Pull Request！

### 开发环境设置
1. Fork项目
2. 创建功能分支
3. 提交更改
4. 创建Pull Request

## 许可证

MIT License

## 更新日志

### v2.0.0
- 添加自然语言建表功能
- 支持多Agent并发控制
- 增强事务管理
- 改进错误处理

### v1.0.0
- 基础SQLite MCP服务器
- Docker容器化支持
- 基本CRUD操作