hanzo-tools-s3 0.1.0__tar.gz

hanzo_tools_s3-0.1.0/.gitignore

@@ -0,0 +1,76 @@
+# IDE and editor
+.vscode
+.idea
+
+# Python
+*.egg-info
+__pycache__
+.mypy_cache
+.pytest_cache
+*.pyc
+.venv
+
+# Build
+build/
+dist
+_dev
+
+# Environment
+.env
+.envrc
+
+# Logs
+.prism.log
+codegen.log
+*.log
+
+# Package manager
+Brewfile.lock.json
+
+# Agent config files (symlinked from user home)
+LLM.md
+AGENTS.md
+CLAUDE.md
+GEMINI.md
+GROK.md
+QWEN.md
+
+# Local databases and state
+.hanzo/
+.grok/
+
+# Documentation build
+docs/.next/
+docs/out/
+docs/node_modules/
+
+# Training data and scripts (DO NOT COMMIT)
+training_dataset.jsonl
+scripts/full_extractor.py
+scripts/mega_extractor.py
+scripts/mega_full_extractor.py
+scripts/streaming_extractor.py
+scripts/supplement_extractor.py
+
+# Test files at root (experimental)
+test_post_quantum_*.py
+
+# Analysis documents (internal)
+HANZO_INNOVATION_OPPORTUNITIES.md
+POST_QUANTUM_CRYPTOGRAPHY_IMPLEMENTATION.md
+
+# Experimental cryptography (WIP)
+pkg/hanzo/src/hanzo/cryptography/
+site/
+
+# hygiene (untrack node_modules, block common build output)
+node_modules/
+**/node_modules/
+.pnpm-store/
+dist/
+.next/
+coverage/
+playwright-report/
+test-results/
+tmp/
+.DS_Store

hanzo_tools_s3-0.1.0/PKG-INFO

@@ -0,0 +1,32 @@
+Metadata-Version: 2.4
+Name: hanzo-tools-s3
+Version: 0.1.0
+Summary: Hanzo S3 MCP tool — buckets and objects on S3-compatible storage
+Author-email: Hanzo AI <dev@hanzo.ai>
+License: MIT
+Keywords: hanzo,mcp,object-storage,s3,seaweedfs,tools
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.12
+Requires-Dist: hanzo-s3>=1.0.0
+Requires-Dist: hanzo-tools-core>=0.1.0
+Description-Content-Type: text/markdown
+
+# hanzo-tools-s3
+
+MCP tool for Hanzo S3 — S3-compatible object storage (s3.hanzo.ai).
+
+Exposes a single `s3` tool with bucket and object actions: `buckets`,
+`make_bucket`, `remove_bucket`, `objects`, `stat`, `remove_object`, `presign`.
+
+Credentials come from the environment — inject them from KMS, never plaintext:
+
+```bash
+eval "$(hanzo kms inject <project> <env>)"   # exports HANZO_S3_*
+```
+
+Env: `HANZO_S3_ENDPOINT` (default `s3.hanzo.ai`), `HANZO_S3_ACCESS_KEY`,
+`HANZO_S3_SECRET_KEY`, `HANZO_S3_SECURE` (default `true`).

hanzo_tools_s3-0.1.0/README.md

@@ -0,0 +1,15 @@
+# hanzo-tools-s3
+
+MCP tool for Hanzo S3 — S3-compatible object storage (s3.hanzo.ai).
+
+Exposes a single `s3` tool with bucket and object actions: `buckets`,
+`make_bucket`, `remove_bucket`, `objects`, `stat`, `remove_object`, `presign`.
+
+Credentials come from the environment — inject them from KMS, never plaintext:
+
+```bash
+eval "$(hanzo kms inject <project> <env>)"   # exports HANZO_S3_*
+```
+
+Env: `HANZO_S3_ENDPOINT` (default `s3.hanzo.ai`), `HANZO_S3_ACCESS_KEY`,
+`HANZO_S3_SECRET_KEY`, `HANZO_S3_SECURE` (default `true`).

hanzo_tools_s3-0.1.0/hanzo_tools/s3/__init__.py

@@ -0,0 +1,7 @@
+"""Hanzo S3 Tools — object storage via MCP."""
+
+from .s3_tool import S3Tool
+
+TOOLS = [S3Tool]
+
+__all__ = ["S3Tool", "TOOLS"]

hanzo_tools_s3-0.1.0/hanzo_tools/s3/s3_tool.py

@@ -0,0 +1,245 @@
+"""MCP tool for Hanzo S3 — S3-compatible object storage.
+
+Single tool over the ``hanzo_s3`` client (S3-compatible, backed by
+hanzoai/s3) at s3.hanzo.ai.
+Buckets and objects: list, create, remove, stat, and presign.
+
+Auth: credentials from the environment — inject them from KMS, never store
+plaintext:
+
+    eval "$(hanzo kms inject <project> <env>)"   # exports HANZO_S3_*
+"""
+
+from __future__ import annotations
+
+import os
+import json
+import logging
+from typing import Any, Annotated, final
+from datetime import timedelta
+
+from pydantic import Field
+from mcp.server import FastMCP
+from mcp.server.fastmcp import Context as MCPContext
+
+from hanzo_tools.core.base import BaseTool
+
+logger = logging.getLogger(__name__)
+
+DESCRIPTION = """Hanzo S3 — S3-compatible object storage (s3.hanzo.ai).
+
+Credentials from env: HANZO_S3_ENDPOINT, HANZO_S3_ACCESS_KEY, HANZO_S3_SECRET_KEY
+(inject from KMS — never plaintext).
+
+Bucket actions:
+- buckets: List buckets
+- make_bucket: Create a bucket (params: bucket)
+- remove_bucket: Remove an empty bucket (params: bucket)
+
+Object actions:
+- objects: List objects (params: bucket, prefix, recursive)
+- stat: Object metadata (params: bucket, object_name)
+- remove_object: Delete an object (params: bucket, object_name)
+- presign: Presigned GET URL (params: bucket, object_name, expires)
+"""
+
+
+def _get_client():
+    """Build an S3 client from environment credentials."""
+    from hanzo_s3 import S3Client
+
+    endpoint = os.getenv("HANZO_S3_ENDPOINT", "s3.hanzo.ai")
+    access_key = os.getenv("HANZO_S3_ACCESS_KEY") or os.getenv("AWS_ACCESS_KEY_ID")
+    secret_key = os.getenv("HANZO_S3_SECRET_KEY") or os.getenv("AWS_SECRET_ACCESS_KEY")
+    secure = os.getenv("HANZO_S3_SECURE", "true").lower() not in ("0", "false", "no")
+
+    if not access_key or not secret_key:
+        raise RuntimeError(
+            "Missing S3 credentials. Set HANZO_S3_ACCESS_KEY and HANZO_S3_SECRET_KEY "
+            "(inject from KMS)."
+        )
+
+    return S3Client(endpoint, access_key=access_key, secret_key=secret_key, secure=secure)
+
+
+@final
+class S3Tool(BaseTool):
+    """MCP tool for Hanzo S3 object storage."""
+
+    @property
+    def name(self) -> str:
+        return "s3"
+
+    @property
+    def description(self) -> str:
+        return DESCRIPTION
+
+    async def call(
+        self,
+        ctx: MCPContext,
+        action: str = "buckets",
+        bucket: str | None = None,
+        object_name: str | None = None,
+        prefix: str = "",
+        recursive: bool = False,
+        expires: int = 3600,
+        **kwargs: Any,
+    ) -> str:
+        try:
+            if action == "buckets":
+                return self._buckets()
+            elif action == "make_bucket":
+                return self._make_bucket(bucket)
+            elif action == "remove_bucket":
+                return self._remove_bucket(bucket)
+            elif action == "objects":
+                return self._objects(bucket, prefix, recursive)
+            elif action == "stat":
+                return self._stat(bucket, object_name)
+            elif action == "remove_object":
+                return self._remove_object(bucket, object_name)
+            elif action == "presign":
+                return self._presign(bucket, object_name, expires)
+            else:
+                return json.dumps({
+                    "error": f"Unknown action: {action}",
+                    "available": [
+                        "buckets", "make_bucket", "remove_bucket",
+                        "objects", "stat", "remove_object", "presign",
+                    ],
+                })
+        except RuntimeError as e:
+            return json.dumps({"error": str(e)})
+        except Exception as e:
+            logger.exception(f"S3 tool error: {e}")
+            return json.dumps({"error": f"S3 error: {e}"})
+
+    # -- Bucket actions ------------------------------------------------------
+
+    def _buckets(self) -> str:
+        client = _get_client()
+        result = [
+            {
+                "name": b.name,
+                "creation_date": str(b.creation_date) if b.creation_date else None,
+            }
+            for b in client.list_buckets()
+        ]
+        return json.dumps({"count": len(result), "buckets": result}, indent=2)
+
+    def _make_bucket(self, bucket: str | None) -> str:
+        if not bucket:
+            return json.dumps({"error": "Required: bucket"})
+        client = _get_client()
+        client.make_bucket(bucket)
+        return json.dumps({"action": "created", "bucket": bucket}, indent=2)
+
+    def _remove_bucket(self, bucket: str | None) -> str:
+        if not bucket:
+            return json.dumps({"error": "Required: bucket"})
+        client = _get_client()
+        client.remove_bucket(bucket)
+        return json.dumps({"action": "removed", "bucket": bucket}, indent=2)
+
+    # -- Object actions ------------------------------------------------------
+
+    def _objects(self, bucket: str | None, prefix: str, recursive: bool) -> str:
+        if not bucket:
+            return json.dumps({"error": "Required: bucket"})
+        client = _get_client()
+        result = [
+            {
+                "key": o.object_name,
+                "size": None if o.is_dir else o.size,
+                "last_modified": str(o.last_modified) if o.last_modified else None,
+                "is_dir": o.is_dir,
+            }
+            for o in client.list_objects(bucket, prefix=prefix, recursive=recursive)
+        ]
+        return json.dumps(
+            {"bucket": bucket, "prefix": prefix, "count": len(result), "objects": result},
+            indent=2,
+        )
+
+    def _stat(self, bucket: str | None, object_name: str | None) -> str:
+        if not bucket or not object_name:
+            return json.dumps({"error": "Required: bucket, object_name"})
+        client = _get_client()
+        obj = client.stat_object(bucket, object_name)
+        return json.dumps({
+            "bucket": bucket,
+            "object_name": object_name,
+            "size": obj.size,
+            "etag": obj.etag,
+            "content_type": obj.content_type,
+            "last_modified": str(obj.last_modified) if obj.last_modified else None,
+        }, indent=2)
+
+    def _remove_object(self, bucket: str | None, object_name: str | None) -> str:
+        if not bucket or not object_name:
+            return json.dumps({"error": "Required: bucket, object_name"})
+        client = _get_client()
+        client.remove_object(bucket, object_name)
+        return json.dumps({"action": "removed", "bucket": bucket, "object_name": object_name}, indent=2)
+
+    def _presign(self, bucket: str | None, object_name: str | None, expires: int) -> str:
+        if not bucket or not object_name:
+            return json.dumps({"error": "Required: bucket, object_name"})
+        client = _get_client()
+        url = client.presigned_get_object(
+            bucket, object_name, expires=timedelta(seconds=expires)
+        )
+        return json.dumps({"bucket": bucket, "object_name": object_name, "url": url}, indent=2)
+
+    # -- Registration --------------------------------------------------------
+
+    def register(self, mcp_server: FastMCP) -> None:
+        """Register S3 tool with explicit parameters."""
+        tool_instance = self
+
+        @mcp_server.tool(
+            name="s3",
+            description=DESCRIPTION,
+        )
+        async def s3(
+            action: Annotated[
+                str,
+                Field(
+                    description=(
+                        "Action to perform. "
+                        "Buckets: buckets, make_bucket, remove_bucket. "
+                        "Objects: objects, stat, remove_object, presign."
+                    ),
+                ),
+            ] = "buckets",
+            bucket: Annotated[
+                str | None,
+                Field(description="Bucket name"),
+            ] = None,
+            object_name: Annotated[
+                str | None,
+                Field(description="Object key (for stat, remove_object, presign)"),
+            ] = None,
+            prefix: Annotated[
+                str,
+                Field(description="Object key prefix (for objects)"),
+            ] = "",
+            recursive: Annotated[
+                bool,
+                Field(description="Recurse into prefixes (for objects)"),
+            ] = False,
+            expires: Annotated[
+                int,
+                Field(description="Presigned URL lifetime in seconds (for presign)"),
+            ] = 3600,
+            ctx: MCPContext = None,
+        ) -> str:
+            return await tool_instance.call(
+                ctx,
+                action=action,
+                bucket=bucket,
+                object_name=object_name,
+                prefix=prefix,
+                recursive=recursive,
+                expires=expires,
+            )

hanzo_tools_s3-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[project]
+name = "hanzo-tools-s3"
+version = "0.1.0"
+description = "Hanzo S3 MCP tool — buckets and objects on S3-compatible storage"
+readme = "README.md"
+requires-python = ">=3.12"
+license = { text = "MIT" }
+authors = [{ name = "Hanzo AI", email = "dev@hanzo.ai" }]
+keywords = ["hanzo", "mcp", "s3", "seaweedfs", "object-storage", "tools"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+
+dependencies = [
+    "hanzo-tools-core>=0.1.0",
+    "hanzo-s3>=1.0.0",
+]
+
+[project.entry-points."hanzo.tools"]
+s3 = "hanzo_tools.s3:TOOLS"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["hanzo_tools"]

hanzo_tools_s3-0.1.0/tests/test_s3_tool.py

@@ -0,0 +1,138 @@
+"""S3Tool test suite — action routing, validation, client wiring."""
+
+import json
+from datetime import datetime
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from hanzo_tools.s3.s3_tool import S3Tool
+
+
+@pytest.fixture
+def tool():
+    return S3Tool()
+
+
+@pytest.fixture
+def ctx():
+    return MagicMock()
+
+
+def _patch_client(client):
+    return patch("hanzo_tools.s3.s3_tool._get_client", return_value=client)
+
+
+class TestProperties:
+    def test_name(self, tool):
+        assert tool.name == "s3"
+
+    def test_description_sections(self, tool):
+        for section in ("Bucket actions", "Object actions"):
+            assert section in tool.description
+
+
+class TestActionRouting:
+    @pytest.mark.asyncio
+    async def test_unknown_action_returns_error(self, tool, ctx):
+        result = json.loads(await tool.call(ctx, action="bogus"))
+        assert "Unknown action" in result["error"]
+
+    @pytest.mark.asyncio
+    async def test_unknown_action_lists_available(self, tool, ctx):
+        result = json.loads(await tool.call(ctx, action="bogus"))
+        assert set(result["available"]) == {
+            "buckets", "make_bucket", "remove_bucket",
+            "objects", "stat", "remove_object", "presign",
+        }
+
+
+class TestBuckets:
+    @pytest.mark.asyncio
+    async def test_buckets(self, tool, ctx):
+        client = MagicMock()
+        bucket = MagicMock(name="hanzo-space", creation_date=datetime(2026, 1, 1))
+        bucket.name = "hanzo-space"
+        client.list_buckets.return_value = [bucket]
+        with _patch_client(client):
+            result = json.loads(await tool.call(ctx, action="buckets"))
+        assert result["count"] == 1
+        assert result["buckets"][0]["name"] == "hanzo-space"
+
+    @pytest.mark.asyncio
+    async def test_make_bucket_requires_name(self, tool, ctx):
+        result = json.loads(await tool.call(ctx, action="make_bucket"))
+        assert "Required" in result["error"]
+
+    @pytest.mark.asyncio
+    async def test_make_bucket(self, tool, ctx):
+        client = MagicMock()
+        with _patch_client(client):
+            result = json.loads(await tool.call(ctx, action="make_bucket", bucket="b1"))
+        client.make_bucket.assert_called_once_with("b1")
+        assert result["action"] == "created"
+
+    @pytest.mark.asyncio
+    async def test_remove_bucket(self, tool, ctx):
+        client = MagicMock()
+        with _patch_client(client):
+            result = json.loads(await tool.call(ctx, action="remove_bucket", bucket="b1"))
+        client.remove_bucket.assert_called_once_with("b1")
+        assert result["action"] == "removed"
+
+
+class TestObjects:
+    @pytest.mark.asyncio
+    async def test_objects_requires_bucket(self, tool, ctx):
+        result = json.loads(await tool.call(ctx, action="objects"))
+        assert "Required" in result["error"]
+
+    @pytest.mark.asyncio
+    async def test_objects(self, tool, ctx):
+        client = MagicMock()
+        obj = MagicMock(object_name="a.txt", size=12, is_dir=False,
+                        last_modified=datetime(2026, 1, 1))
+        client.list_objects.return_value = [obj]
+        with _patch_client(client):
+            result = json.loads(await tool.call(ctx, action="objects", bucket="b1", prefix="a"))
+        assert result["count"] == 1
+        assert result["objects"][0]["key"] == "a.txt"
+        client.list_objects.assert_called_once_with("b1", prefix="a", recursive=False)
+
+    @pytest.mark.asyncio
+    async def test_stat(self, tool, ctx):
+        client = MagicMock()
+        client.stat_object.return_value = MagicMock(
+            size=99, etag="abc", content_type="text/plain",
+            last_modified=datetime(2026, 1, 1),
+        )
+        with _patch_client(client):
+            result = json.loads(await tool.call(ctx, action="stat", bucket="b1", object_name="a.txt"))
+        assert result["size"] == 99
+        assert result["etag"] == "abc"
+
+    @pytest.mark.asyncio
+    async def test_remove_object(self, tool, ctx):
+        client = MagicMock()
+        with _patch_client(client):
+            result = json.loads(await tool.call(ctx, action="remove_object", bucket="b1", object_name="a.txt"))
+        client.remove_object.assert_called_once_with("b1", "a.txt")
+        assert result["action"] == "removed"
+
+    @pytest.mark.asyncio
+    async def test_presign(self, tool, ctx):
+        client = MagicMock()
+        client.presigned_get_object.return_value = "https://s3.hanzo.ai/b1/a.txt?sig=x"
+        with _patch_client(client):
+            result = json.loads(await tool.call(ctx, action="presign", bucket="b1", object_name="a.txt"))
+        assert result["url"].startswith("https://s3.hanzo.ai/")
+
+
+class TestCredentials:
+    @pytest.mark.asyncio
+    async def test_missing_creds_errors(self, tool, ctx, monkeypatch):
+        for var in ("HANZO_S3_ACCESS_KEY", "HANZO_S3_SECRET_KEY",
+                    "AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY"):
+            monkeypatch.delenv(var, raising=False)
+        result = json.loads(await tool.call(ctx, action="buckets"))
+        assert "credentials" in result["error"].lower()