bitflicker64 commented on code in PR #520: URL: https://github.com/apache/hugegraph-doc/pull/520#discussion_r4307802849
########## 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`. Review Comment: Minor: this sentence still calls the rename "the proposed naming fix", while the heading above and the next sentence say it is merged to apache/hugegraph-ai `main` in #382. The CN page (line 103, `该改动将默认工具集改名为`) already drops "proposed". Evidence: `hugegraph-mcp/hugegraph_mcp/toolsets.py` on hugegraph-ai `main` (84ee9c4, still current at 3fad379) sets `DEFAULT_TOOLSET = "core"` with the `v2_core`/`v1` aliases, so the rename is no longer a proposal. The 5ec34e7 update changed the heading and line 104 but left this line. Suggested wording: ```suggestion The default toolset is renamed to `core` and the compatibility toolset to `legacy`. ``` Optionally add "not yet released" to the EN heading to match the CN heading (`未发布`). -- 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]
