Skip to content

Commit 2996164

Browse files
XGenerationLabXGenerationLab
committed
update readme
1 parent 3ad9d9b commit 2996164

File tree

2 files changed

+172
-97
lines changed

2 files changed

+172
-97
lines changed

‎README.md

Lines changed: 71 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -1,34 +1,53 @@
1-
2-
[💻 XiYan-mcp-server](https://github.com/XGenerationLab/xiyan_mcp_server) |
3-
[💻 XiYan-SQL](https://github.com/XGenerationLab/XiYan-SQL) |
4-
[📖 Arxiv](https://arxiv.org/abs/2411.08599)|
5-
[📄 PapersWithCode](https://paperswithcode.com/paper/xiyan-sql-a-multi-generator-ensemble)
6-
7-
[![smithery badge](https://smithery.ai/badge/@XGenerationLab/xiyan_mcp_server)](https://smithery.ai/server/@XGenerationLab/xiyan_mcp_server)
8-
9-
[English](https://github.com/XGenerationLab/xiyan_mcp_server) | [中文](https://github.com/XGenerationLab/xiyan_mcp_server/blob/main/README_zh.md)
10-
11-
12-
# XiYan MCP Server
13-
14-
15-
A Model Context Protocol (MCP) server that enables natural language queries to databases, powered by [XiYanSQL](https://github.com/XGenerationLab/XiYan-SQL) as text-to-sql technique (SOTA of text-to-sql open benchmarks).
16-
17-
We support MySQL database now and more dialects are coming soon.
18-
19-
## 1. Features
20-
- Fetch data by natural language through [XiYanSQL](https://github.com/XGenerationLab/XiYan-SQL)
21-
- List available MySQL tables as resources
22-
- Read table contents
23-
24-
## 2. Tool Preview
1+
<h1 align="center">XiYan MCP Server</h1>
2+
<p align="center">
3+
<a href="https://github.com/XGenerationLab/XiYan-SQL"><img alt="MCP Playwright" src="https://raw.githubusercontent.com/XGenerationLab/XiYan-SQL/main/xiyanGBI.png" height="60"/></a>
4+
</p>
5+
<p align="center">
6+
<b>A Model Context Protocol (MCP) server that enables natural language queries to databases</b></br>
7+
<sub>powered by <a href="https://github.com/XGenerationLab/XiYan-SQL" >XiYan-SQL</a>, SOTA of text-to-sql on open benchmarks</sub>
8+
</p>
9+
10+
<p align="center">
11+
💻 <a href="https://github.com/XGenerationLab/xiyan_mcp_server" >XiYan-mcp-server</a> |
12+
🌐 <a href="https://github.com/XGenerationLab/https://github.com/XGenerationLab/XiYan-SQL" >XiYan-SQL</a> |
13+
📖 <a href="https://arxiv.org/abs/2411.08599"> Arxiv</a> |
14+
📄 <a href="https://paperswithcode.com/paper/xiyan-sql-a-multi-generator-ensemble" >PapersWithCode</a> <br />
15+
<a href="https://smithery.ai/server/@XGenerationLab/xiyan_mcp_server"><img alt="Smithery Installs" src="https://smithery.ai/badge/@XGenerationLab/xiyan_mcp_server" height="20"/></a><br />
16+
<a href="https://github.com/XGenerationLab/xiyan_mcp_server" >English</a> | <a href="https://github.com/XGenerationLab/xiyan_mcp_server/blob/main/README_zh.md"> 中文 </a>
17+
</p>
18+
19+
20+
## Table of Contents
21+
22+
- [Features](#features)
23+
- [Tool Preview](#tool-preview)
24+
- [Installation](#installation)
25+
- [Installing from pip](#installing-from-pip)
26+
- [Installing from Smithery.ai](#installing-from-smitheryai)
27+
- [Configuration](#configuration)
28+
- [LLM Configuration](#llm-configuration)
29+
- [General LLMs](#general-llms)
30+
- [Text-to-SQL SOTA model](#text-to-sql-sota-model)
31+
- [Local LLMs](#local-llms)
32+
- [Database Configuration](#database-configuration)
33+
- [Launch](#launch)
34+
- [Claude Desktop](#claude-desktop)
35+
- [Citation](#citation)
36+
37+
38+
## Features
39+
- 🌐 Fetch data by natural language through [XiYanSQL](https://github.com/XGenerationLab/XiYan-SQL)
40+
- 🖱️ List available MySQL tables as resources
41+
- 🔧 Read table contents
42+
43+
## Tool Preview
2544
- The tool ``get_data_via_natural_language`` provides a natural language interface for retrieving data from a database. This server will convert the input natural language into SQL using a built-in model and call the database to return the query results.
2645

2746
- The ``mysql://{table_name}`` resource allows obtaining a portion of sample data from the database for model reference when a specific table_name is specified.
2847
- The ``mysql://`` resource will list the names of the current databases
2948

30-
## 3. Installation
31-
### 3.1 Install from pip
49+
## Installation
50+
### Installing from pip
3251

3352
Python 3.11+ is required.
3453
you can install the server through pip, and it will install the latest verion
@@ -47,13 +66,12 @@ You will get a yml file. After that you can run the server by:
4766
env YML=path/to/yml python -m xiyan_mcp_server
4867
```
4968

50-
51-
### 3.2 Install from Smithery.ai
69+
### Installing from Smithery.ai
5270
See [@XGenerationLab/xiyan_mcp_server](https://smithery.ai/server/@XGenerationLab/xiyan_mcp_server)
5371

5472
Not fully tested.
5573

56-
## 4. Configuration
74+
## Configuration
5775

5876
You need a yml config file to configure the server.
5977
a default config file is provided in config_demo.yml which looks like this:
@@ -72,9 +90,9 @@ database:
7290
database: ""
7391
```
7492
75-
### 4.1 About LLM
93+
### LLM Configuration
7694
``Name`` is the name of the model to use, ``key`` is the API key of the model, ``url`` is the API url of the model. We support following models.
77-
#### Using general LLMs
95+
#### general LLMs
7896
if you want to use the general LLMs, e.g. gpt3.5, you can directly config like this:
7997
```yaml
8098
model:
@@ -92,7 +110,7 @@ model:
92110
url: "https://dashscope.aliyuncs.com/compatible-mode/v1"
93111
database:
94112
```
95-
#### Using Text-to-SQL SOTA model
113+
#### Text-to-SQL SOTA model
96114
Last, we recommend the XiYanSQL-qwencoder-32B (https://github.com/XGenerationLab/XiYanSQL-QwenCoder), which is the SOTA model in text-to-sql.
97115
We deployed the model on Alibaba Cloud DashScope, so you need to set the following environment variables:
98116
Contact us to get the ``key``. ( godot.lzl@alibaba-inc.com )
@@ -109,7 +127,7 @@ Alternatively, you can also deploy the model (XiYanSQL-qwencoder-32B) on your ow
109127
#### Local LLMs
110128
To support in the future.
111129
112-
### 4.2 About the database
130+
### Database Configuration
113131
``host``, ``port``, ``user``, ``password``, ``database`` are the connection information of the MySQL database.
114132
115133
You can use local or any remote databases. Now we support MySQL (more dialects soon).
@@ -124,8 +142,27 @@ database:
124142
database: ""
125143
```
126144
145+
## Launch
146+
### Claude desktop
147+
Add this in your claude desktop config file
148+
```json
149+
{
150+
"mcpServers": {
151+
"xiyan-mcp-server": {
152+
"command": "python",
153+
"args": [
154+
"-m",
155+
"xiyan_mcp_server"
156+
],
157+
"env": {
158+
"YML": "PATH/TO/YML"
159+
}
160+
}
161+
}
162+
}
163+
```
127164

128-
## 5. Citation
165+
## Citation
129166
If you find our work helpful, feel free to give us a cite.
130167
```bib
131168
@article{xiyansql,

‎README_zh.md

Lines changed: 101 additions & 63 deletions
Original file line numberDiff line numberDiff line change
@@ -1,61 +1,80 @@
1-
以下是您提供的文本的中文翻译：
2-
3-
---
4-
5-
[💻 XiYan-mcp-server](https://github.com/XGenerationLab/xiyan_mcp_server) |
6-
[💻 XiYan-SQL](https://github.com/XGenerationLab/XiYan-SQL) |
7-
[📖 Arxiv](https://arxiv.org/abs/2411.08599) |
8-
[📄 PapersWithCode](https://paperswithcode.com/paper/xiyan-sql-a-multi-generator-ensemble)
9-
10-
[![smithery badge](https://smithery.ai/badge/@XGenerationLab/xiyan_mcp_server)](https://smithery.ai/server/@XGenerationLab/xiyan_mcp_server)
11-
12-
[English](https://github.com/XGenerationLab/xiyan_mcp_server) | [中文](https://github.com/XGenerationLab/xiyan_mcp_server/blob/main/README_zh.md)
13-
14-
# XiYan MCP 服务器
15-
16-
一个模型上下文协议（MCP）服务器，支持通过自然语言查询数据库，使用 [XiYanSQL](https://github.com/XGenerationLab/XiYan-SQL) 作为文本到 SQL 的技术。
17-
18-
我们目前支持 MySQL 数据库，更多方言即将推出。
19-
20-
## 1. 特性
21-
- 通过 [XiYanSQL](https://github.com/XGenerationLab/XiYan-SQL) 以自然语言获取数据
22-
- 列出可用的 MySQL 表作为资源
23-
- 读取表内容
24-
25-
## 2. 工具预览
26-
- 工具 ``get_data_via_natural_language`` 提供了一个自然语言接口，从数据库中检索数据。该服务器将输入的自然语言转换为 SQL，并调用数据库返回查询结果。
27-
28-
- ``mysql://{table_name}`` 资源允许在指定特定 `table_name` 的情况下，从数据库中获取部分样本数据，以供模型参考。
29-
- ``mysql://`` 资源将列出当前数据库的名称。
30-
31-
## 3. 安装
32-
### 3.1 从 pip 安装
33-
34-
需要 Python 3.11 或更高版本。
35-
您可以通过 pip 安装该服务器，它将安装最新版本。
1+
<h1 align="center">XiYan MCP服务器</h1>
2+
<p align="center">
3+
<a href="https://github.com/XGenerationLab/XiYan-SQL"><img alt="MCP Playwright" src="https://raw.githubusercontent.com/XGenerationLab/XiYan-SQL/main/xiyanGBI.png" height="60"/></a>
4+
</p>
5+
<p align="center">
6+
<b>一个模型上下文协议（MCP）服务器，能够通过自然语言查询数据库</b></br>
7+
<sub>由 <a href="https://github.com/XGenerationLab/XiYan-SQL">XiYan-SQL</a> 提供支持，这是开放基准上的文本到SQL的最新技术</sub>
8+
</p>
9+
10+
<p align="center">
11+
💻 <a href="https://github.com/XGenerationLab/xiyan_mcp_server">XiYan-mcp-server</a> |
12+
🌐 <a href="https://github.com/XGenerationLab/XiYan-SQL">XiYan-SQL</a> |
13+
📖 <a href="https://arxiv.org/abs/2411.08599"> Arxiv</a> |
14+
📄 <a href="https://paperswithcode.com/paper/xiyan-sql-a-multi-generator-ensemble">PapersWithCode</a> <br />
15+
<a href="https://smithery.ai/server/@XGenerationLab/xiyan_mcp_server"><img alt="Smithery Installs" src="https://smithery.ai/badge/@XGenerationLab/xiyan_mcp_server" height="20"/></a><br />
16+
<a href="https://github.com/XGenerationLab/xiyan_mcp_server">英文</a> | <a href="https://github.com/XGenerationLab/xiyan_mcp_server/blob/main/README_zh.md"> 中文 </a>
17+
</p>
18+
19+
20+
## 目录
21+
22+
- [功能](#features)
23+
- [工具预览](#tool-preview)
24+
- [安装](#installation)
25+
- [通过pip安装](#installing-from-pip)
26+
- [通过Smithery.ai安装](#installing-from-smitheryai)
27+
- [配置](#configuration)
28+
- [LLM配置](#llm-configuration)
29+
- [通用LLMs](#general-llms)
30+
- [文本到SQL的最新技术模型](#text-to-sql-sota-model)
31+
- [本地LLMs](#local-llms)
32+
- [数据库配置](#database-configuration)
33+
- [启动](#launch)
34+
- [Claude桌面](#claude-desktop)
35+
- [引用](#citation)
36+
37+
38+
## 功能
39+
- 🌐 通过 [XiYanSQL](https://github.com/XGenerationLab/XiYan-SQL) 使用自然语言获取数据
40+
- 🖱️ 列出可用的MySQL表作为资源
41+
- 🔧 阅读表内容
42+
43+
## 工具预览
44+
- 工具 ``get_data_via_natural_language`` 提供了一个自然语言接口，用于从数据库中检索数据。该服务器将输入的自然语言转换为SQL，并调用数据库返回查询结果。
45+
46+
- 资源 ``mysql://{table_name}`` 允许在指定特定表名时从数据库获取一部分示例数据以供模型参考。
47+
- 资源 ``mysql://`` 将列出当前数据库的名称
48+
49+
## 安装
50+
### 通过pip安装
51+
52+
需要Python 3.11或更高版本。
53+
您可以通过pip安装服务器，它将安装最新版本。
3654

3755
```bash
3856
pip install xiyan-mcp-server
3957
```
4058

41-
安装后，您可以直接运行服务器：
59+
之后您可以通过以下命令直接运行服务器：
4260
```bash
43-
python -m xiyan-mcp-server
61+
python -m xiyan_mcp_server
4462
```
45-
但是在完成以下配置之前，它不会提供任何功能。您将获得一个 yml 文件。之后，您可以通过以下方式运行服务器：
63+
但在您完成以下配置之前，它不会提供任何功能。
64+
您将获得一个yml文件。之后您可以通过以下命令运行服务器：
4665
```yaml
47-
env YML=path/to/yml python -m xiyan-mcp-server
66+
env YML=path/to/yml python -m xiyan_mcp_server
4867
```
4968

50-
### 3.2 从 Smithery.ai 安装
51-
查看 [@XGenerationLab/xiyan_mcp_server](https://smithery.ai/server/@XGenerationLab/xiyan_mcp_server)
69+
### 通过Smithery.ai安装
70+
请参阅 [@XGenerationLab/xiyan_mcp_server](https://smithery.ai/server/@XGenerationLab/xiyan_mcp_server)
5271

53-
未进行全面测试。
72+
未完全测试。
5473

55-
## 4. 配置
74+
## 配置
5675

57-
您需要一个 yml 配置文件来配置服务器。
58-
默认配置文件在 `config_demo.yml` 中提供，其内容如下：
76+
您需要一个yml配置文件来配置服务器。
77+
在config_demo.yml中提供了默认配置文件，内容如下：
5978

6079
```yaml
6180
model:
@@ -71,10 +90,10 @@ database:
7190
database: ""
7291
```
7392
74-
### 4.1 关于 LLM
75-
``Name`` 是要使用的模型名称，``key`` 是模型的 API 密钥，``url`` 是模型的 API 地址。我们支持以下模型。
76-
#### 使用通用 LLM
77-
如果您想使用通用 LLM，例如 gpt3.5，您可以直接如下配置：
93+
### LLM配置
94+
``Name``是要使用的模型名称，``key``是模型的API密钥，``url``是模型的API网址。我们支持以下模型。
95+
#### 通用LLMs
96+
如果您想使用通用LLMs，例如gpt3.5，您可以直接配置如下：
7897
```yaml
7998
model:
8099
name: "gpt-3.5-turbo"
@@ -83,20 +102,19 @@ model:
83102
database:
84103
```
85104
86-
如果您想使用阿里巴巴的 Qwen，例如 Qwen-max：
105+
如果您想使用阿里巴巴的Qwen，例如Qwen-max，
87106
```yaml
88107
model:
89108
name: "qwen-max"
90109
key: "YOUR KEY"
91110
url: "https://dashscope.aliyuncs.com/compatible-mode/v1"
92111
database:
93112
```
94-
#### 使用文本到 SQL 的 SOTA 模型
95-
最后，我们推荐使用 XiYanSQL-qwencoder-32B (https://github.com/XGenerationLab/XiYanSQL-QwenCoder)，这是文本到 SQL 的 SOTA 模型，而且我们将其开源了。
96-
我们将模型部署在 DashScope 上，因此您需要设置以下环境变量：
97-
请联系我们以获取 ``key``。( godot.lzl@alibaba-inc.com )
98-
99113
114+
#### 文本到SQL的最新技术模型
115+
最后，我们推荐XiYanSQL-qwencoder-32B (https://github.com/XGenerationLab/XiYanSQL-QwenCoder)，这是文本到SQL的最新模型。
116+
我们在阿里巴巴云DashScope上部署了该模型，因此您需要设置以下环境变量：
117+
请与我们联系以获取 ``key``。 ( godot.lzl@alibaba-inc.com )
100118
```yaml
101119
model:
102120
name: "pre-xiyan_multi_dialect_v3"
@@ -105,15 +123,15 @@ model:
105123
database:
106124
```
107125
108-
当然你也可以自己部署XiYanSQL-qwencoder-32B在任何有足够GPU配置的机器上，并以openai sdk的方式对外提供服务，就可以接入本MCP server
126+
或者，您也可以在自己的服务器上部署模型（XiYanSQL-qwencoder-32B）。
109127
110-
#### 本地 LLM
111-
未来将支持。
128+
#### 本地LLMs
129+
未来将提供支持。
112130
113-
### 4.2 关于数据库
114-
``host``, ``port``, ``user``, ``password``, ``database`` 是 MySQL 数据库的连接信息。
131+
### 数据库配置
132+
``host``, ``port``, ``user``, ``password``, ``database`` 是MySQL数据库的连接信息。
115133
116-
您可以使用本地或任何远程数据库。现在我们支持 MySQL（即将支持更多方言）。
134+
您可以使用本地或任何远程数据库。现在我们支持MySQL（更多方言即将推出）。
117135
118136
```yaml
119137
database:
@@ -124,8 +142,28 @@ database:
124142
database: ""
125143
```
126144
127-
## 5. 引用
128-
如果您觉得我们的工作有帮助，请随意引用我们。
145+
## 启动
146+
### Claude desktop
147+
在您的claude桌面配置文件中添加以下内容：
148+
```json
149+
{
150+
"mcpServers": {
151+
"xiyan-mcp-server": {
152+
"command": "python",
153+
"args": [
154+
"-m",
155+
"xiyan_mcp_server"
156+
],
157+
"env": {
158+
"YML": "PATH/TO/YML"
159+
}
160+
}
161+
}
162+
}
163+
```
164+
165+
## 引用
166+
如果您觉得我们的工作有帮助，欢迎引用我们的文章。
129167
```bib
130168
@article{xiyansql,
131169
title={A Preview of XiYan-SQL: A Multi-Generator Ensemble Framework for Text-to-SQL},

0 commit comments

Comments
 (0)