Gel 数据库 MCP 服务器

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

注意：由于 LLM 可以编写更灵活的查询，因此不包含查询生成功能。已使用 Claude-3.7-sonnet-thinking 测试了 Cursor 代理，在提供 Gel 文档的相关网页链接后获得了良好的结果。

快速入门指南

# 1. Install dependencies
yarn install

# 2. Copy your dbschema folder into the project if you have one already 
# cp -r /path/to/your/dbschema ./
# or just copy and paste

# 3. Initialize a Gel project
npx gel project init
# Follow prompts to set up a new project 
# Can point to an existing gel instance by providing the name of your instance
#   -Import migrations if it asks

# 4. Generate EdgeQL JavaScript query builder files
npx @gel/generate edgeql-js
# Note: Re-run this command after any schema changes

# 5. Update connection settings
# Edit src/index_gel.ts lines 19-25 with your database, host, port, user, password
# Edit src/index_gel.ts line 37 with your branch name

# 6. Build the project
yarn build

# 7. (optional) Test the server runs without errors
node build/index.js

# 7.1 (if you have errors) Test server with a UI that provides more clear error logs using: 
npx @modelcontextprotocol/inspector node build/index.js

# 8. (Recommended) Include the gel_llm.txt documentation file
# Download the Gel documentation file and place it in your project root
# This allows both the search tool and direct file access for your LLM agent
# curl -o gel_llm.txt https://raw.githubusercontent.com/yourorg/gel-docs/main/gel_llm.txt
# Note: Replace the URL with the actual source of your gel_llm.txt file

在 Cursor 中连接 MCP 服务器

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

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

可用工具

Gel 数据库 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  # Optional: Number of context lines to show (default: 5)
match_all_terms: true  # Optional: Require all terms to match (default: 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 处理查询结果时。

了解更多

有关 Model Context Protocol 的更多信息，请访问 modelcontextprotocol.io/quickstart。