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

.github/workflows/hugegraph-mcp.yml

@@ -0,0 +1,203 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+name: HugeGraph-MCP CI
+
+on:
+  push:
+    branches:
+      - "main"
+      - "release-*"
+    paths:
+      - "hugegraph-mcp/**"
+      - "hugegraph-python-client/**"
+      - "pyproject.toml"
+      - "uv.lock"
+      - ".github/workflows/hugegraph-mcp.yml"
+  pull_request:
+    paths:
+      - "hugegraph-mcp/**"
+      - "hugegraph-python-client/**"
+      - "pyproject.toml"
+      - "uv.lock"
+      - ".github/workflows/hugegraph-mcp.yml"
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        run: |
+          curl -LsSf https://astral.sh/uv/install.sh | sh
+          echo "$HOME/.cargo/bin" >> $GITHUB_PATH
+
+      - name: Cache dependencies
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cache/uv
+          key: ${{ runner.os }}-mcp-uv-${{ matrix.python-version }}-${{ hashFiles('**/pyproject.toml', 'uv.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-mcp-uv-${{ matrix.python-version }}-
+
+      - name: Install MCP dependencies
+        run: |
+          # Install the standalone MCP packages with pip. FastMCP 3.x has
+          # platform-specific metadata that uv cannot resolve on Linux x86.
+          python -m pip install --upgrade pip
+          python -m pip install \
+            -e ./hugegraph-python-client \
+            -e ./hugegraph-mcp \
+            "pytest~=8.0.0" \
+            "ruff>=0.11.0"
+          python --version
+
+      - name: Verify isolated wheel install
+        if: matrix.python-version == '3.10'
+        run: |
+          rm -rf wheelhouse isolated-mcp-venv
+          uv build --wheel --out-dir wheelhouse hugegraph-python-client
+          uv build --wheel --out-dir wheelhouse hugegraph-mcp
+          python -m venv isolated-mcp-venv
+          isolated-mcp-venv/bin/python -m pip install \
+            --find-links wheelhouse \
+            wheelhouse/hugegraph_python_client-*.whl \
+            wheelhouse/hugegraph_mcp-*.whl
+          isolated-mcp-venv/bin/python - <<'PY'
+          from importlib.metadata import version
+          from types import SimpleNamespace
+          from unittest.mock import Mock
+
+          import hugegraph_mcp
+          import pyhugegraph
+          from hugegraph_mcp.server import main
+          from pyhugegraph.api.auth import AuthManager
+          from pyhugegraph.utils.huge_config import HGraphConfig
+          from pyhugegraph.utils.huge_requests import HGraphSession
+
+          assert version("hugegraph-python-client") == "1.7.0"
+          assert version("hugegraph-mcp") == "1.7.0"
+
+          class CaptureSession:
+              cfg = SimpleNamespace(graphspace="GS", gs_supported=True)
+
+              def request(self, path, method="GET", **_kwargs):
+                  self.path = path
+                  return {"ok": True}
+
+          capture = CaptureSession()
+          AuthManager(capture).list_users()
+          assert capture.path == "/graphspaces/GS/auth/users"
+
+          config = HGraphConfig(
+              "http://127.0.0.1:8080", "admin", "pwd", "g", graphspace="GS"
+          )
+          session = HGraphSession(config, session=Mock())
+          assert session.resolve("schema") == (
+              "http://127.0.0.1:8080/graphspaces/GS/graphs/g/schema"
+          )
+          PY
+
+      - name: Check MCP formatting
+        run: |
+          ruff format --check hugegraph-mcp/hugegraph_mcp hugegraph-mcp/tests
+
+      - name: Lint MCP
+        run: |
+          ruff check hugegraph-mcp/hugegraph_mcp hugegraph-mcp/tests
+
+      - name: Run MCP tests
+        run: |
+          python -m pytest hugegraph-mcp -m "not live and not integration and not llm"
+
+  real-hugegraph-write-path:
+    runs-on: ubuntu-latest
+    services:
+      hugegraph:
+        image: hugegraph/hugegraph:1.7.0
+        env:
+          PASSWORD: admin
+        options: >-
+          --health-cmd="curl -f http://localhost:8080/versions || exit 1"
+          --health-interval=10s
+          --health-timeout=5s
+          --health-retries=12
+        ports:
+          - 8080:8080
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      - name: Set up Python 3.10
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+
+      - name: Install uv
+        run: |
+          curl -LsSf https://astral.sh/uv/install.sh | sh
+          echo "$HOME/.cargo/bin" >> $GITHUB_PATH
+
+      - name: Cache dependencies
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cache/uv
+          key: ${{ runner.os }}-mcp-real-hugegraph-uv-${{ hashFiles('**/pyproject.toml', 'uv.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-mcp-real-hugegraph-uv-
+
+      - name: Install MCP dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install \
+            -e ./hugegraph-python-client \
+            -e ./hugegraph-mcp \
+            "pytest~=8.0.0"
+
+      - name: Run real HugeGraph write-path tests
+        working-directory: hugegraph-mcp
+        env:
+          RUN_MCP_REAL_HUGEGRAPH_TESTS: "1"
+          HUGEGRAPH_URL: http://127.0.0.1:8080
+          HUGEGRAPH_GRAPH_PATH: DEFAULT/hugegraph
+          HUGEGRAPH_USER: admin
+          HUGEGRAPH_PASSWORD: admin
+          HUGEGRAPH_MCP_READONLY: "false"
+          HUGEGRAPH_MCP_ALLOW_AI: "false"
+        run: |
+          python -m pytest tests/integration/test_real_write_path.py -m real_hugegraph

.github/workflows/publish-hugegraph-mcp.yml

@@ -0,0 +1,82 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+name: Publish HugeGraph MCP
+
+on:
+  push:
+    tags:
+      - "mcp-v*"
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v6
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+
+      - name: Verify release tag
+        if: github.event_name == 'push'
+        run: |
+          package_version=$(uv run --no-project python -c \
+            'import tomllib; print(tomllib.load(open("hugegraph-mcp/pyproject.toml", "rb"))["project"]["version"])')
+          test "${GITHUB_REF_NAME}" = "mcp-v${package_version}"
+
+      - name: Build distributions
+        run: uv build --directory hugegraph-mcp --out-dir dist
+
+      - name: Verify distributions
+        run: uvx --from twine twine check dist/*
+
+      - name: Verify published dependencies and console script
+        run: |
+          wheel=$(find dist -name '*.whl' -print -quit)
+          uvx --from "$wheel" hugegraph-mcp < /dev/null
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: hugegraph-mcp-distributions
+          path: dist/
+          if-no-files-found: error
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi-hugegraph-mcp
+      url: https://pypi.org/p/hugegraph-mcp
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: hugegraph-mcp-distributions
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

.github/workflows/publish-hugegraph-python-client.yml

@@ -0,0 +1,76 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+name: Publish HugeGraph Python Client
+
+on:
+  push:
+    tags:
+      - "client-v*"
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v6
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+
+      - name: Verify release tag
+        run: |
+          package_version=$(uv run --no-project python -c \
+            'import tomllib; print(tomllib.load(open("hugegraph-python-client/pyproject.toml", "rb"))["project"]["version"])')
+          test "${GITHUB_REF_NAME}" = "client-v${package_version}"
+
+      - name: Build distributions
+        run: uv build --package hugegraph-python-client --out-dir dist
+
+      - name: Verify distributions
+        run: uvx --from twine twine check dist/*
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: hugegraph-python-client-distributions
+          path: dist/
+          if-no-files-found: error
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi-hugegraph-python-client
+      url: https://pypi.org/p/hugegraph-python-client
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: hugegraph-python-client-distributions
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

.github/workflows/ruff.yml

@@ -7,6 +7,9 @@ on:
       - "release-*"
   pull_request:
 
+permissions:
+  contents: read
+
 jobs:
   build:
     runs-on: ubuntu-latest
@@ -40,7 +43,7 @@ jobs:
 
       - name: Install dev dependencies
         run: |
-          uv sync --extra dev
+          uv sync --extra dev --extra llm --extra python-client
 
       - name: Check code formatting with Ruff
         run: |
@@ -88,4 +91,4 @@ jobs:
         run: uv run ty check hugegraph-llm/src hugegraph-python-client/src
         continue-on-error: true
         # TODO: extend scope to hugegraph-ml once heavy optional deps (DGL, PyTorch) are handled
-        # TODO: add graph-mcp once the module is introduced
+        # TODO: add graph-mcp after its type-check baseline is established

.gitignore

@@ -41,6 +41,9 @@ MANIFEST
 #  before PyInstaller builds the exe, so as to inject date/other infos into it.
 *.manifest
 *.spec
+# Exception: allow .spec/ directory to be tracked
+!.spec/
+!.spec/**
 
 # Installer logs
 pip-log.txt