harbor-aiops 0.2.0__tar.gz

harbor_aiops-0.2.0/.claude-plugin/plugin.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
+  "name": "harbor-aiops",
+  "displayName": "Harbor AIops",
+  "version": "0.2.0",
+  "description": "Governed Harbor registry operations — 39 MCP tools with audit.",
+  "author": {
+    "name": "Wei Zhou",
+    "email": "zhouwei008@gmail.com",
+    "url": "https://github.com/AIops-tools"
+  },
+  "homepage": "https://github.com/AIops-tools/Harbor-AIops",
+  "repository": "https://github.com/AIops-tools/Harbor-AIops",
+  "license": "MIT",
+  "keywords": [
+    "harbor",
+    "container-registry",
+    "oci",
+    "mcp",
+    "aiops"
+  ]
+}

harbor_aiops-0.2.0/.dockerignore

@@ -0,0 +1,7 @@
+*
+!Dockerfile
+!pyproject.toml
+!README.md
+!LICENSE
+!harbor_aiops/
+!harbor_aiops/**

harbor_aiops-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,28 @@
+name: CI
+
+on:
+  push:
+    branches: [bootstrap, main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  quality:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - name: Install Python and dependencies
+        run: |
+          uv python install 3.11
+          uv sync --dev --python 3.11
+      - name: Tests
+        run: uv run pytest -q
+      - name: Lint
+        run: uv run ruff check .
+      - name: Security scan
+        run: uv run bandit -r harbor_aiops -ll -q
+      - name: Build
+        run: uv build

harbor_aiops-0.2.0/.github/workflows/mcp-publish.yml

@@ -0,0 +1,57 @@
+name: mcp-publish
+
+# Registry publication follows the Harbor wheel's first appearance on PyPI.
+
+on:
+  workflow_dispatch:
+  release:
+    types: [published]
+
+permissions:
+  id-token: write
+  contents: read
+
+jobs:
+  publish-mcp:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Wait for PyPI
+        # The release event also triggers the PyPI publish workflow; the MCP
+        # registry validates that the package version exists on PyPI, so poll
+        # until it has propagated (every 15s, up to 10 minutes).
+        run: |
+          python3 - <<'EOF'
+          import json
+          import sys
+          import time
+          import urllib.error
+          import urllib.request
+
+          with open("server.json", encoding="utf-8") as f:
+              package = json.load(f)["packages"][0]
+          name, version = package["identifier"], package["version"]
+          url = f"https://pypi.org/pypi/{name}/{version}/json"
+          deadline = time.monotonic() + 600
+          while True:
+              try:
+                  with urllib.request.urlopen(url, timeout=10):
+                      print(f"{name}=={version} is available on PyPI.")
+                      sys.exit(0)
+              except (urllib.error.URLError, OSError) as exc:
+                  print(f"{name}=={version} not on PyPI yet ({exc}); "
+                        "retrying in 15s...")
+              if time.monotonic() >= deadline:
+                  sys.exit(f"Timed out after 10 minutes waiting for "
+                           f"{name}=={version} to appear on PyPI. "
+                           "Check the PyPI publish workflow, then re-run "
+                           "this workflow via workflow_dispatch.")
+              time.sleep(15)
+          EOF
+      - name: Install mcp-publisher
+        run: |
+          curl -sL "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher
+      - name: Login to MCP Registry (GitHub OIDC)
+        run: ./mcp-publisher login github-oidc
+      - name: Publish server.json
+        run: ./mcp-publisher publish

harbor_aiops-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,28 @@
+name: Publish to PyPI
+
+# First public package release uses the Harbor-specific pending PyPI publisher.
+
+# Trusted Publishing (OIDC) — publishes from GitHub's runners with no API token,
+# sidestepping the local-IP / account new-project rate limit. Configure a matching
+# "trusted publisher" for this package on PyPI (see the repo release notes).
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write   # required for PyPI Trusted Publishing (OIDC)
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+      - name: Build sdist + wheel
+        run: uv build
+      - name: Publish to PyPI (Trusted Publishing)
+        uses: pypa/gh-action-pypi-publish@release/v1

harbor_aiops-0.2.0/.gitignore

@@ -0,0 +1,23 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+
+# Virtual envs / build
+.venv/
+dist/
+build/
+
+# uv
+uv.lock
+
+# Local config / secrets (never commit)
+*.env
+.env
+config.yaml
+
+# OS
+.DS_Store
+.coverage

harbor_aiops-0.2.0/.mcp.json

@@ -0,0 +1,13 @@
+{
+  "mcpServers": {
+    "harbor-aiops": {
+      "type": "stdio",
+      "command": "uvx",
+      "args": [
+        "--from",
+        "harbor-aiops==0.2.0",
+        "harbor-aiops-mcp"
+      ]
+    }
+  }
+}

harbor_aiops-0.2.0/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## v0.2.0 — 2026-11-05
+
+- Expand to 39 governed MCP/CLI tools for project, repository, artifact, tag, vulnerability, quota, GC, replication and retention operations.
+- Add bounded job logs, measured pagination truncation and explicit failed probes.
+- Add guarded artifact scan, tag creation and exact mutable-tag deletion; preserve unknown outcomes on asynchronous work or lost responses.
+- Limit Docker build context and image copies to package source and packaging files.
+- Add GitHub CI for tests, lint, security scan and build.
+
+## 0.1.0
+
+- Initial local development version; not published.

harbor_aiops-0.2.0/Dockerfile

@@ -0,0 +1,6 @@
+FROM python:3.13-slim
+WORKDIR /app
+COPY pyproject.toml README.md LICENSE /app/
+COPY harbor_aiops /app/harbor_aiops
+RUN pip install --no-cache-dir /app
+ENTRYPOINT ["harbor-aiops-mcp"]

harbor_aiops-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 wei <zhouwei008@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

harbor_aiops-0.2.0/PKG-INFO

@@ -0,0 +1,60 @@
+Metadata-Version: 2.5
+Name: harbor-aiops
+Version: 0.2.0
+Summary: Governed Harbor registry diagnosis for health, storage, GC, replication and retention.
+Author-email: Wei Zhou <zhouwei008@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: cryptography>=42.0
+Requires-Dist: httpx<1.0,>=0.27
+Requires-Dist: mcp[cli]<3.0,>=2.0
+Requires-Dist: pyyaml<7.0,>=6.0
+Requires-Dist: rich<16.0,>=13.0
+Requires-Dist: typer<1.0,>=0.12
+Description-Content-Type: text/markdown
+
+<!-- mcp-name: io.github.AIops-tools/harbor-aiops -->
+# Harbor AIops
+
+Governed Harbor container-registry operations with 39 MCP tools and corresponding CLI commands. Every call is audited and budgeted by the bundled governance harness. Artifact scan, tag creation and high-risk tag deletion have dry-run previews; uncertain results are reported as `outcomeUnknown`.
+
+## What it checks
+
+- Component health and system volume use.
+- Projects, repository inventory, artifacts, tags, vulnerability reports, quotas and project audit logs.
+- Registry statistics, project members, tag immutability rules, labels and robot metadata (secrets redacted).
+- Latest registry-wide and scheduled scan metrics, plus bounded artifact scan report logs.
+- Guarded deletion of one proven, mutable tag with an absence post-check.
+- Garbage collection execution history.
+- GC execution details and bounded plain-text logs.
+- Replication policies, executions, tasks and bounded task logs.
+- Retention policy, execution, tasks and bounded task logs by actual IDs.
+- `harbor_diagnose` combines health, volume, GC and replication observations. Failed probes appear as errors with `data: null`.
+
+Lists have `items`, `returned`, `limit`, and measured `truncated` fields. They are capped at 500 records per call.
+
+## Setup from source
+
+Requires Python 3.11+, `uv`, and a Harbor instance. Install locally with `uv sync --dev`. Run `uv run harbor-aiops init` to configure an HTTPS target and encrypt its password, or create `~/.harbor-aiops/config.yaml` with a `targets` list:
+
+```yaml
+targets:
+  - name: primary
+    host: harbor.example.com
+    username: robot$ops
+    scheme: https
+    port: 443
+    verify_ssl: true
+    timeout: 30
+```
+
+Run `uv run harbor-aiops secret set primary`, then `uv run harbor-aiops doctor` and `uv run harbor-aiops diagnose`. The MCP entry point is `uv run harbor-aiops-mcp`. Set `HARBOR_AIOPS_MASTER_PASSWORD` for noninteractive secret-store access. TLS verification is enabled by default; `ca_file` accepts a custom CA PEM.
+
+## Scope and verification
+
+The `scan-artifact` command starts an asynchronous scan and reports an unknown final outcome until its status is checked. `create-tag` proves the tag was absent and checks that it appeared after the write. `delete-tag` requires an exact mutable tag on the specified digest, previews the target and confirms absence after deletion. Neither tag write mints an undo token because immutability and later artifact changes can make the inverse unsafe. Retention execution, replication restart, GC start/stop, artifact deletion and policy changes remain outside this release until their actual outcomes and recovery paths can be verified on disposable Harbor. See [verification](docs/VERIFICATION.md). Missing operations and live-environment feedback are welcome as issues or PRs.
+
+## Development
+
+`uv run pytest -q`, `uv run ruff check .`, and `uv run bandit -r harbor_aiops -ll` are local checks. Root handbook gates must pass before release.

harbor_aiops-0.2.0/README.md

@@ -0,0 +1,44 @@
+<!-- mcp-name: io.github.AIops-tools/harbor-aiops -->
+# Harbor AIops
+
+Governed Harbor container-registry operations with 39 MCP tools and corresponding CLI commands. Every call is audited and budgeted by the bundled governance harness. Artifact scan, tag creation and high-risk tag deletion have dry-run previews; uncertain results are reported as `outcomeUnknown`.
+
+## What it checks
+
+- Component health and system volume use.
+- Projects, repository inventory, artifacts, tags, vulnerability reports, quotas and project audit logs.
+- Registry statistics, project members, tag immutability rules, labels and robot metadata (secrets redacted).
+- Latest registry-wide and scheduled scan metrics, plus bounded artifact scan report logs.
+- Guarded deletion of one proven, mutable tag with an absence post-check.
+- Garbage collection execution history.
+- GC execution details and bounded plain-text logs.
+- Replication policies, executions, tasks and bounded task logs.
+- Retention policy, execution, tasks and bounded task logs by actual IDs.
+- `harbor_diagnose` combines health, volume, GC and replication observations. Failed probes appear as errors with `data: null`.
+
+Lists have `items`, `returned`, `limit`, and measured `truncated` fields. They are capped at 500 records per call.
+
+## Setup from source
+
+Requires Python 3.11+, `uv`, and a Harbor instance. Install locally with `uv sync --dev`. Run `uv run harbor-aiops init` to configure an HTTPS target and encrypt its password, or create `~/.harbor-aiops/config.yaml` with a `targets` list:
+
+```yaml
+targets:
+  - name: primary
+    host: harbor.example.com
+    username: robot$ops
+    scheme: https
+    port: 443
+    verify_ssl: true
+    timeout: 30
+```
+
+Run `uv run harbor-aiops secret set primary`, then `uv run harbor-aiops doctor` and `uv run harbor-aiops diagnose`. The MCP entry point is `uv run harbor-aiops-mcp`. Set `HARBOR_AIOPS_MASTER_PASSWORD` for noninteractive secret-store access. TLS verification is enabled by default; `ca_file` accepts a custom CA PEM.
+
+## Scope and verification
+
+The `scan-artifact` command starts an asynchronous scan and reports an unknown final outcome until its status is checked. `create-tag` proves the tag was absent and checks that it appeared after the write. `delete-tag` requires an exact mutable tag on the specified digest, previews the target and confirms absence after deletion. Neither tag write mints an undo token because immutability and later artifact changes can make the inverse unsafe. Retention execution, replication restart, GC start/stop, artifact deletion and policy changes remain outside this release until their actual outcomes and recovery paths can be verified on disposable Harbor. See [verification](docs/VERIFICATION.md). Missing operations and live-environment feedback are welcome as issues or PRs.
+
+## Development
+
+`uv run pytest -q`, `uv run ruff check .`, and `uv run bandit -r harbor_aiops -ll` are local checks. Root handbook gates must pass before release.

harbor_aiops-0.2.0/SECURITY.md

@@ -0,0 +1,7 @@
+# Security
+
+Report vulnerabilities privately through the repository's GitHub security advisory flow when the repository is available. Do not put credentials, registry URLs with embedded secrets, or private image details into public issues.
+
+Credentials are stored in the encrypted local `secrets.enc` store. The config file contains only target location and username. TLS verification is on by default, and environment proxy settings are not inherited for registry requests. The bundled governance harness records audit metadata and enforces budgets. Use a Harbor account with the least server-side privileges needed for the requested queries and optional scan/tag writes. Scan, tag creation and high-risk single-tag deletion use dry-run; deletion requires exact target and mutable-status checks, CLI double confirmation, and a post-read. A lost response or failed post-read is marked unknown. Job logs and vulnerability details may contain sensitive data, so share their output only with intended operators.
+
+The Docker build context and image copy include only packaging files and `harbor_aiops/`; local config, encrypted secrets, audit databases and virtual environments are excluded.

harbor_aiops-0.2.0/docs/VERIFICATION.md

@@ -0,0 +1,15 @@
+# Verification — Harbor AIops
+
+## Source-backed API surface
+
+The Harbor [v2.0 Swagger schema](https://github.com/goharbor/harbor/blob/main/api/v2.0/swagger.yaml), checked 2026-11-04, defines the project/repository/artifact/tag, quota, GC, replication, retention and project-log paths used here, plus `/statistics`, project members, immutable-tag rules, robot accounts, labels, both scan-metrics endpoints and artifact scan logs. It explicitly requires a slash in a `repository_name` path argument to be encoded twice. GC, replication-task and retention-task logs produce `text/plain`. Artifact scan is `POST .../scan` with HTTP 202; tag creation is `POST .../tags` with HTTP 201. The schema defines exact tag deletion as `DELETE .../tags/{tag_name}` with HTTP 200. Collection responses use `page` and `page_size`; the implementation reads an extra row to measure truncation.
+
+## Local verification
+
+`tests/test_registry.py` uses a strict HTTP transport fake based on these paths and a loopback HTTP server for proxy isolation. It covers authentication, multi-page GC history, exact-limit results, 403 responses, repository double encoding, bounded plain-text logs, dry-run tag creation, post-read tag verification, exact mutable-tag deletion with dry-run and unknown post-check outcomes, robot-secret redaction, new read endpoint shapes, async scan uncertainty, lost write response, HTTP 500 ambiguity, redirect rejection and a partially failing diagnosis. Governance invariant tests come from the current tool line. Current result: 146 passing tests, Ruff clean, Bandit 0 Medium+ and wheel/sdist build, rerun on 2026-11-05.
+
+The current 0.2.0 candidate wheel was rebuilt and installed into a new environment outside the source tree; its MCP registry reports 39 tools. Its `delete-tag` CLI ran preview and real calls against a strict loopback Harbor HTTP stub; preview made no DELETE, the real call made exactly one DELETE and reported success only after the tag GET returned 404. An earlier 0.2.0 candidate wheel was also installed outside the source tree; `harbor_aiops.__file__` resolved under `site-packages`. Its CLI ran four cases against a strict loopback HTTP stub: health, project listing, tag preview and real tag creation. The stub saw exactly one POST; the real create returned success only after a confirming GET. This validates packaging and request shape, not a real Harbor server.
+
+## Not yet live verified
+
+No Harbor instance was available: Docker is installed but its daemon was not running. No real Harbor API response, permissions matrix, asynchronous job completion, GC failure, retention dry-run, or write cycle has been verified. These writes record no undo token; deleting a tag cannot be safely reversed after it may be rebound or become immutable. Do not describe the package as production validated. The next gate is a disposable Harbor deployment with deliberately failed replication/retention and comparison to Harbor's own UI/API.

harbor_aiops-0.2.0/glama.json

@@ -0,0 +1,6 @@
+{
+  "$schema": "https://glama.ai/mcp/schemas/server.json",
+  "maintainers": [
+    "zw008"
+  ]
+}

harbor_aiops-0.2.0/harbor_aiops/__init__.py

@@ -0,0 +1,8 @@
+"""Harbor AIops: governed container registry operations for AI agents."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("harbor-aiops")
+except PackageNotFoundError:
+    __version__ = "0.0.0+unknown"

harbor_aiops-0.2.0/harbor_aiops/cli/__init__.py

@@ -0,0 +1,9 @@
+"""CLI package for harbor-aiops.
+
+Re-exports ``app`` so the pyproject entry point
+``harbor-aiops = "harbor_aiops.cli:app"`` works unchanged.
+"""
+
+from harbor_aiops.cli._root import app
+
+__all__ = ["app"]

harbor_aiops-0.2.0/harbor_aiops/cli/_common.py

@@ -0,0 +1,122 @@
+"""Shared helpers for harbor-aiops CLI sub-modules."""
+
+from __future__ import annotations
+
+import functools
+from collections.abc import Callable
+from typing import Annotated, Any
+
+import typer
+from rich.console import Console
+from rich.markup import escape
+
+console = Console()
+
+# ─── Shared Option types ───────────────────────────────────────────────────
+
+TargetOption = Annotated[
+    str | None, typer.Option("--target", "-t", help="Target name from config")
+]
+DryRunOption = Annotated[
+    bool, typer.Option("--dry-run", help="Print the API call without executing")
+]
+
+
+def _cli_error_types() -> tuple[type[BaseException], ...]:
+    """Exceptions translated to a one-line teaching error instead of a traceback.
+
+    ``BudgetExceeded`` (and the retained ``PolicyDenied`` type) are raised by
+    ``@governed_tool`` OUTSIDE the tool body, so ``tool_errors`` never sees them
+    and they never arrive as an ``{"error": ...}`` dict. Their message is the
+    teaching text (e.g. which budget was hit) — without them here such a refusal
+    reaches the CLI as a traceback instead.
+    """
+    from harbor_aiops.connection import HarborApiError
+    from harbor_aiops.governance import BudgetExceeded, PolicyDenied
+    from harbor_aiops.secretstore import SecretStoreError
+
+    return (HarborApiError, PolicyDenied, BudgetExceeded, SecretStoreError, KeyError, OSError,
+            ValueError)
+
+
+def cli_errors(fn: Callable) -> Callable:
+    """Translate known exceptions into one red line + exit code 1."""
+
+    @functools.wraps(fn)
+    def wrapper(*args: Any, **kwargs: Any) -> Any:
+        try:
+            return fn(*args, **kwargs)
+        except (typer.Exit, typer.Abort):
+            raise
+        except _cli_error_types() as e:
+            message = str(e)
+            if isinstance(e, KeyError):
+                message = f"Missing required key or environment variable: {message}"
+            # Upstream text can contain "[/bold]"; unescaped, rich raises on it and the
+            # real error is replaced by a MarkupError traceback.
+            console.print(f"[red]Error: {escape(message)}[/]")
+            raise typer.Exit(1) from e
+
+    return wrapper
+
+
+#: Exit status for a write whose outcome could not be determined — kept distinct
+#: from 0 (confirmed) and 1 (failed) so a script can tell all three apart.
+EXIT_UNDETERMINED = 2
+
+
+def governed(result: Any) -> dict:
+    """Return a governed tool's result, or print its error and exit 1.
+
+    The ``harbor_aiops.mcp_server.tools`` twins never raise: ``@tool_errors`` flattens every
+    failure — an unreachable service, a refused login, a bad argument — into
+    ``{"error": ...}``. A CLI command that drops that on the floor prints an empty
+    table and exits 0 as if the service had nothing to report. Route every governed
+    call through here.
+    """
+    # ``outcomeUnknown`` is judged BEFORE ``error``, matching the harness: a
+    # write whose response was lost carries BOTH keys, and it is audited
+    # `unknown` precisely because it may have taken effect. Reporting that as a
+    # plain failure would tell a script the change did not happen and invite the
+    # double-apply the payload's own note warns about.
+    if isinstance(result, dict) and result.get("outcomeUnknown"):
+        console.print(f"[yellow]Outcome undetermined: {escape(str(result.get('note') or ''))}[/]")
+        raise typer.Exit(EXIT_UNDETERMINED)
+    if isinstance(result, dict) and result.get("error"):
+        console.print(f"[red]Error: {escape(str(result['error']))}[/]")
+        raise typer.Exit(1)
+    return result if isinstance(result, dict) else {}
+
+
+def dry_run_print(*, operation: str, api_call: str, parameters: dict | None = None) -> None:
+    """Print a dry-run preview of the API call that would be made."""
+    console.print("\n[bold magenta][DRY-RUN] No changes will be made.[/]")
+    console.print(f"[magenta]  Operation: {operation}[/]")
+    console.print(f"[magenta]  API Call:  {api_call}[/]")
+    for k, v in (parameters or {}).items():
+        console.print(f"[magenta]  Param:     {k} = {v}[/]")
+    console.print("[magenta]  Run without --dry-run to execute.[/]\n")
+
+
+def double_confirm(action: str, resource: str) -> None:
+    """Require two confirmations for a destructive operation."""
+    console.print(f"[bold yellow]⚠️  About to: {action} '{resource}'[/]")
+    typer.confirm(f"Confirm 1/2: {action} '{resource}'?", abort=True)
+    typer.confirm(
+        f"Confirm 2/2: really {action} '{resource}'? This may be irreversible.",
+        abort=True,
+    )
+
+
+def print_truncation_note(result: dict, noun: str) -> None:
+    """Print a visible warning when a listing envelope was capped.
+
+    The JSON already carries ``truncated``, but a human scrolling a long dump
+    will not spot it — and neither will a model summarising the terminal. Say
+    it in words, on the last line, where it cannot be missed.
+    """
+    if isinstance(result, dict) and result.get("truncated"):
+        console.print(
+            f"[yellow]… showing {result.get('returned')} of more {noun} — "
+            f"truncated, re-run with a higher --limit[/]"
+        )