Gel Database MCP Server

Gel Database MCP 服务 [非官方/旧版]

此项目创建时，Gel 还没有官方 MCP 服务，而官方服务的设置要简单得多。不过，我仍保留了这个项目，因为它是我制作的 MCP 服务示例。 官方版本在这里：https://github.com/geldata/gel-mcp

这是一个基于 TypeScript 的 Model Context Protocol (MCP) 服务，旨在通过 EdgeQL 查询简化 Gel 数据库操作。此项目为 LLM Agent（Cursor Agent、Claude Code 等）提供工具，用于自动了解数据库架构，以及编写、验证和执行数据库查询。通过自然语言轻松与 Gel 数据库交互。氛围编程爱好者有福了！

注意：此项目不包含查询生成，因为 LLM 可以编写更灵活的查询。我使用 Cursor Agent 和 Claude-3.7-sonnet-thinking 对其进行了测试，在提供相关网页链接作为 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 > +Add a new server
2. 自行命名
3. 选择类型：Command
4. 输入：node your/full/path/to/build/index.js

注意： 此服务主要使用 Cursor Agent 进行测试，但应该也适用于支持 Model Context Protocol 的其他 Agent 和 LLM。如果你使用其他 Agent 进行了测试，欢迎分享你的发现！

可用工具

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

describe-schema

此工具可帮助你的 LLM Agent 了解并理解数据库结构，而无需手动检查代码。Agent 可以发现可用的实体类型、属性、关系和约束，从而生成更准确的查询。

适用场景： 当 Agent 需要在查询数据库实体之前了解其结构时。

validate-query

此工具可帮助你的 LLM Agent 验证原始 EdgeQL 查询语法，而不执行查询，从而在生成的查询针对数据库运行之前安全地进行验证。

适用场景： 在开发查询时检查语法，避免因执行而产生副作用。

execute-edgeql

此工具可帮助你的 LLM Agent 通过运行原始 EdgeQL 查询、检索数据并根据你的指示执行操作，直接与数据库交互。你的 LLM 可以生成 EdgeQL 查询并自主执行。

示例：

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

search-gel-docs

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

适用场景： 当 Agent 需要了解特定的 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 Agent 可以灵活地搜索特定术语，同时在需要更广泛的上下文时访问完整文档。

execute-typescript

类似于 execute-edgeql，但可用于测试和运行使用查询构建器语法编写的 TypeScript Gel 查询。

工具中包含说明，但最好还是询问 Agent 有哪些说明，以便将其加载到上下文中。这样可以确保它不会跳过这些说明。

注意：常见的 JavaScript 语法错误可能会导致服务崩溃，因此如果连接显示为已关闭，你需要在 Cursor MCP 设置中刷新崩溃的服务，或重启服务。

告诉大模型以下最佳实践：

• 使用 await gelClient.query() 并配合 console.log 显示结果
• 使用 THEN 而非逗号连接 ORDER BY（例如，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。