# FocusSQL
## 基本信息
- Slug: `focussearch-focus_mcp_sql`
- Source: modelscope
- Publisher: @FocusSearch/focus_mcp_sql
- Categories: databases / search
- Hosted: No
- License: Apache License 2.0
- Source URL: https://www.modelscope.cn/mcp/servers/@FocusSearch/focus_mcp_sql
## 简介
基于FocusSearch关键词解析的NL2SQL插件，提供更高的准确性、更快的速度和更可靠的性能！
## 安装提示

```bash
git clone https://github.com/FocusSearch/focus_mcp_sql.git cd focus_mcp_sql
```

## MCP Server 详情

# FOCUS DATA MCP Server [[中文](./README_CN.md)]

Model Context Protocol (MCP) 服务器使人工智能助手能够将自然语言转换为 SQL 语句。

# 已经有这么多的 Text-to-SQL 框架了，为什么还需要另一个？

简单来说，focus_mcp_sql 采用了一个两步的 SQL 生成解决方案，这使得可以控制大模型的幻觉问题，并真正建立起非技术用户对生成的 SQL 结果的信任。

下面是 focus_mcp_sql 与其他框架之间的比较表：

#### 对比分析表
这里是一个并排比较，展示了 focus_mcp_sql 与其它基于大模型的框架之间的差异：

| 特性               | 传统的大模型框架 | focus_mcp_sql              |
|--------------------|------------------|----------------------------|
| 生成过程           | 黑盒，直接生成 SQL | 透明，两步（关键词 + SQL） |
| 幻觉风险           | 高，依赖于模型质量 | 低，可控制（关键词验证）   |
| 速度               | 慢，依赖大型模型推理 | 快，确定性的关键词到 SQL  |
| 成本               | 高，需要高级模型 | 低，减少对大型模型的依赖   |
| 非技术人员友好度   | 低，难以验证结果 | 高，易于检查关键词         |

## 功能

- 初始化模型
- 将自然语言转换为 SQL 语句

## 前提条件

- jdk 23 或更高版本。下载 [jdk](https://www.oracle.com/java/technologies/downloads/)
- gradle 8.12 或更高版本。下载 [gradle](https://gradle.org/install/)
- 注册 [Datafocus](https://www.datafocus.ai/) 获取承载令牌：
    1. 在 [Datafocus](https://www.datafocus.ai/) 注册一个账户
    2. 创建一个应用
    3. 进入该应用
    4. 管理员 -> 接口认证 -> 承载令牌 -> 新建承载令牌
       ![bearer token](bearer_token.png)

## 安装

1. 克隆此仓库：

```bash
git clone https://github.com/FocusSearch/focus_mcp_sql.git
cd focus_mcp_sql
```


2. 构建服务器：

```bash
gradle clean
gradle bootJar

The jar path: build/libs/focus_mcp_sql.jar
```


## MCP 配置

将服务器添加到您的 MCP 设置文件中：

```json
{
  "mcpServers": {
    "focus_mcp_data": {
      "command": "java",
      "args": [
        "-jar",
        "path/to/focus_mcp_sql/focus_mcp_sql.jar"
      ],
      "autoApprove": [
        "gptText2sqlStart",
        "gptText2sqlChat"
      ]
    }
  }
}
```


## 可用工具

### 1. gptText2sqlStart

初始化模型。

**参数：**

- `model` (必需): 表模型
- `bearer` (必需): 承载令牌
- `language` (可选): 语言 ['english','chinese']

**示例：**

```json
{
  "model": {
    "tables": [
      {
        "columns": [
          {
            "columnDisplayName": "name",
            "dataType": "string",
            "aggregation": "",
            "columnName": "name"
          },
          {
            "columnDisplayName": "address",
            "dataType": "string",
            "aggregation": "",
            "columnName": "address"
          },
          {
            "columnDisplayName": "age",
            "dataType": "int",
            "aggregation": "SUM",
            "columnName": "age"
          },
          {
            "columnDisplayName": "date",
            "dataType": "timestamp",
            "aggregation": "",
            "columnName": "date"
          }
        ],
        "tableDisplayName": "test",
        "tableName": "test"
      }
    ],
    "relations": [

    ],
    "type": "mysql",
    "version": "8.0"
  },
  "bearer": "ZTllYzAzZjM2YzA3NDA0ZGE3ZjguNDJhNDjNGU4NzkyYjY1OTY0YzUxYWU5NmU="
}
```


model 参数说明：

|名称|位置|类型|必选|说明|
|---|---|---|---|---|
| model|body|object| 是 |none|
|» type|body|string| 是 |数据库类型|
|» version|body|string| 是 |数据库版本|
|» tables|body|[object]| 是 |表结构列表|
|»» tableDisplayName|body|string| 否 |表显示名|
|»» tableName|body|string| 否 |表原始名|
|»» columns|body|[object]| 否 |表列列表|
|»»» columnDisplayName|body|string| 是 |列显示名|
|»»» columnName|body|string| 是 |列原始名|
|»»» dataType|body|string| 是 |列数据类型|
|»»» aggregation|body|string| 是 |列聚合方式|
|» relations|body|[object]| 是 |表关联关系列表|
|»» conditions|body|[object]| 否 |关联条件|
|»»» dstColName|body|string| 否 |dimension 表关联列原始名|
|»»» srcColName|body|string| 否 |fact 表关联列原始名|
|»» dimensionTable|body|string| 否 |dimension 表原始名|
|»» factTable|body|string| 否 |fact 表原始名|
|»» joinType|body|string| 否 |关联类型|

### 2. gptText2sqlChat

将自然语言转换为 SQL。

**参数：**

- `chatId`（必填）：聊天 ID
- `input`（必填）：自然语言
- `bearer`（必填）：bearer token

**示例：**

```json
{
  "chatId": "03975af5de4b4562938a985403f206d4",
  "input": "what is the max age",
  "bearer": "ZTllYzAzZjM2YzA3NDA0ZGE3ZjguNDJhNDjNGU4NzkyYjY1OTY0YzUxYWU5NmU="
}
```


## 响应格式

所有工具返回的响应都采用以下格式：

```json
{
  "errCode": 0,
  "exception": "",
  "msgParams": null,
  "promptMsg": null,
  "success": true,
  "data": {
  }
}
```


## Visual Studio Code Cline 示例

1. 在 vsCode 中安装 cline 插件
2. 配置 mcp 服务器
   ![配置 mcp 服务器](./mcp_server_config.png)
3. 使用
    1. 初始化模型
       ![初始化模型1](./focus_mcp_sql_init_1.png)
       ![初始化模型2](./focus_mcp_sql_init_2.png)
    2. 转换：最大年龄是多少
       ![聊天](./focus_mcp_sql_chat.png)

## 联系方式：
[https://discord.gg/mFa3yeq9](https://discord.gg/AVufPnpaad)
![Datafocus](./wechat-qrcode.png)