Gel Database MCP 服务器

这是一个基于 TypeScript 的模型上下文协议 (MCP) 服务器，旨在通过 EdgeQL 查询简化 Gel 数据库操作。此项目为 LLM 代理（Cursor Agent、Claude Code 等）提供工具，以自动学习您的模式，并编写、验证和执行数据库查询。通过自然语言轻松与您的 Gel 数据库交互。Vibe 程序员欢呼吧！

注意：未包含查询生成，因为 LLM 可以编写更灵活的查询。已使用 Claude-3.7-sonnet-thinking 通过 Cursor agent 对其进行了测试，并在通过链接相关网页提供 Gel 文档后获得了良好的结果。

快速入门指南

# 1. 安装依赖
yarn install

# 2. 如果您已经有一个 dbschema 文件夹，请将其复制到项目中
# cp -r /path/to/your/dbschema ./
# 或直接复制粘贴

# 3. 初始化一个 Gel 项目
npx gel project init
# 按照提示设置一个新项目
# 可以通过提供实例名称来指向现有的 gel 实例
#   -如果它询问，导入迁移

# 4. 生成 EdgeQL JavaScript 查询构建器文件
npx @gel/generate edgeql-js
# 注意：在任何模式更改后重新运行此命令

# 5. 更新连接设置
# 使用您的数据库、主机、端口、用户、密码编辑 src/index_gel.ts 的第 19-25 行
# 使用您的分支名称编辑 src/index_gel.ts 的第 37 行

# 6. 构建项目
yarn build

# 7. (可选) 测试服务器是否运行没有错误
node build/index.js

# 7.1 (如果您有错误) 使用提供更清晰错误日志的 UI 测试服务器：
npx @modelcontextprotocol/inspector node build/index.js

# 8. (推荐) 包含 gel_llm.txt 文档文件
# 下载 Gel 文档文件并将其放置在您的项目根目录中
# 这允许搜索工具和 LLM 代理的直接文件访问
# curl -o gel_llm.txt https://raw.githubusercontent.com/yourorg/gel-docs/main/gel_llm.txt
# 注意：将 URL 替换为您的 gel_llm.txt 文件的实际来源

在 Cursor 中连接 MCP 服务器

1. 单击右上角的齿轮图标 > MCP > +添加新服务器
2. 随意命名
3. 选择类型：命令
4. 输入：node your/full/path/to/build/index.js

注意： 虽然此服务器主要使用 Cursor 的代理进行了测试，但它应该适用于支持模型上下文协议的其他代理和 LLM。如果您使用其他代理进行测试，请随时贡献您的发现！

可用工具

Gel Database MCP 服务器提供以下工具：

describe-schema

这有助于您的 LLM 代理学习和理解您的数据库结构，而无需手动检查代码。代理可以发现可用的实体类型、它们的属性、关系和约束，以生成更准确的查询。

何时使用： 当您的代理需要在查询数据库实体之前了解其结构时。

validate-query

这有助于您的 LLM 代理验证原始 EdgeQL 查询语法，而无需执行它，从而可以在针对数据库运行之前安全地验证生成的查询。

何时使用： 在查询开发期间检查语法，而不会冒执行副作用的风险。

execute-edgeql

这有助于您的 LLM 代理通过运行原始 EdgeQL 查询、检索数据并根据您的指令执行操作来直接与您的数据库交互。您的 LLM 可以生成 EdgeQL 查询并自主执行它们。

示例：

SELECT Product { name, price } FILTER .price > 100;

search-gel-docs

此工具允许您的 LLM 代理搜索 Gel 文档，以查找有关 EdgeQL 语法、功能或示例的相关信息。它返回包含上下文的全面结果，以帮助代理更好地理解 Gel 数据库概念。

何时使用： 当您的代理需要了解特定的 Gel/EdgeQL 功能、理解语法或查找用于实现数据库操作的示例时。

示例：

search_term: "for loop"
context_lines: 10  # 可选：要显示的上下文行数（默认值：5）
match_all_terms: true  # 可选：要求所有术语都匹配（默认值：false）

关于文档混合方法的说明： 为了获得最佳结果，我们建议同时：

1. 在您的项目根目录中包含 gel_llm.txt 文件（用于直接文件访问）
2. 使用 search-gel-docs 工具进行有针对性的查询

这种混合方法使您的 LLM 代理可以灵活地搜索特定术语，同时也可以在需要更广泛的上下文时访问完整的文档。

execute-typescript

与 execute-edgeql 类似，但可以使用它来测试和运行使用查询构建器语法制作的 Typescript Gel 查询。

说明包含在该工具中，但仍然最好询问代理它有哪些说明，以便它将它们加载到上下文中。这确保它不会跳过它们。

注意：常规 JavaScript 语法错误可能会导致服务器崩溃，因此如果连接显示为已关闭，您将必须刷新 Cursor MCP 设置中崩溃的服务器或重新启动服务器。

告诉 LLM 这些是最佳实践：

• 使用 await gelClient.query() 与 console.log 一起显示结果
• 使用 ORDER BY 与 THEN，而不是逗号（例如，ORDER BY .field1 THEN .field2）
• 保持代码简单并专注于单个操作

示例：

console.log(await gelClient.query(`
  SELECT Product { 
    name, 
    price 
  } 
  FILTER .price > 100 
  ORDER BY .price DESC 
  LIMIT 5;
`));

何时使用： 对于需要程序逻辑的复杂查询，或者当您需要使用 JavaScript 处理查询结果时。

了解更多

有关模型上下文协议的更多信息，请访问 modelcontextprotocol.io/quickstart。