You can use this MCP server to connect Codex to a YueShu Graph Database 5.3, discover graphs and schemas, validate and execute read-only GQL, and optionally run confirmed mutations, while receiving normalized tables, graph elements, chart specs, and analysis.
nebula_test_connection: test connectivity and return database version plus redacted config.
nebula_list_graphs: paginate persistent graphs before choosing a graph context.
nebula_get_graph_schema: return structured Graph Type schema and optional byte-bounded DDL.
nebula_validate_gql: statically validate GQL for placeholders, dialect residuals, and policy; optionally run EXPLAIN without executing the original query.
nebula_execute_query: execute approved read-only GQL and return a table, Cytoscape graph, deterministic analysis, Vega-Lite chart specs, explanation context, and truncation details.
nebula_execute_mutation: run destructive statements only when NEBULA_ALLOW_MUTATIONS=true and the call includes confirm_mutation=true; returns affected node/edge counts, no charts.
Control generated outputs with include_graph, include_analysis, and include_charts, using render_mode=spec.
Enforce read-only by default, strict tool input schemas, and safe identifier rules for graphs, schemas, and graph types.
Provides tools for connecting to and interacting with a NebulaGraph (悦数图数据库 5.3) instance, including graph and schema discovery, GQL validation, read-only query execution, and structured result output.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@nebula-mcp what graphs are available and show me the schema for the user graph?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
nebula-mcp 是运行在本地 Codex 中的 MCP Server，通过 stdio 接入 Codex，并通过网络连接远端悦数图数据库 5.3。MCP Server 不需要部署到数据库服务器。
它负责连接、Schema 发现、GQL 校验与执行、结果解析和标准化规格输出。自然语言、Neo4j Cypher 或 nGQL 到悦数 GQL 的转换由 Codex 客户端使用 gql-query-generator 完成；Server 内不嵌入 LLM，也不在悦数数据库侧做语言转换。
当目标版本的 GitHub Release 可用时，从该版本的资产下载 install.py。macOS/Linux 的 bash/zsh 运行：
python3 install.pyWindows PowerShell 使用 Release 页面中 install.py 的实际 URL：
Invoke-WebRequest -Uri "<Release install.py URL>" -OutFile install.py
py -3 install.py安装器需要 Python 3.10 或更高版本；它会下载并校验该 Release 的 wheel，在用户本地创建隔离环境并注册名为 nebula 的 MCP Server。安装器不收集数据库地址、用户名或密码。
若尚未安装 Codex CLI，安装仍会完成，但 nebula 尚未注册。安装器会输出稍后执行的精确命令，形式如下；安装 Codex CLI 后复制其输出的实际路径执行：
以下手工注册命令由安装器按当前 shell 正确转义：macOS/Linux 输出适用于 bash/zsh，Windows 输出适用于 PowerShell。
codex mcp add nebula -- <安装器使用的系统 Python> <安装器输出的 launcher.py>POSIX 上受管数据根和日志目录会被收敛到当前 uid 的 0700，marker、state、launcher 和日志文件为 0600。Windows 数据根严格位于当前用户 %LOCALAPPDATA%\nebula-mcp 并保留其继承 ACL，且 root leaf 若为 junction/reparse point 会在安装或卸载前拒绝；Windows 不使用 POSIX chmod，也不把 POSIX mode 检查冒充为 ACL 验证。
首次运行时若提示 CONFIGURATION_REQUIRED，表示 Server 已启动但尚未配置数据库；按下一节填写变量、保存并重启 MCP。
打开 Settings > MCP servers > nebula。
在环境变量区域填写 NEBULA_ADDRESSES（一个或多个 HOST:PORT）、NEBULA_USERNAME 和 NEBULA_PASSWORD。
推荐同时填写 NEBULA_CONNECT_TIMEOUT_MS=30000，并保留 NEBULA_ALLOW_MUTATIONS=false。
保存设置并重启 MCP，然后在新对话中调用 nebula_test_connection 验证连接。
Codex 桌面当前不会为该字段提供密码遮罩：NEBULA_PASSWORD 在编辑页可见，并以明文保存在用户本地 ~/.codex/config.toml。nebula-mcp 不使用 Keychain，也不实现自定义加密。不要共享该文件或把它加入项目版本控制；生产环境优先使用最小权限账号。Codex 的 MCP 列表即使对值做脱敏显示，也只是显示脱敏，不是加密。
Server 不自动读取工作区 .env。常用可选变量见 .env.example：连接/请求/连接池等待超时、池大小、TLS、时区以及返回行、节点、边和字节上限。NEBULA_MAX_ROWS 只限制进入 MCP 上下文的结果，不能阻止数据库先计算大结果。
升级时从新版本 Release 下载其 install.py，再次运行 python3 install.py。安装器不会 remove/add 已由它管理的 nebula 注册，因此会保留现有环境变量。
如果已存在同名 nebula MCP 但不是本安装器注册的命令，安装会停止。先用 codex mcp get nebula 核对；仅在确认替换后运行 python3 install.py --replace-registration。替换会删除该旧注册的环境变量，安装器不会合并或恢复它们，须先自行记录并在 Desktop 中重新填写。
卸载运行 python3 install.py --uninstall。它只移除 nebula 注册和本安装器管理的目录；若 Codex CLI 缺失或无法安全移除注册，安装文件会保留以避免留下无效注册。
Windows PowerShell 的升级与卸载分别运行 py -3 install.py 和 py -3 install.py --uninstall；冲突替换参数同样为 py -3 install.py --replace-registration。
Related MCP server: mcp4gql
对于自然语言、Cypher 或 nGQL 请求，Codex 应按以下顺序工作：
调用 nebula_list_graphs 选择目标图。
调用 nebula_get_graph_schema 获取实际 Graph Type；未知属性必须保留为占位符，不得猜测。
在 Codex 客户端使用 $gql-query-generator 生成悦数 5.3 GQL。
调用 nebula_validate_gql 做静态校验，排除占位符、Cypher/nGQL 残留、多语句和安全策略问题。
对需要数据库计划证据的候选语句设置 run_explain=true。EXPLAIN 只检查候选计划，不执行原查询。
向用户展示候选 GQL 和证据边界，确认后调用 nebula_execute_query。
Codex 同时消费所有已启用的结果组成：图元素非空时呈现图，charts 非空时呈现每个图表，并始终根据 explanation_context 生成人工解释。表格不能替代图表或解释。
证据必须分开标记：
静态校验：只证明词法、方言残留和策略检查结果，不证明数据库可执行或业务语义正确。
EXPLAIN 验证：证明数据库接受计划分析，不代表已经读取业务数据。
执行验证：只说明该语句在指定图与当次数据上实际执行；若结果被截断，分析范围仅为 returned_rows。
工具 | 用途 |
| 返回数据库版本和脱敏连接配置，不返回密码。 |
| 使用 |
| 使用 |
| 静态校验候选 GQL，并可选执行 EXPLAIN；不执行原语句。 |
| 只执行通过策略的单条只读 GQL，按参数返回 table、graph、analysis 和 charts。 |
| 独立的破坏性工具；必须同时启用 Server 开关并逐次确认。 |
工具输入使用严格 Schema，未知字段会被拒绝。图、Schema 和 Graph Type 标识符只接受字母、数字和下划线，且不能以数字开头。
默认配置是 NEBULA_ALLOW_MUTATIONS=false。CREATE、DROP、ALTER、INSERT、UPDATE、DELETE 等语句不能通过 nebula_execute_query。
即使管理员显式设置 NEBULA_ALLOW_MUTATIONS=true，写入也只能调用 nebula_execute_mutation，并为该次调用传入 confirm_mutation=true。MCP annotations 仅描述风险，不会自动放行。远端验收测试只执行只读语句，不使用 mutation/DDL 验证。
统一结果包含 status、query、table、graph、analysis、charts、explanation_context 和 truncation：
图使用 cytoscape-elements-v1，稳定 ID 包含图上下文；边的 source/target 一定引用返回的节点元素。
图表使用 vega-lite-v5，最多返回 3 个确定性建议规格；没有合适字段时返回空列表。
非 JSON 原生值保留显式类型，包括日期时间、duration、embedding vector、bytes、set 和非有限浮点。
explanation_context 只提供可复核事实、空结果状态、校验证据和 caveats；人工解释由 Codex 生成。
达到行数、字节、节点或边上限时，truncation.reasons 明确记录原因，统计不会被描述为完整总体。
调用方可用 include_graph、include_analysis 和 include_charts 控制是否生成相应内容；当前 render_mode 只支持 spec，不把 PNG 当作唯一结果。
三个 include 开关均默认开启且相互独立。图中没有节点/边时可以不呈现图；但非空 charts 应呈现为图表，成功查询应同时附上基于 explanation_context 的人工解释。
开发者在仓库检出后可使用 editable 安装；这不是普通用户的 Release 安装方式：
python3 -m venv .venv
.venv/bin/python -m pip install --upgrade pip
.venv/bin/python -m pip install -e '.[dev]'发布构建可在干净环境验证 wheel：
.venv/bin/python -m pip install build
.venv/bin/python -m build
python3 -m venv /tmp/nebula-mcp-wheel-venv
/tmp/nebula-mcp-wheel-venv/bin/python -m pip install dist/nebula_mcp-*.whl
/tmp/nebula-mcp-wheel-venv/bin/nebula-mcp --version.venv/bin/python -m pytest -q
.venv/bin/ruff check .
.venv/bin/mypy src
.venv/bin/python -m nebula_mcp --help真实远端测试需要在运行时提供 NEBULA_ADDRESSES、NEBULA_USERNAME、NEBULA_PASSWORD，且应使用只读账号。不要把凭据加入测试文件。
nebula5-python 5.3.0 的公开单次 execute(timeout=...) 参数在目标实现中没有形成可靠的逐调用 deadline。本项目只承诺连接配置中的 NEBULA_REQUEST_TIMEOUT_MS，不宣称可安全取消任意正在执行的查询。
静态校验采用保守词法策略，不是完整 GQL 解析器；未知 procedure 默认拒绝。
共享远端实例的数据可能变化，单次结果和耗时不能当作业务 SLA。
Execute one mutation only when NEBULA_ALLOW_MUTATIONS=true and confirm_mutation=true. This tool is destructive and returns no charts.
| Name | Required | Description | Default |
|---|---|---|---|
| graph | No | ||
| statement | Yes | ||
| confirm_mutation | No |
| Name | Required | Description |
|---|---|---|
| status | Yes | |
| warnings | No | |
| affected_edges | Yes | |
| affected_nodes | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare destructiveHint=true, so the description's 'This tool is destructive' reinforces rather than adds. It does add useful context by stating 'returns no charts' and 'one mutation only', but it does not disclose other behavioral traits such as whether changes are reversible or what happens on failed validation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two compact sentences with no filler. The critical usage condition is front-loaded, and the destructive/no-charts warning is placed prominently. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is adequate for a simple mutation tool with an output schema: it states the mutation role, safety gate, destructive nature, and output expectation. However, it lacks guidance on how 'statement' and 'graph' relate, and it could benefit from explicitly routing non-mutating users to nebula_execute_query.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate by explaining the parameters. It mentions confirm_mutation as a safety gate, which is useful, but it gives no semantics for the required 'statement' parameter or the optional 'graph' parameter, leaving the agent to infer their roles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies a specific verb ('Execute'), a specific resource ('mutation'), and adds a scope constraint ('one mutation only'). It is distinguishable from sibling tools by the term 'mutation', though it does not explicitly name the sibling it contrasts with, such as nebula_execute_query.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit gating conditions: 'only when NEBULA_ALLOW_MUTATIONS=true and confirm_mutation=true'. This is strong usage guidance for a destructive tool. However, it does not explicitly state when to prefer a sibling like nebula_execute_query for non-mutating work.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute one approved read-only GQL statement and optionally return table, cytoscape-elements-v1 graph, deterministic analysis, and vega-lite-v5 charts.
| Name | Required | Description | Default |
|---|---|---|---|
| graph | No | ||
| max_rows | No | ||
| statement | Yes | ||
| render_mode | No | spec | |
| include_graph | No | ||
| include_charts | No | ||
| include_analysis | No |
| Name | Required | Description |
|---|---|---|
| graph | No | |
| query | Yes | |
| table | Yes | |
| charts | No | |
| status | Yes | |
| analysis | No | |
| truncation | Yes | |
| explanation_context | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description adds value by disclosing the optional return artifacts (graph, analysis, charts) and reinforcing the read-only nature ('approved read-only'). This aligns with annotations and provides additional context about output variety.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, well-structured sentence that front-loads the core action and then lists the optional outputs. There is no fluff or redundancy; every word contributes to agent comprehension.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema, the description is far too sparse for a 7-parameter tool. It omits critical context like what 'approved' means, the meaning of graph/max_rows/render_mode, and how the include_* flags map to return types. An agent would need to inspect the schema and still lack semantic guidance, making the tool risky to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 7 parameters and 0% schema description coverage, the burden falls entirely on the description, but it fails to explain any parameter. It vaguely hints at include_graph/include_charts/include_analysis through the mention of return types, but gives no guidance on the 'statement', 'graph', 'max_rows', or 'render_mode' fields. This is inadequate for a tool with a required statement parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Execute') and a clear resource ('one approved read-only GQL statement') and enumerates the possible return types (table, graph, analysis, charts). This distinguishes it from siblings like nebula_execute_mutation (which is write-oriented) and nebula_validate_gql (which validates rather than executes).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this tool is for executing approved read-only queries, which clearly separates it from mutation and validation tools. However, it does not explicitly state when to prefer this over nebula_validate_gql or reference sibling alternatives by name, so there's minor room for ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a Graph Type schema; optionally include a UTF-8 byte-bounded DDL string.
| Name | Required | Description | Default |
|---|---|---|---|
| schema | Yes | ||
| graph_type | Yes | ||
| include_ddl | No | ||
| max_ddl_bytes | No |
| Name | Required | Description |
|---|---|---|
| ddl | No | |
| schema | Yes | |
| status | Yes | |
| entities | Yes | |
| graph_type | Yes | |
| ddl_truncated | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior, lowering the burden on the description. The description adds the useful detail that DDL output can be optionally included and is UTF-8 byte-bounded, but does not explain what happens when max_ddl_bytes is exceeded or how the DDL string appears in the output.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, compact sentence with no filler or repeated schema information. It front-loads the core operation and puts the optional behavior second, though it is perhaps too sparse to fully carry the 0% schema coverage.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with two required parameters and no schema-level descriptions, the description is not complete enough to guide correct invocation. The presence of an output schema helps with return values, but the opaque 'schema' and 'graph_type' parameters and lack of sibling differentiation leave meaningful gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for the missing parameter documentation. It provides a hint about include_ddl and max_ddl_bytes through the 'UTF-8 byte-bounded DDL string' phrase, but the required parameters 'schema' and 'graph_type' are left completely unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource: 'Read a Graph Type schema'. This clearly distinguishes it from mutation/execution siblings and signals it is a retrieval operation. However, 'Graph Type' is domain-specific and not expanded, so a less knowledgeable agent could still be unsure what object is being read.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given about when to use this tool over siblings like nebula_list_graphs or nebula_execute_query. The description implies a read operation but does not state prerequisites, when it is appropriate, or when an alternative should be chosen.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List persistent graphs before choosing schema and graph context.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| offset | No | ||
| schema | No |
| Name | Required | Description |
|---|---|---|
| limit | Yes | |
| graphs | Yes | |
| offset | Yes | |
| status | Yes | |
| returned_count | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, covering the safety profile. The description adds the qualifier 'persistent graphs', which implies a distinction from temporary graphs. It does not mention pagination behavior (limit/offset) or the optional schema filter, but since annotations carry the main behavioral load, a baseline 3 is reasonable. It doesn't contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It states the core action and its usage context efficiently. Every word earns its place, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the tool is simple and has an output schema (reducing the need to describe return values), the description is incomplete due to the lack of parameter explanations and limited behavioral detail. It does not address the optional schema filter, which is a common source of confusion. The description provides only minimal context, which is insufficient for an agent to use the tool optimally, even with annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not mention any of the three parameters (limit, offset, schema). With low coverage, the description must compensate, but it completely fails to explain what these parameters control. An agent would have to rely solely on the schema, which may be insufficient for understanding the schema parameter's purpose. This is a critical gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('List persistent graphs') on a clear resource, and adds the context of being a preliminary step ('before choosing schema and graph context'). This clearly distinguishes it from siblings like nebula_get_graph_schema (which retrieves schema) and nebula_execute_query (which executes queries). The verb-resource pairing is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear 'when to use' signal ('before choosing schema and graph context'), which is helpful. However, it does not explicitly mention when not to use it or alternative tools, only implying its role as a precursor. A 4 is appropriate because it provides clear context but lacks explicit exclusions or alternative routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Test the configured YueShu connection and return only redacted settings.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| config | Yes | |
| version | Yes | |
| connected | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish read-only, idempotent, open-world, and non-destructive behavior. The description adds value by disclosing that the response is redacted, which is a meaningful behavioral trait beyond the annotations. It does not contradict any annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no filler, front-loading the action ('Test') before the output detail ('return only redacted settings'). Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no parameters, an output schema present, and a clear one-sentence description, nothing essential is missing for an agent to invoke this tool correctly. The redaction note and connection-testing purpose fully cover the low-complexity context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the schema coverage is effectively complete, so there is no parameter burden for the description to carry. The baseline of 4 applies here because no parameter documentation is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Test') and identifies the resource ('configured YueShu connection'), then clarifies the scope of the response ('return only redacted settings'). This makes the tool's purpose immediately distinguishable from sibling tools like nebula_execute_query or nebula_get_graph_schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'Test the configured YueShu connection' clearly implies use as a connectivity/health check before graph operations, and the sibling list reinforces that it is not for querying or schema work. It lacks explicit when-not-to-use statements or named alternatives, but the context is clear enough to guide selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Validate YueShu 5.3 GQL for placeholders, dialect residuals, policy, and optional EXPLAIN. This never executes the original statement.
| Name | Required | Description | Default |
|---|---|---|---|
| graph | No | ||
| statement | Yes | ||
| run_explain | No |
| Name | Required | Description |
|---|---|---|
| policy | Yes | |
| explain | No | |
| evidence | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly discloses that the original statement is never executed, which goes beyond the readOnlyHint annotation by ruling out even read-side execution. It also surfaces optional EXPLAIN behavior, which helps set expectations for the run_explain parameter. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. Every phrase adds meaning, and the most important safety behavior is placed at the end for emphasis.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is strong on safety and purpose, and the output schema plus annotations reduce the need for return-value detail. However, for a 3-parameter tool with zero schema coverage, it leaves the 'graph' parameter unexplained and does not explicitly establish when to use validation versus execution.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must carry the parameter-meaning burden. It does convey that 'statement' is the GQL being validated and hints at 'optional EXPLAIN' for run_explain, but it never explains the 'graph' parameter or specifies expected values for the validation dimensions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description opens with a specific verb, 'Validate,' and identifies the precise resource, 'YueShu 5.3 GQL,' along with concrete validation dimensions: placeholders, dialect residuals, policy, and optional EXPLAIN. This clearly distinguishes it from sibling execution-oriented tools such as nebula_execute_query.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The statement 'This never executes the original statement' clearly implies a safe validation use case and separates this tool from execution tools. However, it does not explicitly name alternatives or state when validation should be preferred over execution.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.3nebula_execute_mutationnebula_execute_querynebula_get_graph_schemanebula_list_graphsnebula_test_connectionnebula_validate_gqlScored across 6 tools
Each tool targets a distinct action and resource: connection testing, graph listing, GQL validation, schema retrieval, read queries, and mutations. There is no meaningful overlap, even between validate and execute, since the former never executes and the latter is read-only or mutation-specific.
All tools follow the same nebula_verb_noun pattern, with clear verbs like test, list, validate, get, and execute. The naming is consistent, predictable, and hierarchical.
Six tools is well-scoped for a graph database server covering connection, discovery, validation, schema, and execution. Each tool has a clear purpose without unnecessary bloat.
The tool surface covers the core workflow: connect, discover graphs, validate, inspect schema, execute reads, and execute mutations. Minor gaps exist, such as no explicit tool for listing all schemas or managing graphs, but these are likely outside the server's intended scope.
Repository knowledge graph MCP server for codebase understanding and debugging.
Token-free MCP server for structured RevoGrid Core, Pro, and Enterprise knowledge retrieval.
The Grafbase MCP server sits in front of a GraphQL API and exposes an MCP protocol-compliant interface that allows AI agents and LLMs to explore and query GraphQL APIs using natural language. It provides tools to search schemas, introspect types and fields, and execute GraphQL queries while minimizing context bloat by returning only relevant schema subsets, with built-in support for authentication, authorization, and configurable access control.
