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

[UIengF]

Summary

This PR adds hugegraph-mcp, a FastMCP-based thin adapter for HugeGraph. It provides a stable V1 tool surface for graph inspection, read-only Gremlin, graph extraction, guarded import/delete, schema design and validation, graph queries, and schema-aware property mutations.

主要改动

• 新增 HugeGraph MCP 子模块、CLI 入口、中英文 README、Skills 和独立 CI。
• 提供图检查、Gremlin 生成/只读执行、文本抽取、受控导入/删除、Schema 设计/校验、顶点/边查询和属性变更工具。
• 普通写操作遵循 dry_run -> server-issued plan -> confirm：SQLite 持久化签发记录和已消费 nonce，限制 10 分钟 TTL，跨进程防重放，并保证并发确认只有一个成功。
• execute_gremlin_write_tool 明确为唯一 break-glass 例外，只允许隔离且可信的 admin transport 使用。
• HugeGraph-LLM legacy Thin API 写端点默认关闭；仅在 login 和独立写开关同时启用后可用，并由生产 Bearer 鉴权 router 保护。
• MCP AI client 支持 HUGEGRAPH_AI_TOKEN，不再误用 HugeGraph 数据库密码作为 AI Basic Auth。
• AI client requests accept relative service paths only; absolute and scheme-relative URLs are rejected before credential injection or network access.
• Typed graph queries validate limit consistently for every operation and return structured validation errors.
• Contributor documentation uses portable project-path placeholders instead of machine-specific paths.
• 补齐 CUSTOMIZE_STRING/CUSTOMIZE_NUMBER 顶点 ID 校验、父子边字段显式拒绝、Schema 语义校验、LIST/SET/SINGLE 属性语义和 client plain-filename logging。
• MCP 依赖约束为 hugegraph-python-client>=1.7.0；CI 从同一 checkout 构建并隔离安装两个 wheel，校验版本和 graphspace/auth routing。
• 本地服务及 Docker 示例默认只绑定 loopback；GitHub Actions 显式限制为 contents: read。

Test

• uv run ruff format --check .
• uv run ruff check .
• git diff --check
• uv lock --check
• MCP non-external tests: 480 passed, 11 deselected
• HugeGraph-LLM Thin API/auth tests: 27 passed
• HugeGraph-LLM non-external unit split: 333 passed, 5 skipped
• Python client non-integration tests: 57 passed, 67 deselected
• Isolated client/MCP wheel install, version, graphspace, and auth-routing smoke: passed
• Real HugeGraph 1.7.0 write-path suite: 11 passed
• Additional real-image verification:
  • writable dry-run and confirm succeeded;
  • a client-computed plan without server issuance was rejected with zero writes;
  • replay was rejected with PLAN_ALREADY_USED and zero additional writes;
  • issued/consumed state survived process restarts;
  • invalid CUSTOMIZE_STRING/NUMBER IDs were rejected during dry-run with zero writes;
  • typed query, read-only Gremlin, and SINGLE/LIST/SET behavior remained functional.

Commit Structure

1. feat(mcp): add HugeGraph MCP V1 core and guarded workflows
2. chore(mcp): add V1 tests, docs, skills, and CI
3. feat(mcp): add and harden P0a graph toolset
4. fix(mcp): complete remaining defect hardening

范围说明

V1 暂不包含 GraphRAG 问答、SQL/表格数据导入、通用图数据 update 和真实 Schema apply。暂不支持的入口继续返回 FEATURE_DISABLED，后续通过独立 PR 实现。

要求 HugeGraph Server >= 1.7.0。

[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