MCP Query Assistant

查询助手MCP服务器

一种模型上下文协议（MCP）服务器，它使用语义搜索训练示例来帮助生成查询。该服务器通过查找类似的问题及其相应的查询来指导各种查询语言（Cypher、SPARQL、SQL等）的查询生成，从而提供很少的镜头学习功能。

特性

• 语义搜索：使用OpenAI嵌入在训练数据集中查找类似问题
• 小样本学习：返回相关示例以帮助生成准确的查询
• 培训数据管理：添加、列出和管理具有重复检测功能的问题查询对
• 矢量存储器：使用HNSW（分层导航小世界）算法进行高效的相似性搜索
• 元数据支持：按领域、复杂性和标签组织示例
• 多语言支持：适用于各种查询语言（Cypher、SPARQL、SQL等）

安装

1. 先决条件：Node.js 18+和npm

1. 构建服务器:

   cd /Users/alkhalili/Documents/Cline/MCP/mcp-query-assistant
   npm install
   npm run build

1. 配置OpenAI API密钥:

- 从获取API密钥 OpenAI平台 - 在以下位置更新MCP设置文件： /Users/alkhalili/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json - 替换 your_openai_api_key_here 使用您的实际API密钥

1. 配置数据目录（可选）:

- 默认情况下，数据存储在 data/ 与项目相关的文件夹 - 要使用自定义数据目录，您可以： - 设置 DATA_DIR 环境变量，或 - 使用 --data-dir 命令行参数

1. 服务器配置：服务器已在MCP设置中配置为：

   "query-assistant": {
     "command": "npx",
     "args": ["mcp-query-assistant"],
     "env": {
       "OPENAI_API_KEY": "your_openai_api_key_here",
       "DATA_DIR": "/optional/custom/data/path"
     },
     "disabled": false,
     "autoApprove": []
   }

带有命令行参数的替代方案:

   "query-assistant": {
     "command": "npx",
     "args": ["mcp-query-assistant", "--openai-key", "your_openai_api_key_here", "--data-dir", "/custom/data/path"],
     "disabled": false,
     "autoApprove": []
   }

可用工具

1. find_similar_queries

基于自然语言问题查找类似的查询示例。

参数：

• question （必填）：自然语言问题，寻找类似的例子
• limit （可选）：要返回的最大相似示例数（默认值：3，最大值：10）
• threshold （可选）：最小相似性阈值0-1（默认值：0.7）

示例用法：

Use the find_similar_queries tool to find examples for: "Give me the list of CDEs in the lineage"

2. add_training_example

将新的问题查询对添加到训练数据集中。

参数：

• question （必填）：自然语言问题
• query （必填）：对应的查询（Cypher、SPARQL、SQL等）
• metadata （可选）：附加元数据（域、复杂性、标签）

示例用法：

Add a training example:
Question: "Find users who bought expensive products"
Query: "MATCH (u:User)-[:PURCHASED]->(p:Product) WHERE p.price > 1000 RETURN u"
Metadata: {"domain": "user_analytics", "complexity": "medium"}

3. list_training_examples

列出数据集中的所有训练示例。

参数：

• limit （可选）：返回的最大示例数（默认值：10，最大值：100）
• domain （可选）：按域筛选

4. find_duplicates

根据问题和查询查找重复的训练示例。

参数： 无

示例用法：

Use find_duplicates to identify duplicate training examples in your dataset.

5. remove_duplicates

删除重复的训练示例，只保留每个唯一问题查询对的第一个出现。

参数：

• confirm （可选）：设置为true以确认删除重复项（默认值：false）

示例用法：

Use remove_duplicates with confirm=true to clean up duplicate examples.

默认训练示例

服务器附带了一个涵盖数据沿袭模式的默认示例：

1. 数据沿袭：“给我谱系中的CDE列表”

- 查询： MATCH (cde:CDE) RETURN cde.name, cde.description, cde.layer, cde.fqn ORDER BY cde.name - 域：数据谱系 - 复杂性：简单

使用工作流程

1. 询问类似问题：当您需要编写查询时，请使用 find_similar_queries 用你的自然语言提问
2. 获取几个射击示例：服务器返回具有相似性得分的类似问题及其查询
3. 生成您的查询：以示例为指导，撰写您的具体查询
4. 添加新示例：使用 add_training_example 使用新模式扩展训练数据集
5. 管理重复项：使用 find_duplicates 和 remove_duplicates 保持数据集干净

数据存储

• 培训数据：存储在 {DATA_DIR}/training_data.json （默认值： data/training_data.json)
• 向量索引：存储在 {DATA_DIR}/vector_index.bin （默认值： data/vector_index.bin)
• 嵌入：使用OpenAI生成 text-embedding-3-small 模型（1536个维度）
• 数据目录：可通过配置 DATA_DIR 环境变量或 --data-dir 命令行参数

交互示例

User: "Show me all data elements with their descriptions"

Agent: Let me find similar examples for you.
[Uses find_similar_queries tool]

Server Response:
Found 1 similar examples for: "Show me all data elements with their descriptions"

Example 1 (similarity: 0.823):
Question: Give me the list of CDEs in the lineage
Query: MATCH (cde:CDE) RETURN cde.name, cde.description, cde.layer, cde.fqn ORDER BY cde.name
Domain: Data Lineage
Complexity: simple

Agent: Based on this example, here's a query for showing data elements with descriptions:
MATCH (cde:CDE) 
RETURN cde.name, cde.description 
ORDER BY cde.name

故障排除

1. “未配置OpenAI API密钥”：确保您已在MCP设置中设置了API密钥
2. “未找到类似示例”：尝试降低相似性阈值或添加更多训练数据
3. 服务器未连接：检查生成路径是否正确以及服务器是否已成功编译

贡献

要添加更多培训示例或改进服务器：

1. 使用 add_training_example 添加新问题查询对的工具
2. 使用适当的元数据（域、复杂性、标签）组织示例
3. 使用各种问题短语测试相似性搜索
4. 考虑为您的用例添加特定领域的示例

技术细节

• 矢量数据库：HNSW（分层导航小世界）用于高效的相似性搜索
• 嵌入模型：OpenAI文本嵌入3-small（1536个维度）
• 相似性度量：余弦相似性
• 存储格式：JSON用于训练数据，二进制用于向量索引
• 最大容量：10000个训练示例（可配置）