This is an automated email from the ASF dual-hosted git repository. spmallette pushed a commit to branch js-translator in repository https://gitbox.apache.org/repos/asf/tinkerpop.git
commit 8f32db22948453fde5a1fa47c91f695adc092433 Author: Stephen Mallette <[email protected]> AuthorDate: Fri Mar 13 18:17:52 2026 -0400 Added docs for gremlin-mcp and javascript translator --- CHANGELOG.asciidoc | 3 ++ docs/src/reference/gremlin-applications.asciidoc | 40 +++++++++++++++++++-- docs/src/upgrade/release-4.x.x.asciidoc | 46 ++++++++++++++++++++++++ gremlin-mcp/src/main/javascript/README.md | 20 ++++++++++- 4 files changed, 106 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.asciidoc b/CHANGELOG.asciidoc index 8163211650..679792f59d 100644 --- a/CHANGELOG.asciidoc +++ b/CHANGELOG.asciidoc @@ -23,6 +23,9 @@ image::https://raw.githubusercontent.com/apache/tinkerpop/master/docs/static/ima [[release-4-0-0]] === TinkerPop 4.0.0 (NOT OFFICIALLY RELEASED YET) +* Added grammar-based `Translator` for `gremlin-javascript` supporting translation to JavaScript, Python, Go, .NET, Java, Groovy, canonical, and anonymized output. +* Added `translate_gremlin_query` tool to `gremlin-mcp` that translates Gremlin queries to a target language variant, with optional LLM-assisted normalization via MCP sampling for non-canonical input. +* Modified `gremlin-mcp` to support offline mode where utility tools (translate, format) remain available without a configured `GREMLIN_MCP_ENDPOINT`. * Added `__contains__` and `keys()` to `Element` in `gremlin-python`. * Added `subgraph()` support for `gremlin-python` so that results are stored in a detached `Graph` object. * Modified grammar to make `discard()` usage more consistent as a filter step where it can now be used to chain additional traversal steps and be used anonymously. diff --git a/docs/src/reference/gremlin-applications.asciidoc b/docs/src/reference/gremlin-applications.asciidoc index d72a63c07c..eada1a5120 100644 --- a/docs/src/reference/gremlin-applications.asciidoc +++ b/docs/src/reference/gremlin-applications.asciidoc @@ -2351,9 +2351,12 @@ input schema, and a result schema. When connected to a Gremlin MCP server, the a * Inspect the server’s health and connection to a Gremlin data source * Discover the graph’s schema (labels, properties, relationships, counts) * Execute Gremlin traversals +* Translate Gremlin queries between language variants +* Format Gremlin queries for readability The Gremlin MCP server sits alongside Gremlin Server (or any TinkerPop‑compatible endpoint) and forwards tool calls to -the graph via standard Gremlin traversals. +the graph via standard Gremlin traversals. The translation and formatting tools are utility tools that work +independently and do not require a graph connection. IMPORTANT: This MCP server is designed for development and trusted environments. @@ -2380,6 +2383,7 @@ The Gremlin MCP server exposes these tools: properties may be surfaced as enums to encourage valid values in queries. * `run_gremlin_query` — Executes an arbitrary Gremlin traversal and returns JSON results. * `refresh_schema_cache` — Forces schema discovery to run again when the graph has changed. +* `translate_gremlin_query` — Translates a Gremlin query to a target language variant with optional normalization. * `format_gremlin_query` — Formats a Gremlin query using gremlint. ==== Schema discovery @@ -2437,6 +2441,38 @@ g.V(). limit(1).fold()) ---- +==== Translating traversals + +The `translate_gremlin_query` tool translates a Gremlin query from one language variant to another. Supported +targets are: `canonical`, `javascript`, `python`, `go`, `dotnet`, `java`, `groovy`, and `anonymized`. The +`canonical` target produces gremlin-language ANTLR format with normalized whitespace and explicit enum names, +which is useful for validating or standardizing queries before further processing. + +The optional `source` parameter controls how the input is pre-processed before translation: + +* When omitted or set to `auto` (the default), the server applies mechanical normalization (stripping + language-specific prefixes, correcting step casing) and then requests LLM normalization from the MCP client + via MCP sampling. This handles input from any dialect without the caller needing to know the source language. + If the MCP client does not support sampling, the LLM step is skipped and a `warning` field is included in + the response to indicate that the result is based on mechanical normalization only. +* When set to `canonical`, normalization is skipped entirely and the input is passed directly to the translator. + This is the most efficient path when the input is known to be in canonical gremlin-language ANTLR format. + +For example, a user could supply this prompt to the assistant: + +[source,text] +---- +Translate this Go traversal to Groovy: +gremlingo.T__.V().Has("name", "Alice").Out("knows").Values("name") +---- + +And the assistant would call `translate_gremlin_query` with `target: "groovy"` and receive: + +[source,groovy] +---- +g.V().has('name', 'Alice').out('knows').values('name') +---- + ==== Executing traversals When the assistant needs to answer a question, a common sequence is: @@ -2461,7 +2497,7 @@ endpoint the server should use. Basic connection settings: -* `GREMLIN_MCP_ENDPOINT` — `host:port` or `host:port/traversal_source` for the target Gremlin Server or compatible endpoint (default traversal source: `g`) +* `GREMLIN_MCP_ENDPOINT` — `host:port` or `host:port/traversal_source` for the target Gremlin Server or compatible endpoint (default traversal source: `g`). Optional — when not set, graph tools are not registered but `translate_gremlin_query` and `format_gremlin_query` remain available. * `GREMLIN_MCP_USE_SSL` — set to `true` when TLS is required by the endpoint (default: `false`) * `GREMLIN_MCP_USERNAME` / `GREMLIN_PASSWORD` — credentials when authentication is enabled (optional) * `GREMLIN_MCP_IDLE_TIMEOUT` — idle connection timeout in seconds (default: `300`) diff --git a/docs/src/upgrade/release-4.x.x.asciidoc b/docs/src/upgrade/release-4.x.x.asciidoc index 6033d969c3..6d0123b096 100644 --- a/docs/src/upgrade/release-4.x.x.asciidoc +++ b/docs/src/upgrade/release-4.x.x.asciidoc @@ -30,6 +30,52 @@ complete list of all the modifications that are part of this release. === Upgrading for Users +==== Gremlin MCP Server + +===== Gremlin Query Translation + +A `translate_gremlin_query` tool is now available that translates a Gremlin query into a target language variant. +Supported targets are `canonical`, `javascript`, `python`, `go`, `dotnet`, `java`, `groovy`, and `anonymized`. + +The optional `source` parameter describes the dialect of the input. When omitted or set to `auto`, the server +normalizes the input before translating — first by applying mechanical transformations (stripping language-specific +prefixes, correcting step casing, etc.) and then by requesting LLM normalization from the MCP client via MCP +sampling. If the MCP client does not support sampling, the LLM step is skipped gracefully and a warning is included +in the response. Set `source` to `canonical` to bypass normalization entirely when the input is already in canonical +gremlin-language ANTLR format. + +Some example prompts that will invoke this tool: + +[source,text] +---- +Translate g.V().has('name','Alice').out('knows').values('name') to Python. +---- + +[source,text] +---- +Convert this Go Gremlin traversal to Groovy: +gremlingo.T__.V().Has("name", "Alice").Out("knows").Values("name") +---- + +[source,text] +---- +I have some Java Gremlin code. Translate it to canonical format so I can review it: +g.V().has("name", "Alice").out("knows").values("name") +---- + +===== Offline Mode + +`GREMLIN_MCP_ENDPOINT` is no longer required to start the server. When no endpoint is configured, graph tools +(`get_graph_status`, `get_graph_schema`, `run_gremlin_query`) are not registered, but the utility tools +(`translate_gremlin_query`, `format_gremlin_query`) remain fully available. This makes it possible to use the +Gremlin MCP Server purely as a translation and formatting aid without any graph database: + +[source,text] +---- +Format this Gremlin query for readability: +g.V().has('name','Alice').out('knows').out('knows').where(neq('Alice')).values('name').dedup() +---- + ==== SLF4j 2.x TinkerPop has generally upgraded to SLF4j 2.x which brings with it some important changes to log initialization which diff --git a/gremlin-mcp/src/main/javascript/README.md b/gremlin-mcp/src/main/javascript/README.md index aa2a6659d3..d3741be8ae 100644 --- a/gremlin-mcp/src/main/javascript/README.md +++ b/gremlin-mcp/src/main/javascript/README.md @@ -48,8 +48,26 @@ Your AI assistant gets access to these powerful tools: | 📋 **get_graph_schema** | Schema Discovery | Get complete graph structure with vertices and edges | | ⚡ **run_gremlin_query** | Query Execution | Execute any Gremlin traversal query with full syntax support | | 🔄 **refresh_schema_cache** | Cache Management | Force immediate refresh of cached schema information | +| 🔄 **translate_gremlin_query** | Translation | Translate a Gremlin query to a target language variant | | 👌 **format_gremlin_query** | Query Formatting | Format a Gremlin query string using gremlint | +### Gremlin Query Translation + +The `translate_gremlin_query` tool translates a Gremlin query to a target language variant. Supported targets +are: `canonical`, `javascript`, `python`, `go`, `dotnet`, `java`, `groovy`, and `anonymized`. + +The optional `source` parameter describes the dialect of the input. When omitted or set to `auto` (the default), +the server first applies mechanical normalization and then requests LLM normalization from the MCP client via MCP +sampling before translating. If the MCP client does not support sampling, the LLM step is skipped and a warning +is included in the response. Set `source` to `canonical` to skip normalization entirely when the input is already +in canonical gremlin-language ANTLR format. + +### Offline Mode + +`GREMLIN_MCP_ENDPOINT` is optional. When not set, graph tools (`get_graph_status`, `get_graph_schema`, +`run_gremlin_query`, `refresh_schema_cache`) are not registered, but `translate_gremlin_query` and +`format_gremlin_query` remain fully available. + ## 🚀 Quick Setup ### Step 1: Install @@ -333,7 +351,7 @@ This intelligent enum discovery transforms how AI agents interact with your grap ### Basic Configuration ```bash -# Required +# Optional - when not set, graph tools are unavailable but translate and format tools remain active GREMLIN_MCP_ENDPOINT="localhost:8182" # Optional
