This is an automated email from the ASF dual-hosted git repository. spmallette pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/tinkerpop.git
commit 86eae86ce4f431e33903f9314259d6d181231ebd Author: Stephen Mallette <[email protected]> AuthorDate: Sun Aug 9 09:26:46 2026 -0400 Retarget the agent tooling to 3.8-dev The forward merge brought 3.7-dev's text across intact, so AGENTS.md and the skill both claimed to be on 3.7-dev. Java is 11 here (17 supported, 21 and 25 experimental since 3.8.2), Python is 3.10+, and gremlin-mcp exists and is back in the build tables with a reference guide written against this branch's module layout. Assisted-by: Claude Code:claude-opus-5 --- .skills/tinker-dev/SKILL.md | 18 ++++--- .../tinker-dev/references/dev-environment-setup.md | 18 ++++--- .skills/tinker-dev/references/gremlin-mcp.md | 63 ++++++++++++++++++++++ .skills/tinker-dev/scripts/check-env.sh | 18 +++---- .skills/tinker-doc/references/books-and-voice.md | 8 +-- AGENTS.md | 8 +-- .../dev/developer/development-environment.asciidoc | 2 +- 7 files changed, 103 insertions(+), 32 deletions(-) diff --git a/.skills/tinker-dev/SKILL.md b/.skills/tinker-dev/SKILL.md index df4db69999..754f80d894 100644 --- a/.skills/tinker-dev/SKILL.md +++ b/.skills/tinker-dev/SKILL.md @@ -5,9 +5,9 @@ description: > testing, or contributing to TinkerPop's graph computing framework and its multi-language Gremlin ecosystem (Java, Python, JavaScript, .NET, Go). Covers coding conventions, build recipes, test evaluation, documentation, - and development environment setup. + development environment setup, and Gremlin MCP server usage. license: Apache-2.0 -compatibility: Requires Java 8 or 11 (build with 11, cross-compiled to 8), Maven 3.5.3+, Docker. Individual GLVs may need Python, Node.js, .NET SDK, or Go. +compatibility: Requires Java 11 (17 supported; 21 and 25 experimental since 3.8.2), Maven 3.5.3+, Docker. Individual GLVs may need Python, Node.js, .NET SDK, or Go. metadata: version: 1.0.0 project: Apache TinkerPop @@ -58,6 +58,7 @@ always list every module you touched. | .NET GLV | `mvn verify -pl :gremlin-dotnet,:gremlin-dotnet-source,:gremlin-dotnet-tests` | | Go GLV | `mvn verify -pl :gremlin-go` | | `gremlint` | `mvn verify -pl :gremlint` | +| `gremlin-mcp` | `mvn verify -pl :gremlin-mcp` | | Other single JVM module (e.g. `tinkergraph-gremlin`, `gremlin-console`, `neo4j-gremlin`, `sparql-gremlin`, `gremlin-archetype`) | `mvn verify -pl <module> -DskipIntegrationTests=false` | **Shared modules** — depended on by others, so changing them means validating the consumers too. @@ -101,8 +102,10 @@ Most module names map directly to their purpose (`gremlin-core`, `gremlin-server `gremlin-go`, etc.). Two things that aren't obvious: - **Every module is top-level**, including the JavaScript ones: `gremlin-javascript/` (the - `gremlin` npm driver) and `gremlint/` sit directly under the repository root. Later branches - group them under a `gremlin-js/` workspace, so a path from `master` will not resolve here. + `gremlin` npm driver), `gremlint/` and `gremlin-mcp/` sit directly under the repository root, + each holding its npm project under `src/main/javascript/`. `master` groups them into a + `gremlin-js/` workspace with the npm project at the module root, so a path from `master` will + not resolve here. - **Maven orchestrates the build for every module, including the non-JVM ones** (Python, JavaScript, .NET, Go) — which is why the validation in the Definition of Done runs through Maven rather than each language's native test runner. @@ -133,9 +136,9 @@ The general Do/Don't rules and "when in doubt" guidance live in the root `AGENTS single source of truth, not repeated here. The conventions below are the TinkerPop-specific ones that are easy to miss: -- **This is a maintenance branch.** `3.7-dev` takes non-breaking bug fixes and enhancements - only. Within the 3.7.x line a change must not alter existing behavior, introduce new APIs, - change serialization formats, or modify protocols — a client of one 3.7.x version must still +- **This is a maintenance branch.** `3.8-dev` takes non-breaking bug fixes and enhancements + only. Within the 3.8.x line a change must not alter existing behavior, introduce new APIs, + change serialization formats, or modify protocols — a client of one 3.8.x version must still interact correctly with a server of another. Anything that fails that test belongs on a later branch. See `docs/src/dev/developer/for-committers.asciidoc`. - **License header**: every new file needs the ASF header. Canonical text: `bin/asf-license-header.txt`. @@ -162,3 +165,4 @@ Build and validate commands live in the **Definition of Done** table above. For task-specific guidance, see: - [Development Environment Setup](references/dev-environment-setup.md) — fresh clone to working environment, prerequisites, GLV activation +- [Gremlin MCP Server](references/gremlin-mcp.md) — schema discovery, querying and formatting via MCP diff --git a/.skills/tinker-dev/references/dev-environment-setup.md b/.skills/tinker-dev/references/dev-environment-setup.md index f94935b6b5..60b60b9173 100644 --- a/.skills/tinker-dev/references/dev-environment-setup.md +++ b/.skills/tinker-dev/references/dev-environment-setup.md @@ -7,10 +7,11 @@ The canonical reference is `docs/src/dev/developer/development-environment.ascii ### Minimum (Java-only build) -- **Java 8 or 11** — OpenJDK recommended, with Java 11 preferred: the build cross-compiles to - Java 8 bytecode. Use [SDKMAN!](https://sdkman.io/) to manage versions. Java 17 also compiles, - but deep reflection needs the `--add-opens` JVM options already configured in the pom files. - Use Java 11 for documentation generation with `bin/process-docs.sh`. +- **Java 11** — the minimum, and what the build targets. Java 17 also works. Since 3.8.2 there + is experimental support for Java 21 and 25 across every module except `spark-gremlin`, whose + Spark version only runs on Java 8 through 17. Deep reflection needs the `--add-opens` JVM + options already configured in the pom files. Use [SDKMAN!](https://sdkman.io/) to manage + versions. - **Maven 3.5.3+** — also manageable via SDKMAN. With just Java and Maven you can build JVM modules and get a clean `mvn clean install`, but @@ -21,10 +22,13 @@ GLV builds and many integration tests will be skipped. - **Docker and Docker Compose** — required for all GLV test execution. Docker Desktop includes both. GLV tests run inside Docker containers, so local language runtimes are optional for test execution via Maven. -- **Python 3.9–3.13** — optional for local development; Docker handles test execution. +- **Python 3.10–3.13** — optional for local development; Docker handles test execution. - **Node.js 20+ / npm 10+** — optional; Maven downloads a local copy via `frontend-maven-plugin` - (`node.version` and `npm.version` in the root `pom.xml` pin the exact versions used by the - build). Consider [nvm](https://github.com/nvm-sh/nvm) for version management. + for `gremlin-javascript`, `gremlint` and `gremlin-mcp` (the `runtime.node.version` property in + the root `pom.xml` pins the exact version used by the build). The `docs/gremlint` web app is + the exception: it needs Node and npm installed locally, and `bin/generate-home.sh` and + `bin/publish-home.sh` build it. Consider [nvm](https://github.com/nvm-sh/nvm) for version + management. - **.NET SDK 6.0+** — optional; Docker handles test execution. `Gremlin.Net` targets `netstandard2.0` and `net6.0`. - **Go 1.25+** — optional; Docker handles test execution. diff --git a/.skills/tinker-dev/references/gremlin-mcp.md b/.skills/tinker-dev/references/gremlin-mcp.md new file mode 100644 index 0000000000..f8530a26c3 --- /dev/null +++ b/.skills/tinker-dev/references/gremlin-mcp.md @@ -0,0 +1,63 @@ +# Gremlin MCP Server + +The Gremlin MCP server (`gremlin-mcp`) is an MCP (Model Context Protocol) server that +enables AI assistants to interact with Apache TinkerPop-compatible graph databases. The +Maven module is `gremlin-mcp/` and the npm project inside it lives at +`gremlin-mcp/src/main/javascript/`. It is published as the `gremlin-mcp` npm package. + +## When to Use + +Use gremlin-mcp when you need to: +- **Query a graph database** through natural language via an AI assistant +- **Discover graph schema** including vertex/edge labels, properties, and relationship patterns +- **Format Gremlin queries** using gremlint for consistent style + +## Available Tools + +| Tool | Purpose | +|--------------------------|----------------------------------------------------------------------| +| `get_graph_status` | Get the connection status of the Gremlin graph database | +| `get_graph_schema` | Vertex labels, edge labels, and relationship patterns | +| `run_gremlin_query` | Execute a Gremlin traversal query against the graph database | +| `refresh_schema_cache` | Force an immediate refresh of the graph schema cache | +| `format_gremlin_query` | Format a Gremlin query using gremlint, returning a structured result | + +All five register unconditionally. `GREMLIN_MCP_ENDPOINT` is **required** — the server will +not start without it, so there is no offline mode on this branch and no query-translation +tool. Both exist on `master` only; do not describe them as available here. + +Configuration is entirely environment-driven (`GREMLIN_MCP_ENDPOINT`, `GREMLIN_MCP_USE_SSL`, +`GREMLIN_MCP_USERNAME` / `_PASSWORD`, `GREMLIN_MCP_LOG_LEVEL`, `GREMLIN_MCP_IDLE_TIMEOUT`, and +the `GREMLIN_MCP_SCHEMA_*` / `GREMLIN_MCP_ENUM_*` schema-discovery settings). See +`src/main/javascript/src/config.ts` and `.env.example` for the full set. + +## Testing with MCP Inspector + +A fast way to test gremlin-mcp after building: +```bash +npx @modelcontextprotocol/inspector \ + node gremlin-mcp/src/main/javascript/dist/server.js \ + -e GREMLIN_MCP_ENDPOINT=localhost:8182/g \ + -e GREMLIN_MCP_LOG_LEVEL=info +``` + +This starts the MCP server and opens a browser-based tool for interacting with it. + +## Building gremlin-mcp + +Quick reference (validate per the **Definition of Done** table in `SKILL.md`): + +```bash +# Build only +mvn clean install -pl :gremlin-mcp -DskipTests + +# Build and test +mvn clean install -pl :gremlin-mcp + +# npm commands (from gremlin-mcp/src/main/javascript/) +npm test # Unit tests (jest) +npm run test:it # Integration tests (expects a server at localhost:8182/g) +npm run lint # Linting +npm run type-check # tsc --noEmit +npm run validate # format, lint, type-check and unit tests +``` diff --git a/.skills/tinker-dev/scripts/check-env.sh b/.skills/tinker-dev/scripts/check-env.sh index 1be8ac2fe0..7b3480da44 100755 --- a/.skills/tinker-dev/scripts/check-env.sh +++ b/.skills/tinker-dev/scripts/check-env.sh @@ -49,17 +49,15 @@ if command -v java &>/dev/null; then 1.*) java_version=$(echo "$java_version" | cut -d. -f2) ;; *) java_version=$(echo "$java_version" | cut -d. -f1) ;; esac - if [[ "$java_version" -eq 11 ]]; then - ok "Java $java_version (preferred for 3.7-dev)" - elif [[ "$java_version" -eq 8 ]]; then - ok "Java $java_version (supported; Java 11 is preferred and required for bin/process-docs.sh)" - elif [[ "$java_version" -gt 11 ]]; then - skip "Java $java_version found — 3.7-dev targets Java 8 and builds best on 11 (use sdkman.io to switch)" + if [[ "$java_version" -eq 11 || "$java_version" -eq 17 ]]; then + ok "Java $java_version (11 is the minimum, 17 is supported)" + elif [[ "$java_version" -eq 21 || "$java_version" -eq 25 ]]; then + skip "Java $java_version is experimental since 3.8.2 and excludes spark-gremlin — use 11 or 17 to validate everything" else - bad "Java $java_version found — version 8 or 11 required (use sdkman.io to install)" + bad "Java $java_version found — version 11 or 17 required (use sdkman.io to install)" fi else - bad "Java not found — install Java 8 or 11 (use sdkman.io)" + bad "Java not found — install Java 11 or 17 (use sdkman.io)" fi # --- Maven --- @@ -96,7 +94,7 @@ echo "Optional (GLV development):" # --- Python --- if command -v python3 &>/dev/null; then py_version=$(python3 --version 2>&1 | grep -oE '[0-9]+\.[0-9]+') - ok "Python $py_version (3.9-3.13 supported for gremlin-python local dev)" + ok "Python $py_version (3.10-3.13 supported for gremlin-python local dev)" else skip "Python 3 not found — Docker handles test execution, but local dev needs it" fi @@ -104,7 +102,7 @@ fi # --- Node.js --- if command -v node &>/dev/null; then node_version=$(node --version 2>/dev/null | sed 's/v//') - ok "Node.js $node_version (20+ recommended for gremlin-javascript local dev)" + ok "Node.js $node_version (20+ recommended for gremlin-javascript, gremlint and gremlin-mcp local dev)" else skip "Node.js not found — Maven downloads a local copy automatically" fi diff --git a/.skills/tinker-doc/references/books-and-voice.md b/.skills/tinker-doc/references/books-and-voice.md index 3548c0994b..af966a1b9f 100644 --- a/.skills/tinker-doc/references/books-and-voice.md +++ b/.skills/tinker-doc/references/books-and-voice.md @@ -10,9 +10,11 @@ The guidance below is what is specific to each book. ## Upgrade Documentation -`docs/src/upgrade/` — one file per minor line (`release-3.7.x.asciidoc`, etc.), -newest release section at the top, split into "Upgrading for Users" and, where -relevant, provider-facing notes. +`docs/src/upgrade/` — closed release lines get one file (`release-3.7.x.asciidoc`), +while the line under development gets one file per release (`release-3.8.2.asciidoc`). +Newest release section at the top, split into "Upgrading for Users" and, where +relevant, provider-facing notes. Check what is already in the directory rather than +assuming either shape. Upgrade documentation **announces** a release. It is the place where a feature is introduced to the world. This shapes everything about how it reads. diff --git a/AGENTS.md b/AGENTS.md index 1e8286b331..9b7eafac30 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -3,12 +3,12 @@ You are a TinkerPop developer working across the entire monorepo—code, tests, docs, and website to implement, maintain, and validate Apache TinkerPop's graph computing framework and its multi-language Gremlin ecosystem. -## This Branch: 3.7-dev +## This Branch: 3.8-dev -`3.7-dev` is a maintenance branch for the 3.7.x release line. It takes non-breaking bug fixes +`3.8-dev` is a maintenance branch for the 3.8.x release line. It takes non-breaking bug fixes and enhancements only: within the line a change must not alter existing behavior, introduce new APIs, change serialization formats, or modify protocols. The rule of thumb is that a client of -one 3.7.x version must still interact correctly with a server of another. Work that fails that +one 3.8.x version must still interact correctly with a server of another. Work that fails that test belongs on a later branch. Changes here merge forward toward `master` — see `docs/src/dev/developer/for-committers.asciidoc`. @@ -116,7 +116,7 @@ These rules apply to any AI/IDE assistant operating on this repository. - Don't perform large, sweeping refactors unless explicitly requested. - Don't change public APIs, configuration formats, serialization formats, or network protocols on this branch. Those are breaking changes and belong on a later branch — see - **This Branch: 3.7-dev** above. + **This Branch: 3.8-dev** above. - Don't switch documentation formats (e.g., AsciiDoc to Markdown) in the main docs tree. - Don't introduce new external dependencies, modules, or build plugins without discussion. - Don't invent project policies, version numbers, or release names. diff --git a/docs/src/dev/developer/development-environment.asciidoc b/docs/src/dev/developer/development-environment.asciidoc index 597ddf733a..937f017555 100644 --- a/docs/src/dev/developer/development-environment.asciidoc +++ b/docs/src/dev/developer/development-environment.asciidoc @@ -482,7 +482,7 @@ TinkerPop provides development guidance as link:https://agentskills.io[Agent Ski open Agent Skills standard: * `tinker-dev` covers project conventions, coding standards, build and test recipes for each Gremlin Language Variant, -and development environment setup, along with a verification script in `scripts/` +development environment setup and Gremlin MCP server usage, along with a verification script in `scripts/` * `tinker-doc` covers documentation authoring and review, meaning the per-book voice, the executable Gremlin code-block pipeline, and AsciiDoc conventions
