Metadata-Version: 2.5
Name: hugegraph-mcp
Version: 1.7.1
Summary: FastMCP server that exposes HugeGraph schema & Gremlin tools over MCP/STDIO
Project-URL: Homepage, https://hugegraph.apache.org/
Project-URL: Repository, https://github.com/apache/hugegraph-ai
Project-URL: Issues, https://github.com/apache/hugegraph-ai/issues
Author-email: Apache HugeGraph Contributors <dev@hugegraph.apache.org>
License: Apache-2.0
Keywords: gremlin,hugegraph,mcp,model-context-protocol
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: fastmcp==3.2.4
Requires-Dist: hugegraph-python<2,>=1.7.1
Description-Content-Type: text/markdown

# HugeGraph MCP

[中文文档](README.zh-CN.md)

HugeGraph MCP is a safe, controlled Model Context Protocol adapter for HugeGraph Server. It exposes stable structured tools, centralizes configuration and permission checks, and persists immutable write plans and outcomes.

**Requires HugeGraph Server >= 1.7.0.** The default graph path is `DEFAULT/hugegraph` and uses graphspace-scoped APIs unavailable in older releases.

## Quick Start

Installing a published package does not require cloning this repository. The
commands below target `1.7.1` on PyPI; until it is published, use the
[developer setup](#developer-notes). See the [release workflow](docs/releasing.md).

Install [uv](https://docs.astral.sh/uv/getting-started/installation/), then start the server in read-only mode:

```bash
export HUGEGRAPH_URL=http://hugegraph.example.com:8080
export HUGEGRAPH_GRAPH_PATH=DEFAULT/hugegraph
export HUGEGRAPH_USER=admin
export HUGEGRAPH_PASSWORD=admin
export HUGEGRAPH_MCP_READONLY=true

uvx hugegraph-mcp@1.7.1
```

The process speaks MCP JSON-RPC on stdout. Keep `HUGEGRAPH_MCP_READONLY=true` unless controlled writes are required. The default toolset is `v2_core`; set `HUGEGRAPH_MCP_TOOLSET=v1` before startup only for the legacy 10-tool contract.

For MCP clients that accept JSON server configuration:

```json
{
  "mcpServers": {
    "hugegraph": {
      "command": "uvx",
      "args": ["hugegraph-mcp@1.7.1"],
      "env": {
        "HUGEGRAPH_URL": "http://hugegraph.example.com:8080",
        "HUGEGRAPH_GRAPH_PATH": "DEFAULT/hugegraph",
        "HUGEGRAPH_USER": "admin",
        "HUGEGRAPH_PASSWORD": "admin",
        "HUGEGRAPH_MCP_READONLY": "true"
      }
    }
  }
}
```

## Developer Notes

To try both packages from the same checkout, run from the repository root:

```bash
uvx --no-config --no-cache --with ./hugegraph-python-client --from ./hugegraph-mcp hugegraph-mcp
```

From the root of the PR checkout, install uv, then create an isolated environment and install both packages from this branch:

```bash
uv venv --python 3.10 .venv-mcp
uv --no-config pip install --python .venv-mcp -e ./hugegraph-python-client -e ./hugegraph-mcp
```

Set the HugeGraph URL and credentials shown above for your server, then start on macOS/Linux:

```bash
.venv-mcp/bin/python -m hugegraph_mcp.server
```

On Windows PowerShell (set variables with `$env:NAME="value"`):

```powershell
.\.venv-mcp\Scripts\python.exe -m hugegraph_mcp.server
```

Both packages load from this checkout; no author-specific path or pre-existing environment is required. `--no-config` keeps root LLM dependency constraints out of the standalone MCP environment.

For an MCP client, set `command` to the absolute path of this Python interpreter in your own checkout and `args` to `["-m", "hugegraph_mcp.server"]`.

After connecting, call `inspect_graph_tool(include_raw_schema=true)` and check that `hugegraph_server_status="available"`. Then run a bounded structured query, replacing `person` with an existing label:

```json
{"name":"query_graph_data_tool","arguments":{"target":"vertex","operation":"page","label":"person","limit":5}}
```

[Architecture and roadmap](docs/architecture.md) · [Integration checklist](docs/integration.md) · [Release order](docs/releasing.md)

Structured queries cap the requested page size at `HUGEGRAPH_MCP_MAX_RESULT_ITEMS` and the tool maximum of 500. ID batches exceeding the effective limit are rejected before querying. Responses exceeding the item or byte limit are rejected without truncation or a continuation cursor; these checks do not bound backend execution or transport memory.

## Public Tool Surface

The default `v2_core` contract registers 16 tools. The `v1` compatibility contract registers 10 tools and omits the six v2 additions.

| Tool | Contract | Description |
|------|----------|-------------|
| `inspect_graph_tool` | v1, v2 | Inspect connection, schema summary, read-only state, and tool contract |
| `generate_gremlin_tool` | v1, v2 | Generate Gremlin; execution is disabled until the hard-budget contract is verified |
| `execute_gremlin_read_tool` | v1, v2 | Registered for compatibility; public raw execution currently returns `FEATURE_DISABLED` |
| `extract_graph_data_tool` | v1, v2 | Extract candidate graph data without writing |
| `design_schema_tool` | v1, v2 | Produce schema design guidance |
| `apply_schema_tool` | v1, v2 | Validate or preview one schema create; v2 supports confirmed apply |
| `import_graph_data_tool` | v1, v2 | Validate and preview structured vertex/edge creates; confirmation currently returns `FEATURE_DISABLED` |
| `delete_graph_data_tool` | v1, v2 | Preview exact deletion; confirmed edge deletion is supported |
| `refresh_vid_embeddings_tool` | v1, v2 | Admin write tool, disabled unless admin mode and writes are enabled |
| `execute_gremlin_write_tool` | v1, v2 | Registered for compatibility; public raw execution currently returns `FEATURE_DISABLED` |
| `inspect_schema_tool` | v2 | Inspect and filter schema objects and relations |
| `query_graph_data_tool` | v2 | Perform typed, bounded vertex and edge reads |
| `mutate_graph_properties_tool` | v2 | Preview property changes; confirmation is disabled without atomic CAS |
| `confirm_write_tool` | v2 | Confirm one persisted plan by `plan_id` |
| `get_write_status_tool` | v2 | Read the durable plan and operation outcome by `plan_id` |
| `reconcile_write_tool` | v2 | Reconcile `UNKNOWN` or `PARTIAL` outcomes by `plan_id` using read-only checks |

Invalid `HUGEGRAPH_MCP_TOOLSET` values fail closed to `v1`. Tool registration is fixed at process startup, so restart the server after changing the toolset.

## Unified Response Envelope

High-level tools return:

```json
{
  "ok": true,
  "data": {},
  "error": null,
  "warnings": [],
  "next_actions": [],
  "meta": {
    "request_id": "req-...",
    "graph": "hugegraph",
    "graphspace": "DEFAULT",
    "readonly": true,
    "duration_ms": 12.3
  }
}
```

Failures set `ok=false`; `error.type` is a stable machine-readable code and `error.retryable` must be observed.

## Write Safety Contract

Canonical writes use only a server-issued `plan_id`:

```text
structured dry-run
  -> review concrete targets, warnings, and mutation summary
  -> receive immutable persisted plan_id
  -> confirm_write_tool(plan_id)
  -> get_write_status_tool(plan_id)
  -> if required, reconcile_write_tool(plan_id)
```

The confirmation call never accepts the original payload. The persisted plan is the sole execution authority. Each operation records a durable receipt, and reusing a completed `plan_id` returns its recorded outcome rather than applying the write again.

`APPLIED` means every operation is proven applied. `PARTIAL` means at least one operation was applied and the workflow did not completely apply. `UNKNOWN` means the service cannot prove whether an operation committed, so callers must query status and reconcile; they must not blindly repeat the write.

The old `plan_hash`, `nonce`, and `expires_at` locator remains on legacy write entry points for the single compatibility release immediately following introduction of the plan-ID contract. All three fields are required together, cannot be mixed with `plan_id`, and produce a `LEGACY_CONFIRMATION_DEPRECATED` warning. New integrations must use `confirm_write_tool(plan_id)`.

The bundled SQLite plan store is safe for a single write-capable MCP instance. Configure a shared transactional store before deploying multiple write instances; the current package fails closed when `HUGEGRAPH_MCP_WRITE_INSTANCE_COUNT` is greater than one with the SQLite backend.

### Operation Boundaries

- A confirmable schema plan contains exactly one `create_property_key`, `create_vertex_label`, or `create_edge_label` operation. Success is reported as `APPLIED`. Index create, append/eliminate, and drop remain outside the apply scope.
- Graph import is always preview-only because atomic create-if-absent capability has not been verified for HugeGraph 1.7.0. Its preview sets `confirmable=false` and `preview_only=true`, issues no `plan_id`, and confirmation returns `FEATURE_DISABLED` without writing.
- Property mutation is preview-only because HugeGraph 1.7.0 does not expose an atomic compare-and-set property update. Confirmation returns `FEATURE_DISABLED`.
- Isolated vertex deletion is preview-only. Docker concurrency testing proved that HugeGraph 1.7.0 cannot atomically guarantee “delete only if no incident edge”; confirmation returns `FEATURE_DISABLED`. Delete incident edges explicitly, then use an independently controlled maintenance path for the vertex.
- Exact edge deletion remains confirmable because the plan binds the concrete edge ID.

Schema and graph-data dry-runs reject more than 200 operations or payloads larger than 1 MiB before returning a usable preview or plan.

### Raw Gremlin Boundary

Every public raw Gremlin execution path is disabled, including `execute_gremlin_read_tool`, `execute_gremlin_write_tool`, and `generate_gremlin_tool(execute=true)`. Admin mode does not override this gate. Raw execution can be opened only after the deployment proves server evaluation and wait timeouts, a server-side result-item cap, a client streaming byte cap, and a read-only principal. Post-materialization item or byte checks are output guards, not hard resource budgets.

Structured reads and `generate_gremlin_tool(execute=false)` remain available.

## Configuration

| Variable | Default | Description |
|----------|---------|-------------|
| `HUGEGRAPH_URL` | `http://127.0.0.1:8080` | HugeGraph Server URL |
| `HUGEGRAPH_GRAPH_PATH` | `DEFAULT/hugegraph` | `GRAPH_SPACE/GRAPH_NAME` |
| `HUGEGRAPH_GRAPHSPACE`, `HUGEGRAPH_GRAPH` | unset | Explicit values that override `HUGEGRAPH_GRAPH_PATH` |
| `HUGEGRAPH_USER` | `admin` | HugeGraph username |
| `HUGEGRAPH_PASSWORD` | empty | HugeGraph password |
| `HUGEGRAPH_MCP_TOOLSET` | `v2_core` | `v1` or `v2_core`; invalid values fall back to `v1` |
| `HUGEGRAPH_MCP_READONLY` | `true` | Disable all controlled writes when true |
| `HUGEGRAPH_MCP_ALLOW_AI` | `false` | Allow HugeGraph-AI calls |
| `HUGEGRAPH_MCP_ADMIN_MODE` | `false` | Enable eligible admin/debug tools |
| `HUGEGRAPH_AI_URL` | `http://127.0.0.1:8001` | HugeGraph-AI URL |
| `HUGEGRAPH_AI_TOKEN` | unset | Optional HugeGraph-AI bearer token |
| `HUGEGRAPH_AI_GRAPH_URL` | unset | Graph URL presented to HugeGraph-AI; falls back to `HUGEGRAPH_URL` |
| `HUGEGRAPH_CONNECT_TIMEOUT_SECONDS` | `0.5` | HugeGraph connection timeout; range `0.001..86400` |
| `HUGEGRAPH_READ_TIMEOUT_SECONDS` | `15` | Structured HugeGraph read timeout; range `0.001..86400` |
| `HUGEGRAPH_WRITE_TIMEOUT_SECONDS` | `15` | HugeGraph data and schema write timeout; range `0.001..86400` |
| `HUGEGRAPH_AI_TIMEOUT_SECONDS` | `30` | HugeGraph-AI HTTP timeout; range `1..86400` |
| `HUGEGRAPH_MCP_TIMEOUT_SECONDS` | `30` | Deprecated fallback for AI timeout |
| `HUGEGRAPH_MCP_MAX_RESULT_ITEMS` | `100` | Post-materialization output item guard; range `1..1000000` |
| `HUGEGRAPH_MCP_MAX_RESULT_BYTES` | `1048576` | Post-materialization output byte guard; range `1..1073741824` |
| `HUGEGRAPH_MCP_PLAN_STORE` | `sqlite` | Durable plan-store backend; only `sqlite` is currently supported |
| `HUGEGRAPH_MCP_WRITE_INSTANCE_COUNT` | `1` | Declared count of write-capable MCP instances; SQLite requires exactly one |
| `HUGEGRAPH_MCP_STATE_DIR` | `$XDG_STATE_HOME/hugegraph-mcp` or `~/.local/state/hugegraph-mcp` | Directory containing the plan, operation, and receipt database |

Boolean values accept `1/true/yes/on` and `0/false/no/off`, case-insensitively. Invalid values use safe defaults. Invalid, non-finite, or out-of-range numeric values use the documented defaults.

Recommended defaults are `HUGEGRAPH_MCP_READONLY=true`, `HUGEGRAPH_MCP_ALLOW_AI=false`, and `HUGEGRAPH_MCP_ADMIN_MODE=false`.

## License

Apache License 2.0
