imbajin commented on code in PR #520:
URL: https://github.com/apache/hugegraph-doc/pull/520#discussion_r4264105026
##########
data/docs_nav.json:
##########
@@ -103,6 +103,9 @@
{
"page": "/docs/quickstart/hugegraph-ai/hugegraph-llm"
},
+ {
+ "page": "/docs/quickstart/hugegraph-ai/hugegraph-mcp"
Review Comment:
⚠️ Important: Blocking: yes. Summary: This new MCP route changes navigation
metadata for latest and historical versions, but the pinned baselines were not
updated. Evidence: exact-head Build and deploy site run 38222905036 fails
navigation validation: latest has 93 pages vs expected 92; 1.3, 1.5, and 1.7
each have one more removed page than expected. `scripts/versioning.py` still
contains the old `DOCS_NAV_EXPECTED_STATS`. Requested change: regenerate/update
the expected navigation statistics for latest and every affected historical
version.
##########
content/en/docs/quickstart/hugegraph-ai/hugegraph-mcp.md:
##########
@@ -0,0 +1,225 @@
+---
+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 |
+
+Do not use `v2`; it is not a supported toolset name in this release.
+Both toolsets report `mcp_tool_contract_version="2.0"`. This field describes
the tool contract, not the package version.
+
+### New Names (Not Yet Released)
+
+The naming fix renames the default toolset to `core` and the compatibility
toolset to `legacy`.
+This section describes an unreleased change and **does not apply to the 1.7.1
installation command above**.
+The release version and upgrade command must be updated after publication.
+
+- `v2_core` maps to `core`, and `v1` maps to `legacy`. Old values remain
compatibility aliases and emit a migration warning.
+- Inspection reports only `core` or `legacy`. Clients comparing `data.toolset`
or `meta.toolset` must update those comparisons.
+- An unset variable selects `core`. Empty or unknown values prevent startup
instead of falling back to the compatibility toolset.
+- Toolset selection happens at startup and requires a restart to change.
Compatibility mode does not bypass permission checks.
+
+## Tool Capabilities
+
+A registered tool does not imply that every operation is enabled. The current
capability boundaries are summarized below.
+Use the tool schema returned to your client for exact parameters.
+
+| Feature | Tools | Scope |
+|---|---|---|
+| Inspection and design | `inspect_graph_tool`, `inspect_schema_tool`,
`design_schema_tool` | Connection status, schema, and design guidance |
+| Structured reads | `query_graph_data_tool` | Read vertices and edges by ID,
ID list, page, or conditions |
+| Schema creation | `apply_schema_tool` | Validate and preview; the default
toolset can confirm one property key, vertex label, or edge label creation |
+| Write plans | `confirm_write_tool`, `get_write_status_tool`,
`reconcile_write_tool` | Confirm, inspect, and reconcile persistent plans |
+| Graph import | `import_graph_data_tool` | AI-backed `extract`; preview-only
`ingest`; `table` is currently disabled |
+| Graph deletion | `delete_graph_data_tool` | Exact edge deletion can be
confirmed; vertex deletion is preview-only |
+| Property changes | `mutate_graph_properties_tool` | Preview-only;
confirmation is currently disabled |
+| AI generation and extraction | `generate_gremlin_tool`,
`extract_graph_data_tool` | Generate queries or candidate graph data without
executing generated queries |
+| Embedding refresh | `refresh_vid_embeddings_tool` | Requires AI, admin mode,
writes enabled, and explicit confirmation; see current-source service gates
below |
+| Raw Gremlin | `execute_gremlin_read_tool`, `execute_gremlin_write_tool` |
Both return `FEATURE_DISABLED`; admin mode cannot override this |
+
+The compatibility toolset excludes `inspect_schema_tool`,
`query_graph_data_tool`, `mutate_graph_properties_tool`,
+and the three write-plan tools. Switching to compatibility mode does not
enable raw Gremlin execution.
+
+### Controlled Writes
+
+To use writes, set `HUGEGRAPH_MCP_READONLY=false` and use a HugeGraph account
with the appropriate permissions.
+For a confirmable operation, first run a dry-run, review its exact targets,
changes, and warnings, then confirm the returned `plan_id`:
+
+```json
+{
+ "name": "confirm_write_tool",
+ "arguments": {"plan_id": "<PLAN_ID>"}
+}
+```
+
+Use `get_write_status_tool(plan_id)` to inspect the persisted result.
`APPLIED` means all operations are confirmed successful.
+`PARTIAL` or `UNKNOWN` means the workflow is incomplete or its outcome is
uncertain. Inspect and reconcile status before retrying;
+do not blindly create a replacement plan. Confirming the same completed plan
again returns its recorded result without repeating the write.
+
+The built-in SQLite state store requires a single writable MCP instance and a
persistent state directory.
+When multiple clients start separate processes, keep them read-only initially;
multi-instance writes require a shared transactional store design.
+Operations returning `confirmable=false` cannot be forced through by disabling
read-only mode or enabling admin mode.
+
+## Configuration
+
+The following defaults apply to published version `1.7.1`. HugeGraph
credentials and the HugeGraph-LLM API token are separate credentials.
+
+| Environment variable | Default | Description |
+|---|---|---|
+| `HUGEGRAPH_URL` | `http://127.0.0.1:8080` | HugeGraph address reachable from
the MCP process |
+| `HUGEGRAPH_GRAPH_PATH` | `DEFAULT/hugegraph` | `GRAPH_SPACE/GRAPH_NAME` |
Review Comment:
⚠️ Important: Blocking: no. Summary: The published 1.7.1 configuration also
accepts `HUGEGRAPH_GRAPHSPACE` and `HUGEGRAPH_GRAPH`, which override
`HUGEGRAPH_GRAPH_PATH`. Evidence: `hugegraph_mcp/config.py` at the 1.7.1
packaging commit `8189b96` applies these values after parsing the path; the
package README documents the same precedence. Requested change: add both
variables and their override behavior to the EN and CN configuration tables so
operators can tell which graph the process will use.
--
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]
