diff --git a/content/cn/docs/quickstart/hugegraph-ai/_index.md b/content/cn/docs/quickstart/hugegraph-ai/_index.md index 68c4232bd..6028ee7b3 100644 --- a/content/cn/docs/quickstart/hugegraph-ai/_index.md +++ b/content/cn/docs/quickstart/hugegraph-ai/_index.md @@ -10,6 +10,7 @@ weight: 3 ## 模块 +- [hugegraph-mcp](./hugegraph-mcp.md)：通过 MCP 向 AI 客户端提供图查询、Schema 和受控写入工具。 - [hugegraph-llm](https://github.com/apache/hugegraph-ai/tree/main/hugegraph-llm)：知识图谱构建、GraphRAG 和自然语言图查询。 - [hugegraph-ml](https://github.com/apache/hugegraph-ai/tree/main/hugegraph-ml)：从 HugeGraph 读取图数据并运行图学习模型。 - [hugegraph-python-client](https://github.com/apache/hugegraph-ai/tree/main/hugegraph-python-client)：管理 Schema、图数据和 Gremlin 查询的 Python SDK。 @@ -88,6 +89,7 @@ cd hugegraph-ml/src ## 后续阅读 +- [HugeGraph-MCP](./hugegraph-mcp.md) - [HugeGraph-LLM](./hugegraph-llm.md) - [HugeGraph-LLM 使用流程](./quick_start.md) - [配置参考](./config-reference.md) diff --git a/content/cn/docs/quickstart/hugegraph-ai/hugegraph-mcp.md b/content/cn/docs/quickstart/hugegraph-ai/hugegraph-mcp.md new file mode 100644 index 000000000..4bab72b04 --- /dev/null +++ b/content/cn/docs/quickstart/hugegraph-ai/hugegraph-mcp.md @@ -0,0 +1,219 @@ +--- +title: "HugeGraph-MCP" +linkTitle: "HugeGraph-MCP" +weight: 7 +--- + +`hugegraph-mcp` 通过 Model Context Protocol（MCP）向 AI 客户端提供 HugeGraph 工具， +包括 Schema 检查、结构化图查询、受控写入，以及可选的自然语言查询生成和图数据抽取。 +服务使用 STDIO 传输，由 MCP 客户端启动本地进程；它不是 HugeGraph Server，也不提供独立的 HTTP MCP 端口。 + +普通图查询直接访问 HugeGraph Server。自然语言生成、抽取和向量刷新还需要 +[HugeGraph-LLM](./hugegraph-llm.md) 服务，模型凭据配置在该服务中。 + +## 环境要求 + +- Python 3.10 或更高版本；单独运行 HugeGraph-LLM 时，请同时满足该模块的 Python 版本要求。 +- [uv](https://docs.astral.sh/uv/getting-started/installation/) 和支持 STDIO 的 MCP 客户端。 +- 可从 MCP 进程访问的 HugeGraph Server 1.7.0 或更高版本。默认图路径为 `DEFAULT/hugegraph`，使用 graphspace API。 +- 已创建的图及具备相应权限的账号。服务端认证配置见[认证与授权](../../config/config-authentication.md)。 + +## 安装与连接 + +以下示例固定使用已发布的 `hugegraph-mcp==1.7.1`，不需要克隆代码仓库。 +将地址、图路径和凭据替换为实际部署值。先使用只读模式验证连接，再按需要开放受支持的写入。 + +支持 `mcpServers` JSON 配置的客户端可添加： + +```json +{ + "mcpServers": { + "hugegraph": { + "command": "uvx", + "args": ["hugegraph-mcp@1.7.1"], + "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" + } + } + } +} +``` + +不同客户端的配置文件位置和结构可能不同，请按客户端说明填写相同的启动命令、参数和环境变量。 +如果客户端找不到 `uvx`，将 `command` 改为本机 `uvx` 的绝对路径。修改配置后重启 MCP 进程。 + +也可在已配置上述环境变量的终端中启动： + +```bash +uvx hugegraph-mcp@1.7.1 +``` + +进程启动后等待 MCP 客户端通过标准输入发送协议消息，不会打开网页。 +stdout 用于 MCP JSON-RPC，不要将额外的 shell 输出写入该通道。 + +### 验证连接 + +通过客户端列出工具，再调用 `inspect_graph_tool`。以下 JSON 是 MCP `tools/call` 的参数内容， +不是向 HugeGraph REST API 直接发送的请求。 + +```json +{ + "name": "inspect_graph_tool", + "arguments": {"include_raw_schema": true} +} +``` + +确认返回 `ok=true`、`data.hugegraph_server_status="available"`。 +从 Schema 中选择已有的顶点标签，将下例中的 `person` 替换为该标签： + +```json +{ + "name": "query_graph_data_tool", + "arguments": { + "target": "vertex", + "operation": "page", + "label": "person", + "limit": 5 + } +} +``` + +该工具属于默认的 16 工具集。分页时使用响应中的 `next_page` 作为下一次调用的 `page`， +并保留相同的查询条件。结果为空不一定表示连接失败，请同时检查图路径、标签和已有数据。 + +## 工具集与版本 + +工具集选择的是同一个包提供的工具分组，不是软件包版本、HugeGraph Server 版本或 MCP 协议版本。 +`1.7.1` 的配置名称如下： + +| `HUGEGRAPH_MCP_TOOLSET` | 工具数量 | 用途 | +|---|---|---| +| 未设置，或 `v2_core` | 16 | 默认工具集，包含结构化查询和持久化写入计划工具 | +| `v1` | 10 | 兼容工具集，保留较早的工具入口 | + +其他任何值（包括 `v2`、`core`、`legacy` 或空字符串），在 1.7.1 中均会记录错误日志并回退到包含 10 个工具的 `v1` 兼容工具集。 +两种工具集的 `mcp_tool_contract_version` 均为 `2.0`，该字段表示工具契约，不表示包版本。 + +### 新名称迁移（已合并至 apache/hugegraph-ai main #382，未发布） + +该改动将默认工具集改名为 `core`，兼容工具集改名为 `legacy`。 +该改动已合并至 apache/hugegraph-ai main 分支（#382），但尚未发布至 PyPI，**不适用于上面的 1.7.1 安装命令**。 +新版本号和升级命令应在正式发布后更新。 + +- `v2_core` 对应 `core`，`v1` 对应 `legacy`；旧值作为兼容别名保留，并输出迁移警告。 +- 检查接口统一返回 `core` 或 `legacy`，比较 `data.toolset` 或 `meta.toolset` 的客户端需要同步调整。 +- 不设置变量时使用 `core`；空白或未知值会阻止启动，不再自动回退到兼容工具集。 +- 工具集在启动时确定，修改配置后需要重启；选择兼容工具集不会绕过权限检查。 + +## 工具能力 + +工具已注册不代表所有操作都可以执行。当前能力范围如下，实际工具参数以客户端的工具 Schema 为准。 + +| 功能 | 工具 | 使用范围 | +|---|---|---| +| 检查与设计 | `inspect_graph_tool`、`inspect_schema_tool`、`design_schema_tool` | 查看连接、Schema 和设计指导 | +| 结构化读取 | `query_graph_data_tool` | 按 ID、ID 列表、分页或条件读取顶点和边 | +| Schema 创建 | `apply_schema_tool` | 校验和预览；默认工具集支持确认单个属性键、顶点标签或边标签创建 | +| 写入计划 | `confirm_write_tool`、`get_write_status_tool`、`reconcile_write_tool` | 确认、查询及协调持久化计划 | +| 图导入 | `import_graph_data_tool` | `extract` 调用 AI；`ingest` 仅预览，`table` 当前禁用 | +| 图删除 | `delete_graph_data_tool` | 精确边删除可确认；顶点删除仅预览 | +| 属性变更 | `mutate_graph_properties_tool` | 仅预览，确认当前禁用 | +| AI 生成与抽取 | `generate_gremlin_tool`、`extract_graph_data_tool` | 生成查询或抽取候选图数据，不自动执行生成的查询 | +| 向量刷新 | `refresh_vid_embeddings_tool` | 需要 AI、管理模式、允许写入以及显式确认；当前源码的服务侧门禁见下文 | +| 原始 Gremlin | `execute_gremlin_read_tool`、`execute_gremlin_write_tool` | 当前均返回 `FEATURE_DISABLED`；管理模式不能绕过 | + +兼容工具集不包含 `inspect_schema_tool`、`query_graph_data_tool`、`mutate_graph_properties_tool`， +以及三个写入计划工具。原始 Gremlin 执行也不会因切换到兼容工具集而开放。 + +### 受控写入 + +需要写入时，将 `HUGEGRAPH_MCP_READONLY` 设为 `false`，并使用有相应权限的 HugeGraph 账号。 +对于可确认的操作，先执行 dry-run，检查具体目标、变更内容和警告，再使用返回的 `plan_id` 确认： + +```json +{ + "name": "confirm_write_tool", + "arguments": {"plan_id": ""} +} +``` + +用 `get_write_status_tool(plan_id)` 查询持久化结果。`APPLIED` 表示全部操作已确认成功； +`PARTIAL` 或 `UNKNOWN` 表示部分完成或结果尚不能确定，应先查询和协调状态，不要重新生成计划盲目重试。 +已完成的同一计划再次确认会返回记录的结果，不会重复写入。 + +内置 SQLite 状态存储要求单个可写 MCP 实例，并需要可持久保存的状态目录。 +多个客户端各自启动进程时，应先保持只读；多实例写入需要另行设计共享事务存储。 +预览返回 `confirmable=false` 的操作不能通过关闭只读或开启管理模式强制执行。 + +## 配置 + +下表对应已发布的 `1.7.1`。MCP 图账号与 HugeGraph-LLM 的 API token 是两种不同的凭据。 + +| 环境变量 | 默认值 | 说明 | +|---|---|---| +| `HUGEGRAPH_URL` | `http://127.0.0.1:8080` | MCP 进程访问的 HugeGraph 地址 | +| `HUGEGRAPH_GRAPH_PATH` | `DEFAULT/hugegraph` | `GRAPH_SPACE/GRAPH_NAME` | +| `HUGEGRAPH_GRAPHSPACE` | 未设置 | 覆盖 `HUGEGRAPH_GRAPH_PATH` 中的 graphspace | +| `HUGEGRAPH_GRAPH` | 未设置 | 覆盖 `HUGEGRAPH_GRAPH_PATH` 中的图名 | +| `HUGEGRAPH_USER` | `admin` | HugeGraph 用户名 | +| `HUGEGRAPH_PASSWORD` | 空 | HugeGraph 密码 | +| `HUGEGRAPH_MCP_TOOLSET` | `v2_core` | 该版本支持 `v2_core`、`v1` | +| `HUGEGRAPH_MCP_READONLY` | `true` | 禁止受控写入 | +| `HUGEGRAPH_MCP_ALLOW_AI` | `false` | 允许调用 HugeGraph-LLM | +| `HUGEGRAPH_MCP_ADMIN_MODE` | `false` | 开放符合条件的管理操作 | +| `HUGEGRAPH_AI_URL` | `http://127.0.0.1:8001` | HugeGraph-LLM 服务地址 | +| `HUGEGRAPH_AI_TOKEN` | 未设置 | HugeGraph-LLM bearer token | +| `HUGEGRAPH_AI_GRAPH_URL` | 未设置 | 不用于改变 AI 服务目标；当前源码已忽略此项 | +| `HUGEGRAPH_AI_TIMEOUT_SECONDS` | `30` | AI HTTP 请求超时，单位为秒 | +| `HUGEGRAPH_MCP_STATE_DIR` | XDG 状态目录或 `~/.local/state/hugegraph-mcp` | 写入计划与回执的持久化目录 | + +### 可选 AI 功能 + +先按 [HugeGraph-LLM 指南](./hugegraph-llm.md) 配置并启动模型服务，再在 MCP 客户端的 `env` 中加入： + +```json +{ + "HUGEGRAPH_MCP_ALLOW_AI": "true", + "HUGEGRAPH_AI_URL": "http://127.0.0.1:8001", + "HUGEGRAPH_AI_TOKEN": "your-ai-service-token" +} +``` + +这段内容应合并到前面的 `env` 对象中。生成和抽取可保持只读；向量刷新要求满足以下条件： +- 客户端配置：`HUGEGRAPH_MCP_READONLY=false`、`HUGEGRAPH_MCP_ADMIN_MODE=true`，且调用时需传入 `confirm=true`。 +- 服务端配置（HugeGraph-LLM）：需设置 `ENABLE_LOGIN=true` 与 `HUGEGRAPH_LLM_ENABLE_THIN_WRITES=true`，配置强 `USER_TOKEN`， + 并通过 MCP 的 `HUGEGRAPH_AI_TOKEN` 传递有效认证。若服务端未开启写入门禁，刷新请求将被拒绝并返回 `FEATURE_DISABLED`（"Legacy Thin API writes are disabled"）。 + +如果 MCP 在宿主机运行，而 AI 在容器中运行，二者访问 HugeGraph 的地址可能不同。 +应在 AI 服务侧配置 `GRAPH_URL` 为容器可访问的地址，例如 `http://server:8080`，并设置 `GRAPH_NAME`、`GRAPH_SPACE` +与 MCP 目标一致；不要让容器通过 `127.0.0.1` 访问宿主机上的图服务。修改 MCP 地址不会修改 AI 服务目标。 + +**能力校验协议（已合并至 main #382，未正式发布）**： +在 [apache/hugegraph-ai#382](https://github.com/apache/hugegraph-ai/pull/382) 中，MCP 增加了双向校验协议，要求 +`GET /vid-embeddings/refresh-capabilities` 返回 `protocol_version=1`，并在刷新前传递预期图名与 graphspace 由服务端校验； +缺少该协议的服务将被拒绝。此协议属于后续版本规划，不适用于上述已发布的 `1.7.1` 安装示例。 + +## 常见问题 + +- **客户端启动后没有工具**：检查 `uvx` 路径、Python 版本和进程 stderr；终端进程等待协议输入是正常行为。 +- **找不到结构化查询工具**：检查是否选择了兼容工具集。`1.7.1` 使用 `v2_core`，也可直接不设置工具集变量。 +- **返回 `FEATURE_DISABLED`**：先检查能力表、只读、AI 和管理开关；部分操作是后端能力限制，不能仅靠修改配置开放。 +- **AI 调用失败**：检查服务地址、token、容器网络和 AI 日志。MCP 返回的服务不可用错误不一定意味着模型已下线。 +- **向量接口返回 400 或 429**：检查提供商的单次输入条数及请求频率限制。每批最大条数和并发请求数是不同限制； + 应在 HugeGraph-LLM 的向量适配与索引构建路径中处理，而不是更换 MCP 工具集。 + +工具响应中的 `ok=false` 表示失败，请同时检查 `error.type`、`error.retryable` 和 `warnings`， +不要只根据 MCP 连接成功或 HTTP 状态判断业务操作成功。 + +## 后续阅读 + +- [HugeGraph-LLM](./hugegraph-llm.md) +- [HugeGraph-MCP 源码与 README](https://github.com/apache/hugegraph-ai/tree/main/hugegraph-mcp) +- [集成验证](https://github.com/apache/hugegraph-ai/blob/main/hugegraph-mcp/docs/integration.md) +- [PyPI 发行包](https://pypi.org/project/hugegraph-mcp/) + +仓库 `main` 的文档随源码更新。使用固定发行包时，应先核对对应版本；本文安装示例固定为 `1.7.1`。 diff --git a/content/en/docs/quickstart/hugegraph-ai/_index.md b/content/en/docs/quickstart/hugegraph-ai/_index.md index fc2cb8d81..6eba8f53d 100644 --- a/content/en/docs/quickstart/hugegraph-ai/_index.md +++ b/content/en/docs/quickstart/hugegraph-ai/_index.md @@ -10,6 +10,7 @@ weight: 3 ## Modules +- [hugegraph-mcp](./hugegraph-mcp.md): graph queries, schema tools, and controlled writes for AI clients through MCP. - [hugegraph-llm](https://github.com/apache/hugegraph-ai/tree/main/hugegraph-llm): knowledge graph construction, GraphRAG, and natural-language graph queries. - [hugegraph-ml](https://github.com/apache/hugegraph-ai/tree/main/hugegraph-ml): reads graph data from HugeGraph and runs graph learning models. - [hugegraph-python-client](https://github.com/apache/hugegraph-ai/tree/main/hugegraph-python-client): a Python SDK for managing schemas and graph data and running Gremlin queries. @@ -88,6 +89,7 @@ Example scripts are under `hugegraph-ml/src/hugegraph_ml/examples/`. ## Next Steps +- [HugeGraph-MCP](./hugegraph-mcp.md) - [HugeGraph-LLM](./hugegraph-llm.md) - [HugeGraph-LLM workflow](./quick_start.md) - [Configuration reference](./config-reference.md) diff --git a/content/en/docs/quickstart/hugegraph-ai/hugegraph-mcp.md b/content/en/docs/quickstart/hugegraph-ai/hugegraph-mcp.md new file mode 100644 index 000000000..67504bb98 --- /dev/null +++ b/content/en/docs/quickstart/hugegraph-ai/hugegraph-mcp.md @@ -0,0 +1,227 @@ +--- +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": ["hugegraph-mcp@1.7.1"], + "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 hugegraph-mcp@1.7.1 +``` + +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, Not Yet Released) + +The default toolset is renamed 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": ""} +} +``` + +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: +- Client settings: `HUGEGRAPH_MCP_READONLY=false`, `HUGEGRAPH_MCP_ADMIN_MODE=true`, and `confirm=true` in the tool call. +- Service settings (HugeGraph-LLM): `ENABLE_LOGIN=true`, `HUGEGRAPH_LLM_ENABLE_THIN_WRITES=true`, a configured `USER_TOKEN`, + and valid authentication passed via MCP's `HUGEGRAPH_AI_TOKEN`. Without these service-side gates, refresh requests are rejected + with `FEATURE_DISABLED` ("Legacy Thin API writes are disabled"). + +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. + +**Capability check protocol in #382 (merged to main, not yet in a published release)**: +The capability check protocol merged in [apache/hugegraph-ai#382](https://github.com/apache/hugegraph-ai/pull/382) requires +`GET /vid-embeddings/refresh-capabilities` to return `protocol_version=1`, and sends the expected graph and graphspace +for service-side validation before refreshing. Services lacking this protocol are rejected. This protocol applies to future +releases and is not required for the published `1.7.1` package. + +## Troubleshooting + +- **No tools after client startup**: check the `uvx` path, Python version, and process stderr. Waiting for protocol input in a terminal is normal. +- **Structured query tool missing**: check whether the compatibility toolset was selected. For `1.7.1`, use `v2_core` or leave the variable unset. +- **`FEATURE_DISABLED` response**: check the capability table and read-only, AI, and admin settings. + Some operations are disabled because of backend capability limits and cannot be enabled through configuration alone. +- **AI calls fail**: check the service address, token, container networking, and AI logs. An unavailable-service error does not necessarily mean a model was + retired. +- **Embedding calls return 400 or 429**: check the provider's input-count and request-rate limits. + Batch size and concurrent request count are different limits; handle them in HugeGraph-LLM's embedding and index-building paths, not by changing MCP toolsets. + +An `ok=false` tool response indicates failure. Inspect `error.type`, `error.retryable`, and `warnings`; +an established MCP connection or successful HTTP status alone does not prove that a business operation succeeded. + +## Next Steps + +- [HugeGraph-LLM](./hugegraph-llm.md) +- [HugeGraph-MCP source and README](https://github.com/apache/hugegraph-ai/tree/main/hugegraph-mcp) +- [Integration checks](https://github.com/apache/hugegraph-ai/blob/main/hugegraph-mcp/docs/integration.md) +- [PyPI package](https://pypi.org/project/hugegraph-mcp/) + +Documentation on the repository's `main` branch follows source changes. Check version applicability when using a pinned package; +the installation examples on this page use `1.7.1`. diff --git a/data/docs_nav.json b/data/docs_nav.json index abb3089a6..3db307fcd 100644 --- a/data/docs_nav.json +++ b/data/docs_nav.json @@ -109,6 +109,9 @@ { "page": "/docs/quickstart/hugegraph-ai/hugegraph-llm" }, + { + "page": "/docs/quickstart/hugegraph-ai/hugegraph-mcp" + }, { "page": "/docs/quickstart/hugegraph-ai/hugegraph-ml" }, @@ -523,6 +526,11 @@ "url": "/docs/quickstart/hugegraph-ai/hugegraph-llm/", "children": [] }, + { + "page": "/docs/quickstart/hugegraph-ai/hugegraph-mcp", + "url": "/docs/quickstart/hugegraph-ai/hugegraph-mcp/", + "children": [] + }, { "page": "/docs/quickstart/hugegraph-ai/hugegraph-ml", "url": "/docs/quickstart/hugegraph-ai/hugegraph-ml/", @@ -1035,6 +1043,11 @@ "/docs/quickstart/hugegraph-ai/", "/docs/quickstart/hugegraph-ai/hugegraph-llm/" ], + "/docs/quickstart/hugegraph-ai/hugegraph-mcp/": [ + "@group/components", + "/docs/quickstart/hugegraph-ai/", + "/docs/quickstart/hugegraph-ai/hugegraph-mcp/" + ], "/docs/quickstart/hugegraph-ai/hugegraph-ml/": [ "@group/components", "/docs/quickstart/hugegraph-ai/", @@ -1417,6 +1430,7 @@ "/docs/quickstart/hugegraph-ai/": [ "/docs/quickstart/hugegraph-ai/quick_start", "/docs/quickstart/hugegraph-ai/hugegraph-llm", + "/docs/quickstart/hugegraph-ai/hugegraph-mcp", "/docs/quickstart/hugegraph-ai/hugegraph-ml", "/docs/quickstart/hugegraph-ai/config-reference", "/docs/quickstart/hugegraph-ai/rest-api" diff --git a/data/version_routes.json b/data/version_routes.json index 46ae1f6fa..ababc7095 100644 --- a/data/version_routes.json +++ b/data/version_routes.json @@ -687,6 +687,13 @@ "1.3": null, "1.0": null }, + "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 + }, "cn:quickstart/hugegraph-ai/hugegraph-ml": { "latest": "cn/docs/quickstart/hugegraph-ai/hugegraph-ml/", "1.7": "cn/docs/quickstart/hugegraph-ai/hugegraph-ml/", @@ -1429,6 +1436,13 @@ "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 + }, "en:quickstart/hugegraph-ai/hugegraph-ml": { "latest": "docs/quickstart/hugegraph-ai/hugegraph-ml/", "1.7": "docs/quickstart/hugegraph-ai/hugegraph-ml/", diff --git a/scripts/versioning.py b/scripts/versioning.py index 9fe77880a..b7fd0b156 100644 --- a/scripts/versioning.py +++ b/scripts/versioning.py @@ -133,29 +133,29 @@ DOCS_NAV_EXPECTED_STATS = { "latest": { "groups": 5, - "pages": 95, + "pages": 96, "removed": 4, "scopedLinks": 0, - "treeSha256": "b33f771f77fc376121902fee37d66235d2920a450320620400320925f985c86a", + "treeSha256": "8b2b1f270a27b909b673a30d186c46a6a0feccab4c4a980d9b8127686346be2b", }, "1.7": { "groups": 5, "pages": 85, - "removed": 8, + "removed": 9, "scopedLinks": 10, "treeSha256": "c87538b82b0e3506eef59417411686ddc188e0f33d0e3a1cda687de8d6f88747", }, "1.5": { "groups": 5, "pages": 77, - "removed": 16, + "removed": 17, "scopedLinks": 10, "treeSha256": "ac29ab8f0e7020496a3a1afe480687043d751e32c93ffb848e2210e3500cd483", }, "1.3": { "groups": 5, "pages": 68, - "removed": 25, + "removed": 26, "scopedLinks": 10, "treeSha256": "e8c9b0a64dac6dd3e47827ec5072697eb7d3ed79659e0b5c4a9c5df8e1408d38", },