Skip to content

feat(mcp): add MCP v2 resources/prompts, streamable-http, bounded traversal, VID search, and plan lifecycle tools - #436

Open
UIengF wants to merge 8 commits into
apache:mainfrom
UIengF:feat/mcp-v2
Open

UIengF wants to merge 8 commits into
apache:mainfrom
UIengF:feat/mcp-v2

Conversation

@UIengF

@UIengF UIengF commented Nov 15, 2026

Copy link
Copy Markdown
Contributor

Summary

This PR introduces MCP v2 capabilities across hugegraph-mcp, hugegraph-llm, and hugegraph-python-client, adding native MCP Resources/Prompts, streamable-http transport, durable PostgreSQL plan storage, bounded graph traversal, semantic VID search, task/graph observability, and write-plan lifecycle management, together with multi-round security and reliability hardening.

Key Changes

1. hugegraph-mcp — Protocol, Transport & Persistence

  • Native MCP Resources & Prompts (hugegraph_mcp/resources.py, hugegraph_mcp/prompts.py):
    • Added 4 MCP Resources (schema, graph summary, VID embedding index status, and actor-scoped write plan details) with resource subscription and invalidation notifications.
    • Added 6 MCP Prompts (explore_graph, design_graph_schema, review_write_plan, investigate_write_status, ingest_text_to_graph, optimize_gremlin_query).
  • Streamable HTTP & Actor Context (auth_middleware.py, runtime.py, server.py):
    • Added streamable-http / http / sse transport support with bearer/actor extraction, admin scope gating, and per-session cleanup.
  • PostgreSQL Plan Store & Outbox Relay (stores/postgres.py, stores/base.py, plan_store.py):
    • Added PostgresPlanStore (and PostgresSyncPlanStore bridge) with outbox event relay alongside the default SQLite store.

2. hugegraph-mcp — New core Tools (24 tools total in core, 10 in legacy)

  • Bounded Traversal & Observability:
    • traverse_graph_tool (neighbors, k_out, shortest_path, paths with strict bounds).
    • get_task_status_tool, list_tasks_tool, cancel_task_tool (admin-gated async task inspection & cancellation).
    • list_graphs_tool (admin-gated visible graph listing in the configured graphspace).
  • Write-Plan Lifecycle & Schema Append:
    • list_write_plans_tool (actor-owned plans ordered by most recent) and cancel_write_plan_tool (cancel ISSUED plans to EXPIRED, revoking legacy confirmation tokens).
    • WritePlan support for append_vertex_label and append_edge_label in apply_schema_tool / confirm_write_tool.
    • Cache invalidation on reconcile_write_tool and degraded-server reporting in read_summary_resource.
  • Semantic VID Search:
    • search_vid_embeddings_tool calling HugeGraph-AI /v1/vid-embeddings/search (requires HUGEGRAPH_MCP_ALLOW_AI=true).

3. hugegraph-python-client & hugegraph-llm

  • Streaming Byte Cap & Trickle Deadline (huge_requests.py, exceptions.py):
    • Enforced streaming response byte limits and end-to-end request deadlines across hugegraph-python-client to prevent unbounded response buffering.
  • HugeGraph-AI VID Search & Index Reliability (thin_api.py, build_semantic_index.py, milvus_vector_store.py, qdrant_vector_store.py):
    • Added POST /v1/vid-embeddings/search with target (graphspace, graph) validation, read-only index loading, and index generation/refresh metadata (index_generation, refreshed_at).

4. Documentation

  • Updated hugegraph-mcp/README.md, hugegraph-mcp/README.zh-CN.md, hugegraph-mcp/docs/architecture.md, hugegraph-mcp/docs/integration.md, hugegraph-mcp/docs/releasing.md, and hugegraph-mcp/tests/distribution_smoke.py to reflect the 24 core tools, Resources/Prompts, transports, PostgresPlanStore, and schema append support.

Testing & Verification

  • hugegraph-mcp & hugegraph-python-client offline tests (verified at 5174486):
    python -m pytest hugegraph-python-client/src/tests hugegraph-mcp/tests -m "not integration" -q
    # 1125 passed, 3 skipped, 90 deselected
  • MCP distribution smoke test (verified at 5174486):
    python hugegraph-mcp/tests/distribution_smoke.py -- <path-to-hugegraph-mcp>
    # Command exited with code 0
  • Live PostgreSQL 14 + HugeGraph integration test (verified at 5174486):
    # hugegraph-mcp/tests/integration/test_live_v2_postgres_and_hugegraph.py
    # 3 passed
  • hugegraph-llm offline tests (verified at d5acfe0 on Windows):
    python -m pytest hugegraph-llm/src/tests -m "not integration" -q
    # 1274 passed, 11 skipped, 16 deselected
    # (2 pre-existing Windows-only failures in test_external_config.py due to POSIX st_mode 0o600/0o660 checks on NTFS)
  • Public docs & stable tool contract tests (verified at 94bec5b):
    python -m pytest hugegraph-mcp/tests/test_public_docs_contract.py hugegraph-mcp/tests/test_v1_stable_tools.py -q
    # 50 passed

@bitflicker64 bitflicker64 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Blocking: yes. Summary: Cancelled edge-delete plans still run through the legacy token, non-DEFAULT graphspace VID indexes move without migration, the Postgres outbox relay can skip events and replays its full history on restart, and the HTTP transport's auth variables are undocumented.

)
from hugegraph_mcp.confirmation_store import ConfirmationStore

ConfirmationStore.from_config().revoke_by_plan_id(cleaned_id)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Important: revoke_by_plan_id only finds tokens bound through bind_plan_id, which manage_graph_data never calls, so after cancel_write_plan_tool reports an edge-delete plan EXPIRED, delete_graph_data_tool(confirm=True) with the dry-run token still drops the edge. Bind the token after save_plan in manage_graph_data, or reject legacy confirmation when the bound plan is no longer ISSUED, and add an edge-delete cancel test.

space = effective_graphspace(graph_space)
if space == "DEFAULT":
return (graph_name, "graph_vids")
return (f"{len(space)}_{space}", graph_name, "graph_vids_ns")

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Important: for a non-DEFAULT graph_space, the VID index moves from <graph>/graph_vids to <n>_<space>/<graph>/graph_vids_ns, so after upgrade SemanticIdQuery opens an empty index and semantic VID matching returns nothing until the user rebuilds, and clean_all_graph_index stops removing the old index. Fall back to or migrate the legacy (graph_name, "graph_vids") index when the namespaced one does not exist.

resource_version, EXTRACT(EPOCH FROM created_at) AS created_at
FROM event_outbox
WHERE seq > %s
AND txid < txid_snapshot_xmin(txid_current_snapshot())

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Important: txid is assigned at the transaction's first FOR UPDATE but seq at the outbox insert, so a transaction with a lower txid and higher seq can commit first; the relay then moves last_seq past the uncommitted lower seq, and that event is never delivered. Order by and track the cursor as (txid, seq), which is gap-free for rows with txid below xmin.

fanout_task = asyncio.create_task(_fanout_events(runtime))
await asyncio.sleep(0)
if isinstance(runtime.plan_store, OutboxSource):
runtime.outbox_relay = OutboxEventRelay(

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Important: the relay starts at initial_seq=0 and nothing deletes from event_outbox, so every restart republishes the whole event history, invalidating caches and sending resources/updated for old writes, and the replay grows with every write. Start the cursor at MAX(seq) on startup and prune old outbox rows.

Comment thread hugegraph-mcp/README.md
| `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 |
| `HUGEGRAPH_MCP_STATE_DIR` | `$XDG_STATE_HOME/hugegraph-mcp` or `~/.local/state/hugegraph-mcp` | Directory containing the SQLite plan, operation, and receipt database |
| `HUGEGRAPH_MCP_TRANSPORT` | `stdio` | MCP transport (`stdio`, `http`, `streamable-http`, or `sse`) |

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Important: the HTTP transports require a Bearer token by default, configured only through HUGEGRAPH_MCP_BEARER_SECRET, HUGEGRAPH_MCP_BEARER_SCOPES and HUGEGRAPH_MCP_REQUIRE_AUTH, none of which is documented, so a user who sets HUGEGRAPH_MCP_TRANSPORT=streamable-http gets 401 on every request. Add these variables to the configuration tables in README.md and README.zh-CN.md.


@mcp.tool()
@_register_tool
def apply_schema_tool(

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Minor: this tool description still says apply rejects schema append, but this PR makes append_vertex_label and append_edge_label confirmable, so MCP clients are told not to use them. List both as supported and keep only eliminate and remove/drop as rejected.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants