bitflicker64 commented on code in PR #520:
URL: https://github.com/apache/hugegraph-doc/pull/520#discussion_r4303155669
##########
data/docs_nav.json:
##########
@@ -1035,6 +1043,11 @@
"/docs/quickstart/hugegraph-ai/",
"/docs/quickstart/hugegraph-ai/hugegraph-llm/"
],
+ "/docs/quickstart/hugegraph-ai/hugegraph-mcp/": [
Review Comment:
Important: the new page is in the navigation but not in
`data/version_routes.json`, so version validation for latest fails at this head.
Evidence, run at b1561ad with the CI commands:
- `python3 scripts/versioning.py build --version latest --sha b1561ad...
--site-origin https://hugegraph.apache.org --historical-origin
https://hugegraph.apache.org --output out/latest` succeeds. Its
`docsNavigation` is `{pages: 96, removed: 4, scopedLinks: 0, treeSha256:
8b2b1f27...}`, which matches the new `DOCS_NAV_EXPECTED_STATS`.
- `python3 scripts/versioning.py validate --version latest ...` on that
artifact exits 1 with `current canonical Docs page is absent from route-map:
latest cn/docs/quickstart/hugegraph-ai/hugegraph-mcp/`
(`_version_switch_options`, `scripts/versioning.py:2683-2687`).
- `scripts/build_versions.py` runs `validate` after every build (lines 62
and 70), so the "Build and validate selected versions" job fails once the
workflow is approved. After merge it would also block the master deploy.
The last page-adding change did this: #527 added `cn:` and `en:` entries for
each new Helm page to `data/version_routes.json`. Please add these two entries
next to `quickstart/hugegraph-ai/hugegraph-llm`:
```json
"cn:quickstart/hugegraph-ai/hugegraph-mcp": {"latest":
"cn/docs/quickstart/hugegraph-ai/hugegraph-mcp/", "1.7": null, "1.5": null,
"1.3": null, "1.0": null},
"en:quickstart/hugegraph-ai/hugegraph-mcp": {"latest":
"docs/quickstart/hugegraph-ai/hugegraph-mcp/", "1.7": null, "1.5": null, "1.3":
null, "1.0": null}
```
With exactly these entries added locally, a rebuild of latest followed by
`validate` passes (`validated latest: 333 canonical pages`).
##########
content/en/docs/quickstart/hugegraph-ai/hugegraph-mcp.md:
##########
@@ -0,0 +1,226 @@
+---
+title: "HugeGraph-MCP"
+linkTitle: "HugeGraph-MCP"
+weight: 7
+---
+
+`hugegraph-mcp` exposes HugeGraph tools to AI clients through the Model
Context Protocol (MCP).
+It supports schema inspection, structured graph queries, controlled writes,
and optional natural-language query generation and graph extraction.
+The MCP client starts a local process and communicates over STDIO. This
process is not HugeGraph Server and does not expose an HTTP MCP endpoint.
+
+Ordinary graph queries connect directly to HugeGraph Server. Query generation,
extraction, and embedding refresh also require
+[HugeGraph-LLM](./hugegraph-llm.md), where model credentials are configured.
+
+## Requirements
+
+- Python 3.10 or later. A separate HugeGraph-LLM service must also meet that
module's Python requirements.
+- [uv](https://docs.astral.sh/uv/getting-started/installation/) and an MCP
client that supports STDIO.
+- HugeGraph Server 1.7.0 or later, reachable from the MCP process. The default
graph path is `DEFAULT/hugegraph` and uses the graphspace API.
+- An existing graph and an account with the required permissions. See
[authentication and authorization](../../config/config-authentication.md).
+
+## Installation and Connection
+
+These examples pin the published `hugegraph-mcp==1.7.1` package. Cloning the
repository is not required.
+Replace the address, graph path, and credentials with your deployment values.
Verify the connection in read-only mode before enabling supported writes.
+
+For clients that accept a `mcpServers` JSON configuration, add:
+
+```json
+{
+ "mcpServers": {
+ "hugegraph": {
+ "command": "uvx",
+ "args": ["[email protected]"],
+ "env": {
+ "HUGEGRAPH_URL": "http://127.0.0.1:8080";,
+ "HUGEGRAPH_GRAPH_PATH": "DEFAULT/hugegraph",
+ "HUGEGRAPH_USER": "your-user",
+ "HUGEGRAPH_PASSWORD": "your-password",
+ "HUGEGRAPH_MCP_READONLY": "true"
+ }
+ }
+ }
+}
+```
+
+Configuration locations and formats vary between clients. Use your client's
instructions to set the same command, arguments, and environment variables.
+If the client cannot find `uvx`, use its absolute path for `command`. Restart
the MCP process after changing the configuration.
+
+You can also start it in a terminal with the environment variables above
already configured:
+
+```bash
+uvx [email protected]
+```
+
+The process waits for protocol messages from the MCP client on stdin; it does
not open a web page.
+stdout carries MCP JSON-RPC. Do not write extra shell output to that channel.
+
+### Verify the Connection
+
+List tools through the client, then call `inspect_graph_tool`. The following
JSON is the parameter body for MCP `tools/call`,
+not a request to send directly to the HugeGraph REST API.
+
+```json
+{
+ "name": "inspect_graph_tool",
+ "arguments": {"include_raw_schema": true}
+}
+```
+
+Check for `ok=true` and `data.hugegraph_server_status="available"`.
+Choose an existing vertex label from the schema and replace `person` below
with that label:
+
+```json
+{
+ "name": "query_graph_data_tool",
+ "arguments": {
+ "target": "vertex",
+ "operation": "page",
+ "label": "person",
+ "limit": 5
+ }
+}
+```
+
+This tool belongs to the default set of 16 tools. To paginate, pass the
returned `next_page` as `page` on the next call,
+keeping the same query conditions. An empty result does not necessarily mean
the connection failed; check the graph path, label, and existing data.
+
+## Toolsets and Versions
+
+A toolset selects a group of tools within the same package. It is not a
package version, HugeGraph Server version, or MCP protocol version.
+Version `1.7.1` accepts the following configuration names:
+
+| `HUGEGRAPH_MCP_TOOLSET` | Tools | Purpose |
+|---|---|---|
+| Unset, or `v2_core` | 16 | Default toolset, including structured queries and
persistent write-plan tools |
+| `v1` | 10 | Compatibility toolset retaining earlier tool entry points |
+
+Any other value, including `v2`, `core`, `legacy` or an empty string, falls
back to the 10-tool `v1` set in 1.7.1 and logs an error.
+Both toolsets report `mcp_tool_contract_version="2.0"`. This field describes
the tool contract, not the package version.
+
+### New Names (Proposed in apache/hugegraph-ai#382)
Review Comment:
Important: this heading, line 104 ("an unmerged change") and lines 195-198
("proposed AI changes", "(not yet merged)") say apache/hugegraph-ai#382 is
unmerged. It merged on 2026-10-13 as 84ee9c4, four days before this head commit.
Evidence, from apache/hugegraph-ai `main` at 84ee9c4:
- `hugegraph_mcp/toolsets.py`: `DEFAULT_TOOLSET = "core"`, aliases `v2_core
-> core` and `v1 -> legacy` that log a deprecation warning, and `ValueError`
for empty or unknown values. This matches the bullets at lines 107-110.
- `tools/refresh_vid_embeddings.py:46-81` calls `GET
/vid-embeddings/refresh-capabilities`, requires `protocol_version == 1`, then
sends `expected_graph` and `expected_graphspace`.
`hugegraph_llm/api/thin_api.py:166-196` checks them. This matches lines 198-201.
- The `ENABLE_LOGIN` / `HUGEGRAPH_LLM_ENABLE_THIN_WRITES` gate
(`thin_api.py:116-129`) was on `main` before #382. It is absent from the
hugegraph-ai 1.7.0 tag, which has no `thin_api.py`.
- PyPI still lists only `hugegraph-mcp` 1.7.1, so none of this is in a
published package yet.
The wording is now wrong in the other direction. A reader who runs from
`main`, which the "source and README" link points to, is told those defaults
and the startup failure are not in the code yet. For example,
`HUGEGRAPH_MCP_TOOLSET=v2` stops the server on `main` instead of falling back.
Please change "Proposed in / not yet merged / unmerged / proposed AI
changes" to "merged to apache/hugegraph-ai `main` in #382, not yet in a
published release" here, at line 104 and at lines 195-198. Keep the statement
that this does not apply to 1.7.1. The CN page needs the same change at lines
101, 104, 193 and 195 ("提案，尚未合并", "尚未合并的改动", "AI 提案中的", "尚未合并的提案").
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
