# lzwcai-mcp-sqlexecutor

一个基于 MCP (Model Context Protocol) 的 SQL 查询执行服务器，支持从 JSON 配置文件动态生成查询工具。

## 功能特性

- 🚀 动态工具生成：从 `businessQueries.json` 自动生成 MCP 工具
- 🔧 灵活配置：支持自定义业务查询和参数验证
- 📝 完整日志：详细的操作日志记录（仅输出到文件，不干扰MCP通信）
- 🌐 中文支持：工具名称自动转换为拼音

## 安装

### 使用 pip 安装

```bash
pip install lzwcai-mcp-sqlexecutor
```

### 从源码安装

```bash
git clone <repository-url>
cd lzwcai_mcp_sqlexecutor
pip install -e .
```

### 使用 uv 安装（推荐）

```bash
uv pip install lzwcai-mcp-sqlexecutor
```

## 使用方法

### 命令行启动

安装后，可以直接通过命令启动：

```bash
lzwcai-mcp-sqlexecutor
```

### 作为 Python 模块运行

```bash
python -m lzwcai_mcp_sqlexecutor.main
```

### 配置到 MCP 客户端

在你的 MCP 客户端配置文件中添加：

```json
{
  "mcpServers": {
    "lzwcai-sqlexecutor": {
      "command": "lzwcai-mcp-sqlexecutor"
    }
  }
}
```

## 配置说明

### businessQueries.json

在 `businessQueries.json` 中定义你的业务查询：

```json
[
  {
    "id": "query-001",
    "businessName": "用户订单查询",
    "businessDescription": "根据用户ID查询订单信息",
    "sqlTemplate": "SELECT * FROM orders WHERE user_id = {{userId}}",
    "parameters": {
      "type": "object",
      "required": ["userId"],
      "properties": {
        "userId": {
          "type": "integer",
          "description": "用户的唯一标识符",
          "examples": [10086]
        }
      }
    }
  }
]
```

## 开发

### 依赖项

- Python >= 3.13
- httpx >= 0.28.1
- mcp[cli] >= 1.10.1
- pypinyin >= 0.53.0

### 本地开发

```bash
# 克隆仓库
git clone <repository-url>
cd lzwcai_mcp_sqlexecutor

# 安装开发依赖
pip install -e .

# 运行服务器
python -m lzwcai_mcp_sqlexecutor.main
```

## 构建与发布

### 使用 build 构建

```bash
pip install build
python -m build
```

### 发布到 PyPI

```bash
pip install twine
twine upload dist/*
```

## 常见问题

### MCP Inspector 显示 JSON 解析错误

如果在使用 MCP Inspector 测试时遇到 `SyntaxError: Unexpected non-whitespace character after JSON` 错误，这是因为：

1. **原因**：MCP 协议使用 stdio（标准输入输出）进行 JSON-RPC 通信，任何输出到 stdout 的内容（如 print 语句或控制台日志）都会破坏 JSON 格式。

2. **解决方案**：本服务器已将所有日志输出配置为仅写入文件（位于 `logs/` 目录），不输出到控制台。日志文件包括：
   - `lzwcai_mcp_sqlexecutor.log` - 主日志文件
   - `lzwcai_mcp_sqlexecutor_error.log` - 错误日志
   - `lzwcai_mcp_sqlexecutor_daily.log` - 按日期滚动的日志
   - `mcp_services.log` - MCP 服务专用日志

3. **查看日志**：如果需要调试，请查看 `logs/` 目录下的日志文件。

## 许可证

MIT License

## 作者

lzwcai

