bitflicker64 commented on code in PR #520: URL: https://github.com/apache/hugegraph-doc/pull/520#discussion_r4249365096
########## 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. Review Comment: Minor: `v2` is one case of a wider behaviour that the page does not state. In 1.7.1 every value other than `v1` or `v2_core` makes the server log an error and register the 10-tool `v1` set. That includes an empty string and the future names `core` and `legacy` from the next section. Evidence: `_active_toolset()` in `hugegraph_mcp/server.py:54-59` on apache/hugegraph-ai `main` at 8a7c186 returns `"v1"` for any value outside `VALID_TOOLSETS`. `server.py` is unchanged since the 1.7.1 packaging commit 8189b96. A reader who copies `core` onto the pinned package loses `query_graph_data_tool` and the write-plan tools. Besides the server log, the signs in the client are a tool list of 10 and `toolset: "v1"` in the `inspect_graph_tool` response. Please state the fallback here, for example: "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." The same sentence is needed at line 98 of the CN page. ########## 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` | +| `HUGEGRAPH_USER` | `admin` | HugeGraph user | +| `HUGEGRAPH_PASSWORD` | Empty | HugeGraph password | +| `HUGEGRAPH_MCP_TOOLSET` | `v2_core` | This release accepts `v2_core` and `v1` | +| `HUGEGRAPH_MCP_READONLY` | `true` | Disable controlled writes | +| `HUGEGRAPH_MCP_ALLOW_AI` | `false` | Allow calls to HugeGraph-LLM | +| `HUGEGRAPH_MCP_ADMIN_MODE` | `false` | Enable eligible administrative operations | +| `HUGEGRAPH_AI_URL` | `http://127.0.0.1:8001` | HugeGraph-LLM service address | +| `HUGEGRAPH_AI_TOKEN` | Unset | HugeGraph-LLM bearer token | +| `HUGEGRAPH_AI_GRAPH_URL` | Unset | Does not change the AI target; deprecated and ignored in current source | +| `HUGEGRAPH_AI_TIMEOUT_SECONDS` | `30` | AI HTTP request timeout in seconds | +| `HUGEGRAPH_MCP_STATE_DIR` | XDG state directory or `~/.local/state/hugegraph-mcp` | Persistent directory for write plans and receipts | + +### Optional AI Features + +Configure and start the model service using the [HugeGraph-LLM guide](./hugegraph-llm.md), then add these entries to the MCP client's `env`: + +```json +{ + "HUGEGRAPH_MCP_ALLOW_AI": "true", + "HUGEGRAPH_AI_URL": "http://127.0.0.1:8001";, + "HUGEGRAPH_AI_TOKEN": "your-ai-service-token" +} +``` + +Merge these entries into the earlier `env` object. Generation and extraction can remain read-only. +Embedding refresh additionally requires `HUGEGRAPH_MCP_READONLY=false`, `HUGEGRAPH_MCP_ADMIN_MODE=true`, and `confirm=true` in the tool call. + +If MCP runs on the host and AI runs in a container, they may need different addresses to reach HugeGraph. +Configure `GRAPH_URL` on the AI service to an address reachable from its container, such as `http://server:8080`. +Set `GRAPH_NAME` and `GRAPH_SPACE` to match MCP. Do not use the container's `127.0.0.1` to reach the host graph service. +Changing the MCP address does not reconfigure the AI service target. + +**Refresh prerequisites in current AI source**: also set `ENABLE_LOGIN=true` and `HUGEGRAPH_LLM_ENABLE_THIN_WRITES=true` +on the service, configure a strong `USER_TOKEN`, and provide valid authentication through MCP's `HUGEGRAPH_AI_TOKEN`. +Older deployments may lack these gates; check the actual service version. Current MCP source requires +`GET /vid-embeddings/refresh-capabilities` to return `protocol_version=1`, then sends the expected graph +and graphspace for service-side validation before refreshing. Older services without the protocol are rejected. +This does not prove both sides connect to the same physical server. The protocol applies to current source and the next release, +not the published `1.7.1` installation examples above. + +For the default MCP target `DEFAULT/hugegraph`, explicitly configure AI `GRAPH_NAME=hugegraph` and `GRAPH_SPACE=DEFAULT`; an unset/null graphspace does not pass the exact target check. Review Comment: Important: this line and lines 195-199 describe the refresh capability protocol and the exact target check as "current source", but both exist only in the paired PR apache/hugegraph-ai#382, which is open, and the check itself is still under review there. Measured on 2026-10-12 against apache/hugegraph-ai `main` at 8a7c186: - `git grep -E "refresh-capabilities|protocol_version|expected_graphspace" origin/main -- hugegraph-llm/src hugegraph-mcp/hugegraph_mcp` returns nothing. On `main`, `tools/refresh_vid_embeddings.py` posts `{}` to `/vid-embeddings/refresh` and `thin_api.py:153-157` runs the flow with no target comparison. - `hugegraph_mcp/server.py:47-48` on `main` still has `DEFAULT_TOOLSET = "v2_core"` and `VALID_TOOLSETS = frozenset({"v1", DEFAULT_TOOLSET})`. There is no `core` or `legacy`, and `HUGEGRAPH_MCP_TOOLSET=core` falls back to the 10-tool `v1` set (`_active_toolset()`, `server.py:54-59`). Both changes are present only at the #382 head bdf7654. That PR has two reviews from 2026-10-12 (bitflicker64 and imbajin) whose bodies start with `Blocking: yes`, both about this target check. The first asks for an unset AI `GRAPH_SPACE` to be treated as `DEFAULT`, which would make this line wrong as written. If this page is published first, a reader who runs HugeGraph-LLM from `main` and follows this line gets no target check in return, and setting `GRAPH_SPACE=DEFAULT` moves the Text2Gremlin example index from `hugegraph/gremlin_examples` to `DEFAULT_hugegraph/gremlin_examples` (`get_index_folder_name`, used at `demo/rag_demo/text2gremlin_block.py:85`). The PR description already names #382 as paired, so please do one of these: 1. Merge this after #382 and re-check lines 101-110, 169 and 195-201 (CN 101-110, 168 and 193-197) against the merged code. 2. Or say "proposed in apache/hugegraph-ai#382, not yet merged" instead of "current source" at lines 195-199 (CN 193-195), change "unreleased" to "unmerged" at lines 101-105, drop "deprecated" at line 169 (CN 168), and remove this line (CN 197) until the target rule is settled. The `ENABLE_LOGIN` and `HUGEGRAPH_LLM_ENABLE_THIN_WRITES` gates at lines 193-194 are on `main` already (`thin_api.py:112-130`) and need no change. -- 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]
