feat(mcp): add HugeGraph MCP V1 tools and harden guarded writes

[UIengF]

Overview

This PR adds hugegraph-mcp, a standalone thin adapter that gives MCP clients and agents controlled access to HugeGraph and HugeGraph-AI. The MCP layer owns stable tool contracts, configuration and authorization, typed queries, immutable server-side write plans, durable operation receipts, status inspection, and reconciliation.

The default public contract is v2_core; v1 remains available as a compatibility mode. The runtime requires Python >= 3.10 and HugeGraph Server >= 1.7.0; unverified versions, backends, and atomic capabilities fail closed.

Public tool contract

• v2_core registers 16 tools by default.
• v1 registers 10 compatibility tools and omits inspect_schema_tool, query_graph_data_tool, mutate_graph_properties_tool, confirm_write_tool, get_write_status_tool, and reconcile_write_tool.
• The public surface covers graph and schema inspection, typed bounded vertex/edge queries, Gremlin generation, text-to-graph extraction, schema design and validation, and controlled write previews.
• import_graph_data_tool(mode=table) remains FEATURE_DISABLED; unimplemented table_data and mapping parameters are not exposed in the MCP JSON Schema.
• Legacy internal aggregate entry points are not registered as MCP tools.
• Safe defaults remain HUGEGRAPH_MCP_READONLY=true, HUGEGRAPH_MCP_ALLOW_AI=false, and HUGEGRAPH_MCP_ADMIN_MODE=false.

Confirmed-write safety model

The canonical flow is:

structured dry-run
  -> server persists an immutable WritePlan
  -> client receives plan_id
  -> confirm_write_tool(plan_id)
  -> get_write_status_tool(plan_id)
  -> reconcile_write_tool(plan_id), when required

• Confirmation submits only plan_id. Backend IDs, endpoints, expected and desired state, operation order, graph target, principal, and expiry are loaded from the persisted server plan.
• The SQLite plan store persists plans, per-operation state, and receipts. Confirming a completed plan_id again returns the durable result without issuing another write.
• APPLIED, ALREADY_APPLIED, REJECTED, CONFLICT, PARTIAL, UNKNOWN, and RETRYABLE_NOT_APPLIED retain distinct meanings. UNKNOWN and PARTIAL are never retried automatically.
• Edge endpoints and delete targets are bound to stable backend IDs during dry-run; execution does not re-evaluate mutable property predicates.
• Legacy plan_hash, nonce, and expires_at fields remain locator-only compatibility inputs for one release. They must be provided together, cannot be mixed with plan_id, and produce a deprecation warning.
• The bundled plan store currently implements SQLite only and supports one writable MCP instance. Declaring multiple writers fails closed; multi-replica writes require a future shared transactional store.
• Real schema apply remains disabled in v1.

Executable boundaries

The canonical user-confirmed flow currently supports:

• One property key, vertex label, or edge label creation per schema plan.
• Exact edge deletion by a persisted edge ID.

The following operations are preview-only, issue no plan_id, return FEATURE_DISABLED on confirmation, and perform no write:

• Graph creation/import, because HugeGraph 1.7.0 has no verified atomic create-if-absent primitive.
• Vertex/edge property append/eliminate, because HugeGraph 1.7.0 has no backend-enforced compare-and-set primitive.
• Isolated vertex deletion with cascade=false, because Docker concurrency testing reproduced a non-isolated edge-add/delete race.
• Index create/rebuild, schema drop, and other destructive operations without a registered atomic adapter.

refresh_vid_embeddings_tool remains a separate admin write tool gated by readonly, AI, and admin configuration.

Raw Gremlin boundary

All public Raw Gremlin execution paths are currently disabled:

• execute_gremlin_read_tool
• execute_gremlin_write_tool
• generate_gremlin_tool(execute=true)

Admin mode cannot bypass this gate. Raw execution can only be enabled after the deployment enforces a read-only database principal, server evaluation/wait timeouts, a server-side result cap, and a streaming client-side byte cap. Typed reads and generate_gremlin_tool(execute=false) remain available.

Additional changes

• Fix HugeGraph edge ID encoding, graphspace/auth routing, and client schema field forwarding.
• Apply shared validation for SINGLE, LIST, SET, UUID, DATE, BLOB, OBJECT, and numeric bounds.
• Add typed and bounded connect/read/write timeout and result-budget configuration.
• Normalize HugeGraph-AI Thin API envelopes with bounded unwrapping and secret-safe error logging.
• Importing the Python client no longer replaces the host process logging configuration; a narrow contract is added for a future backend property CAS primitive.
• Add an evidence-backed backend capability matrix; unknown versions, backends, and unverified atomic semantics fail closed.
• Add immutable-plan, SQLite migration, fault-injection, fencing, reconciliation, concurrency, and Docker coverage.

Verification

Current head 845baaf2:

• HugeGraph MCP: 784 passed, 17 skipped
• HugeGraph Python client: 71 passed, 70 skipped
• HugeGraph-LLM Thin API: 15 passed, with 5 dependency deprecation warnings
• SQLite migration: 13 passed
• Executor fault/fencing: 8 passed
• Deterministic Docker HugeGraph 1.7.0 real-write path: 16 passed
• A 300-iteration isolated-delete probe reproduced two non-isolated outcomes, so the capability remains disabled
• Ruff check, Ruff format, ASF License Header, and git diff --check: passed
• FastMCP stdio: initialize, 16-tool tools/list, and inspect_graph_tool call passed

Out of scope

This PR does not add GraphRAG question answering, SQL/table import, arbitrary Raw Gremlin execution, general unconditional graph-data update, index/rebuild, destructive schema apply, MCP resources, HTTP/SSE transport, or multi-replica writes backed by independent SQLite files.

[imbajin]

Reviewed the current MCP/client changes at head 8842bb53007102b47d50e4eaabb6e2cc51e9b526. I found several install/runtime safety issues that should be addressed before relying on the new MCP package independently. Local non-live checks passed, so these comments focus on behavioral and packaging gaps rather than test failures.

[VGalaxies]

Review summary

• Blocking: yes
• Summary: The PR still has blocking correctness and write-safety issues in the new MCP/Thin API surface.
• Evidence:
  • static review of git diff origin/main...HEAD
  • git diff --check origin/main...HEAD only reports the known blank-line style issue