contree-mcp 0.1.0__py3-none-any.whl

contree_mcp/tools/import_image.py

@@ -0,0 +1,99 @@
+from contree_mcp.auth import RegistryAuth, RegistryToken
+from contree_mcp.backend_types import OperationResponse
+from contree_mcp.context import CLIENT
+
+
+class RegistryAuthenticationError(Exception):
+    """Raised when registry authentication is required but not found."""
+
+    def __init__(self, registry: str):
+        self.registry = registry
+        super().__init__(
+            f"Not authenticated with '{registry}'. "
+            f"Run registry_token_obtain(registry_url='...') first to open the browser, "
+            f"then registry_auth(registry_url='...', username='...', token='...') to authenticate."
+        )
+
+
+async def import_image(
+    registry_url: str,
+    tag: str | None = None,
+    wait: bool = True,
+    i_accept_that_anonymous_access_might_be_rate_limited: bool = False,
+) -> OperationResponse | dict[str, str]:
+    """
+    Import OCI container image from registry (e.g., Docker Hub). Spawns microVM.
+
+    TL;DR:
+    - PURPOSE: Import a base image only when nothing suitable exists locally
+    - AUTH: Requires prior authentication via registry_auth() or anonymous access
+    - REUSE: Always check list_images first - reuse existing tags/UUIDs when possible
+    - COST: Highest-cost operation; can take dozens of minutes and incur microVM costs
+
+    AUTHENTICATION:
+    Before importing, you must authenticate with the registry:
+    1. Call registry_token_obtain(registry_url="...") to open browser for PAT creation
+    2. Wait for user to provide the token
+    3. Call registry_auth(registry_url="...", username="...", token="...") to store credentials
+
+    Anonymous access is possible but discouraged (registry provider rate limits).
+
+    USAGE:
+    - Avoid import_image when you can build on an existing base
+      (e.g., Ubuntu + apt/pip with disposable=false + set_tag)
+    - registry_url must be full URL with protocol prefix:
+      - docker://docker.io/library/alpine:latest
+      - docker://docker.io/library/python:3.11-slim
+      - docker://docker.io/library/ubuntu:22.04
+      - docker://ghcr.io/owner/image:tag
+    - Use returned UUID directly for subsequent operations
+    - Only assign tags to frequently-used images
+    - Tag format: `{scope}/{purpose}/{base}` where base includes its tag
+
+    RETURNS: result_image UUID, result_tag (if assigned)
+    - operation_id returned when wait=false
+
+    GUIDES:
+    - [ESSENTIAL] contree://guide/async - Async execution with wait=false
+    - [USEFUL] contree://guide/tagging - Agent tagging convention
+    """
+    client = CLIENT.get()
+
+    # Parse registry from URL
+    auth = RegistryAuth.from_url(registry_url)
+
+    username: str | None = None
+    password: str | None = None
+
+    # Look up credentials from cache
+    entry = await client.cache.get(kind="registry_token", key=auth.registry)
+
+    if entry is not None:
+        # Extract credentials from cache entry
+        registry_token = RegistryToken.model_validate(entry.data)
+
+        # Revalidate token before use (tokens can expire)
+        is_valid = await auth.validate_token(registry_token.username, registry_token.token)
+        if is_valid:
+            username = registry_token.username
+            password = registry_token.token
+        else:
+            # Remove invalid token from cache
+            await client.cache.delete(kind="registry_token", key=auth.registry)
+
+    # If no valid credentials and anonymous not allowed, raise error
+    if username is None and not i_accept_that_anonymous_access_might_be_rate_limited:
+        raise RegistryAuthenticationError(auth.registry)
+
+    operation_id = await client.import_image(
+        registry_url=registry_url,
+        tag=tag,
+        username=username,
+        password=password,
+    )
+
+    if wait:
+        # Client handles lineage caching automatically via _cache_lineage
+        return await client.wait_for_operation(operation_id)
+
+    return {"operation_id": operation_id}

contree_mcp/tools/list_files.py

@@ -0,0 +1,80 @@
+from pydantic import BaseModel
+
+from contree_mcp.context import CLIENT
+
+
+class FileEntry(BaseModel):
+    """File entry in directory listing."""
+
+    name: str
+    path: str
+    type: str  # "file", "directory", "symlink"
+    size: int
+    mode: str | None = None
+    target: str | None = None  # For symlinks
+
+
+class ListFilesOutput(BaseModel):
+    """Output of list_files tool."""
+
+    path: str
+    count: int
+    files: list[FileEntry]
+
+
+async def list_files(image: str, path: str = "/") -> ListFilesOutput:
+    """
+    List files and directories in a container image. Free (no VM).
+
+    TL;DR:
+    - PURPOSE: Inspect container filesystem without starting a VM
+    - ADVANTAGE: Instant results, no VM cost - use before run
+    - COST: Free (no VM)
+
+    USAGE:
+    - Explore image structure before running commands
+    - Verify expected files exist at target paths
+    - Check file permissions and symlink targets
+    - Prefer over run("ls") for simple listings
+
+    RETURNS: path, count, files[] with name, path, type, size, mode, target
+
+    GUIDES:
+    - [USEFUL] contree://guide/reference - Tool reference and resources
+    """
+
+    client = CLIENT.get()
+    image_uuid = await client.resolve_image(image)
+
+    # Normalize path
+    if not path.startswith("/"):
+        path = "/" + path
+    if path == "/.":
+        path = "/"
+
+    listing = await client.list_directory(image_uuid, path)
+
+    # Handle text response (shouldn't happen with as_text=False default)
+    if isinstance(listing, str):
+        return ListFilesOutput(path=path, count=0, files=[])
+
+    files = []
+    for f in listing.files:
+        if f.is_symlink:
+            file_type = "symlink"
+        elif f.is_dir:
+            file_type = "directory"
+        else:
+            file_type = "file"
+
+        entry = FileEntry(
+            name=f.path.rsplit("/", 1)[-1] if "/" in f.path else f.path,
+            path=f.path,
+            type=file_type,
+            size=f.size,
+            mode=oct(f.mode) if f.mode is not None else None,
+            target=f.symlink_to if f.is_symlink and f.symlink_to else None,
+        )
+        files.append(entry)
+
+    return ListFilesOutput(path=listing.path, count=len(files), files=files)

contree_mcp/tools/list_images.py

@@ -0,0 +1,50 @@
+from pydantic import BaseModel, Field
+
+from contree_mcp.backend_types import Image
+from contree_mcp.context import CLIENT
+
+
+class ListImagesOutput(BaseModel):
+    images: list[Image] = Field(description="List of images")
+
+
+async def list_images(
+    limit: int = 100,
+    offset: int = 0,
+    tagged: bool | None = None,
+    tag_prefix: str | None = None,
+    since: str | None = None,
+    until: str | None = None,
+) -> ListImagesOutput:
+    """
+    List available container images. Free (no VM).
+
+    TL;DR:
+    - PURPOSE: Find existing images before importing new ones
+    - FIRST STEP: Use this before import_image to avoid the most expensive operation (can take dozens of minutes)
+    - FILTER: Use tag_prefix to find specific image types
+    - COST: Free (no VM)
+
+    USAGE:
+    - Browse available images to find base images for commands
+    - Filter by tag prefix to find specific image types
+    - Use returned UUIDs directly in run
+    - Tag prefixes are typically `common/` or `<project>/`
+    - Examples: tag_prefix="common/python", tag_prefix="myproj/"
+
+    RETURNS: images[] with uuid, tag, created_at
+
+    GUIDES:
+    - [USEFUL] contree://guide/tagging - Agent tagging convention
+    """
+
+    client = CLIENT.get()
+    images = await client.list_images(
+        limit=limit,
+        offset=offset,
+        tagged=tagged,
+        tag_prefix=tag_prefix,
+        since=since,
+        until=until,
+    )
+    return ListImagesOutput(images=[Image(uuid=img.uuid, tag=img.tag, created_at=img.created_at) for img in images])

contree_mcp/tools/list_operations.py

@@ -0,0 +1,46 @@
+from pydantic import BaseModel, Field
+
+from contree_mcp.backend_types import OperationKind, OperationStatus, OperationSummary
+from contree_mcp.context import CLIENT
+
+
+class ListOperationsOutput(BaseModel):
+    operations: list[OperationSummary] = Field(description="List of operations")
+
+
+async def list_operations(
+    limit: int = 100,
+    status: OperationStatus | None = None,
+    kind: OperationKind | None = None,
+    since: str | None = None,
+) -> ListOperationsOutput:
+    """
+    List operations (command executions and image imports). Free (no VM).
+
+    TL;DR:
+    - PURPOSE: Monitor async operations launched with wait=false
+    - FILTER: Use status="running" to find active operations
+    - COST: Free (no VM)
+
+    USAGE:
+    - Monitor running operations
+    - Review history of command executions
+    - Filter by status (pending, running, success, failed, cancelled)
+    - Filter by kind (image_import, instance)
+
+    RETURNS: operations[] with uuid, kind, state, created_at
+
+    GUIDES:
+    - [ESSENTIAL] contree://guide/async - Async execution and polling
+    """
+
+    client = CLIENT.get()
+
+    operations = await client.list_operations(
+        limit=limit,
+        status=status,
+        kind=kind,
+        since=since,
+    )
+
+    return ListOperationsOutput(operations=operations)

contree_mcp/tools/read_file.py

@@ -0,0 +1,47 @@
+import base64
+
+from pydantic import BaseModel
+
+from contree_mcp.context import CLIENT
+
+
+class ReadFileOutput(BaseModel):
+    path: str
+    content: str
+    encoding: str = "utf-8"
+    bytes_size: int
+
+
+async def read_file(image: str, path: str) -> ReadFileOutput:
+    """
+    Read a file from a container image. Free (no VM).
+
+    TL;DR:
+    - PURPOSE: Inspect file contents without starting a VM
+    - ADVANTAGE: Instant access to configs and scripts - no VM cost
+    - COST: Free (no VM)
+
+    USAGE:
+    - Inspect configuration files to understand image setup
+    - Review scripts before execution to verify behavior
+    - Check expected content without downloading to local filesystem
+    - Prefer over run("cat") when you just need file contents
+
+    RETURNS: path, content, size, is_text
+
+    GUIDES:
+    - [USEFUL] contree://guide/reference - Tool reference and resources
+    """
+
+    client = CLIENT.get()
+    image_uuid = await client.resolve_image(image)
+    content = await client.read_file(image_uuid, path)
+
+    try:
+        content_str = content.decode("utf-8")
+        encoding = "utf-8"
+    except UnicodeDecodeError:
+        content_str = base64.b64encode(content).decode("utf-8")
+        encoding = "base64"
+
+    return ReadFileOutput(path=path, content=content_str, encoding=encoding, bytes_size=len(content))

contree_mcp/tools/registry_auth.py

@@ -0,0 +1,71 @@
+from typing import Literal
+
+from pydantic import BaseModel
+
+from contree_mcp.auth import RegistryAuth, RegistryToken
+from contree_mcp.context import CLIENT
+
+
+class RegistryAuthResponse(BaseModel):
+    """Response from registry_auth tool."""
+
+    status: Literal["success", "error"]
+    registry: str
+    message: str
+
+
+async def registry_auth(
+    registry_url: str,
+    username: str,
+    token: str,
+) -> RegistryAuthResponse:
+    """
+    Authenticate with a container registry via Personal Access Token.
+
+    TL;DR:
+    - PURPOSE: Validate and store registry credentials
+    - VALIDATION: Tests credentials via OCI /v2/ API
+    - STORAGE: Credentials persisted in local cache
+
+    URL PARSING:
+    - "docker://ghcr.io/org/image" -> ghcr.io
+    - "oci://registry.gitlab.com/org/image" -> registry.gitlab.com
+    - "alpine" or "library/alpine" -> docker.io (implicit)
+
+    USAGE:
+    1. Call registry_token_obtain(registry_url="...") -> opens browser
+    2. User creates read-only PAT in registry web UI
+    3. Call registry_auth(registry_url="...", username="...", token="...") -> validates and stores
+
+    RETURNS: status, message, registry (parsed hostname)
+    """
+    auth = RegistryAuth.from_url(registry_url)
+
+    # Validate credentials via OCI API
+    is_valid = await auth.validate_token(username, token)
+    if not is_valid:
+        return RegistryAuthResponse(
+            status="error",
+            registry=auth.registry,
+            message=(f"Invalid credentials for '{auth.registry}'. Please verify your username and PAT."),
+        )
+
+    # Store credentials in cache
+    client = CLIENT.get()
+    registry_token = RegistryToken(
+        registry=auth.registry,
+        username=username,
+        token=token,
+        scopes=["pull"],
+    )
+    await client.cache.put(
+        kind="registry_token",
+        key=auth.registry,
+        data=registry_token,
+    )
+
+    return RegistryAuthResponse(
+        status="success",
+        registry=auth.registry,
+        message=f"Authenticated with '{auth.registry}' as '{username}' successfully.",
+    )

contree_mcp/tools/registry_token_obtain.py

@@ -0,0 +1,80 @@
+import webbrowser
+from typing import Literal
+
+from pydantic import BaseModel
+
+from contree_mcp.auth import RegistryAuth
+
+
+class RegistryTokenObtainResponse(BaseModel):
+    """Response from registry_token_obtain tool."""
+
+    status: Literal["success", "error"]
+    registry: str
+    url: str = ""
+    message: str
+    agent_instruction: str = ""
+
+
+async def registry_token_obtain(
+    registry_url: str,
+) -> RegistryTokenObtainResponse:
+    """
+    Open browser to create a Personal Access Token for a container registry.
+
+    TL;DR:
+    - PURPOSE: Guide user to create a read-only PAT for the registry
+    - KNOWN REGISTRIES: Opens correct PAT creation page
+    - UNKNOWN REGISTRIES: Returns error with instructions
+
+    URL PARSING:
+    - "docker://ghcr.io/org/image" -> ghcr.io
+    - "oci://registry.gitlab.com/org/image" -> registry.gitlab.com
+    - "alpine" or "library/alpine" -> docker.io (implicit)
+
+    KNOWN REGISTRIES:
+    - docker.io -> Docker Hub PAT page
+    - ghcr.io -> GitHub fine-grained tokens page
+    - registry.gitlab.com -> GitLab PAT page
+    - gcr.io -> Google Cloud credentials page
+
+    RETURNS: status, message, url (if opened), registry (parsed hostname)
+    ERRORS: "Unknown registry. Please consult registry docs for token creation."
+
+    AGENT INSTRUCTIONS:
+    After calling this tool, you MUST STOP and wait for the user to:
+    1. Create a PAT in the opened browser page
+    2. Provide the token back to you
+    Then call registry_auth() with the provided token.
+    DO NOT proceed automatically - user interaction is required.
+    """
+    auth = RegistryAuth.from_url(registry_url)
+
+    if not auth.is_known:
+        return RegistryTokenObtainResponse(
+            status="error",
+            registry=auth.registry,
+            message=(
+                f"Unknown registry '{auth.registry}'. Please consult the registry documentation for token creation."
+            ),
+        )
+
+    pat_url = auth.pat_url
+    if pat_url:
+        webbrowser.open(str(pat_url))
+
+    return RegistryTokenObtainResponse(
+        status="success",
+        registry=auth.registry,
+        url=str(pat_url) if pat_url else "",
+        message=(
+            f"Browser opened to {pat_url}. "
+            f"Create a read-only PAT, then provide your username and token. "
+            f"After receiving the token, call "
+            f"registry_auth(registry_url='{registry_url}', username='<username>', token='<token>')."
+        ),
+        agent_instruction=(
+            "STOP HERE. Wait for user to create PAT and provide the token. "
+            "Do not proceed until user gives you the token."
+        ),
+    )

contree_mcp/tools/rsync.py

@@ -0,0 +1,46 @@
+from pathlib import Path
+
+from contree_mcp.context import CLIENT, FILES_CACHE
+
+
+async def rsync(
+    source: str,
+    destination: str,
+    exclude: list[str] | None = None,
+) -> int:
+    """
+    Sync local files to Contree for use in container instances. Free (no VM).
+
+    TL;DR:
+    - PURPOSE: Prepare files for run injection
+    - WORKFLOW: rsync -> get directory_state_id -> pass to run
+    - CACHE: Smart caching uploads only changed files
+    - EXCLUDE: Always exclude __pycache__, .git, node_modules, .venv
+
+    USAGE:
+    - source: Absolute path to local directory (~ expansion supported)
+    - Sync directory: source="/path/to/project", destination="/app"
+    - Exclude patterns: exclude=["__pycache__", "*.pyc", ".git"]
+
+    RETURNS: directory_state_id (int) for run tool
+
+    GUIDES:
+    - [ESSENTIAL] contree://guide/quickstart - File sync + execute patterns
+    """
+
+    client = CLIENT.get()
+    files_cache = FILES_CACHE.get()
+
+    source_path = Path(source).expanduser()
+    if not source_path.is_absolute():
+        raise ValueError(f"source must be an absolute path, got: {source}")
+
+    destination = destination.rstrip("/")
+    exclude = exclude or []
+
+    return await files_cache.sync_directory(
+        client=client,
+        path=source_path,
+        destination=destination,
+        excludes=exclude,
+    )

contree_mcp/tools/run.py

@@ -0,0 +1,97 @@
+from typing import Any
+
+from contree_mcp.backend_types import OperationResponse
+from contree_mcp.context import CLIENT, FILES_CACHE
+
+
+async def run(
+    command: str,
+    image: str,
+    shell: bool = True,
+    env: dict[str, str] | None = None,
+    cwd: str = "/root",
+    timeout: int = 30,
+    disposable: bool = True,
+    stdin: str | None = None,
+    directory_state_id: int | None = None,
+    files: dict[str, str] | None = None,
+    wait: bool = True,
+    truncate_output_at: int = 8000,
+) -> OperationResponse | dict[str, str]:
+    """
+    Execute command in isolated container. Spawns microVM.
+    Returns string with operation_id when wait=false or detailed result when wait=true.
+
+    TL;DR:
+    - PURPOSE: Run code in sandboxed environment with full root access
+    - IMAGE POLICY: Prefer existing images; import_image is the most expensive operation (can take dozens of minutes)
+      and should be a last resort. If you need Python on Ubuntu, install it once with disposable=false and
+      set_tag for reuse.
+    - WORKFLOW: Use rsync or upload first to inject files, then call run tool
+    - COST: Spawns microVM (~2-5s startup)
+
+    USAGE:
+    - Use list_images to find existing tags/UUIDs before import_image
+    - Run shell commands with stdout/stderr capture
+    - Chain commands using result_image from disposable=false
+    - If you intend reuse, tag result_image using the convention:
+      `{scope}/{purpose}/{base}` (base includes tag, e.g. python:3.11-slim)
+    - Launch async with wait=false, poll with get_operation or wait_operations
+    - Use env parameter for environment variables, not shell export
+
+    RETURNS: stdout, stderr, exit_code, result_image (when disposable=false)
+    - Use result_image UUID to chain subsequent commands
+    - operation_id returned when wait=false
+
+    GUIDES:
+    - [ESSENTIAL] contree://guide/quickstart - File sync + execute patterns
+    - [ESSENTIAL] contree://guide/async - Parallel execution
+    - [USEFUL] contree://guide/state - When to save vs discard
+    """
+    client = CLIENT.get()
+    files_cache = FILES_CACHE.get()
+
+    image_uuid = await client.resolve_image(image)
+
+    # Load files from directory state if provided
+    spawn_files: dict[str, dict[str, Any]] | None = None
+    if directory_state_id:
+        ds = await files_cache.get_directory_state(directory_state_id)
+        if ds is None:
+            raise ValueError(f"Directory state not found: {directory_state_id}")
+
+        ds_files = await files_cache.get_directory_state_files(directory_state_id)
+        if not ds_files:
+            raise ValueError(f"Directory state has no files: {directory_state_id}")
+
+        spawn_files = {}
+        for f in ds_files:
+            spawn_files[f.target_path] = {
+                "uuid": f.file_uuid,
+                "mode": oct(f.target_mode),
+            }
+
+    # Add direct file UUIDs (from upload)
+    if files:
+        if spawn_files is None:
+            spawn_files = {}
+        for path, uuid in files.items():
+            spawn_files[path] = {"uuid": uuid, "mode": "0o644"}
+
+    # Use spawn_instance when files are provided
+    # Note: Client handles lineage caching automatically via _cache_lineage
+    operation_id = await client.spawn_instance(
+        command=command,
+        image=image_uuid,
+        shell=shell,
+        env=env,
+        cwd=cwd,
+        timeout=timeout,
+        disposable=disposable,
+        stdin=stdin,
+        files=spawn_files,
+        truncate_output_at=truncate_output_at,
+    )
+    if wait:
+        return await client.wait_for_operation(operation_id)
+    return {"operation_id": operation_id}

contree_mcp/tools/set_tag.py

@@ -0,0 +1,31 @@
+from contree_mcp.backend_types import Image
+from contree_mcp.context import CLIENT
+
+
+async def set_tag(image_uuid: str, tag: str | None = None) -> Image:
+    """
+    Set or remove tag for container image. Free (no VM).
+    TL;DR:
+    - PURPOSE: Tag frequently-used images for reuse across sessions
+    - REMOVE: Omit tag parameter to remove existing tag
+    - COST: Free (no VM)
+
+    USAGE:
+    - Assign memorable name to frequently-used base images
+    - Omit tag to remove existing tag from image
+    - Prefer UUIDs directly for one-off operations
+    - Tag format: `{scope}/{purpose}/{base}` where base includes its tag
+    - Scope: `common` for reusable deps, or project name for project-specific
+    - Purpose: describe what you added (e.g., python-ml, web-deps)
+
+    RETURNS: uuid, tag, created_at
+
+    GUIDES:
+    - [ESSENTIAL] contree://guide/tagging - Agent tagging convention
+    """
+    client = CLIENT.get()
+    if tag:
+        img = await client.tag_image(image_uuid=image_uuid, tag=tag)
+    else:
+        img = await client.untag_image(image_uuid=image_uuid)
+    return Image(uuid=img.uuid, tag=img.tag, created_at=img.created_at)