bitflicker64 commented on code in PR #520: URL: https://github.com/apache/hugegraph-doc/pull/520#discussion_r4307823856
########## 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 (Merged to apache/hugegraph-ai main in #382) + +The proposed naming fix renames the default toolset to `core` and the compatibility toolset to `legacy`. +This change is merged to apache/hugegraph-ai main in #382, but is not yet in a published release; it **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 graph data without executing generated queries | +| Embedding refresh | `refresh_vid_embeddings_tool` | Requires AI, admin mode, writes enabled, and confirmation; see 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_GRAPHSPACE` | Unset | Overrides the graphspace in `HUGEGRAPH_GRAPH_PATH` | +| `HUGEGRAPH_GRAPH` | Unset | Overrides the graph name in `HUGEGRAPH_GRAPH_PATH` | +| `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; 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 #382 (merged to main, not yet in a published release)**: also set `ENABLE_LOGIN=true` and `HUGEGRAPH_LLM_ENABLE_THIN_WRITES=true` Review Comment: Minor: this paragraph scopes the `ENABLE_LOGIN=true`, `HUGEGRAPH_LLM_ENABLE_THIN_WRITES=true` and `USER_TOKEN` requirements to #382 ("not yet in a published release"), and line 197 says older deployments may lack them, but the service-side gate is older than #382 and applies to the published 1.7.1 MCP as well. A 1.7.1 user who follows line 188 (read-only off, admin mode on, `confirm=true`) and skips this paragraph as not applying to them gets `FEATURE_DISABLED` ("Legacy Thin API writes are disabled") from the service. Evidence: on apache/hugegraph-ai `main`, `_thin_write_disabled()` in `hugegraph-llm/src/hugegraph_llm/api/thin_api.py` (lines 113-131) gates `POST /vid-embeddings/refresh`. `git log -S HUGEGRAPH_LLM_ENABLE_THIN_WRITES` and `git log -S '"/vid-embeddings/refresh"'` both trace back to aebc6c7 (2026-08-14, "fix(llm): align APIs and client integration"), two months before #382 (84ee9c4, 2026-10-13). That commit added the endpoint and the gate together. No tag contains it: the 1.7.0 tag has no `thin_api.py`. So every HugeGraph-LLM that serves the endpoint 1.7.1 calls (`tools/refresh_vid_embeddings.py` at 8189b96 posts `{}` to `/vid-embeddings/refresh`) also enforces the gate, and `main` still accepts that empty legacy body (`vid_embeddings_refresh_api`). Only the `refresh-capabilities` / `protocol_version=1` / `expected_graph` check is new in #382. Please split the paragraph. Move the `ENABLE_LOGIN` / `HUGEGRAPH_LLM_ENABLE_THIN_WRITES` / `USER_TOKEN` / `HUGEGRAPH_AI_TOKEN` requirements into the line 188 list as service-side requirements for refresh with 1.7.1. Drop "Older deployments may lack these gates". Keep only the capability-check protocol under the #382 label. CN lines 186-187 and 193-194 need the same 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]
