contree-mcp 0.1.0__py3-none-any.whl

contree_mcp/resources/image_lineage.py

@@ -0,0 +1,46 @@
+import json
+from urllib.parse import unquote
+
+from contree_mcp.context import CLIENT
+
+
+async def image_lineage(image: str) -> str:
+    """View image parent-child relationships and history.
+
+    View image parent-child relationships and history. Free (no VM).
+
+    URI: contree://image/{image}/lineage
+
+    Returns lineage information including:
+    - parent: Immediate parent image
+    - children: Direct children of this image
+    - ancestors: Full parent chain up to root
+    - root: Root imported image
+    - depth: Number of ancestors
+    - is_known: Whether the image is in our lineage database
+    - data: Stored metadata (command, operation_id, etc.)
+
+    Example: contree://image/abc-123-def/lineage
+    """
+    cache = CLIENT.get().cache
+    # URL-decode image since it may contain encoded characters
+    decoded_image = unquote(image)
+
+    entry = await cache.get("image", decoded_image)
+    ancestors = await cache.get_ancestors("image", decoded_image)
+    children = await cache.get_children("image", decoded_image)
+
+    # Extract root from ancestors (last one) or self if no ancestors
+    root = ancestors[-1].key if ancestors else (entry.key if entry else None)
+
+    lineage_data = {
+        "image": decoded_image,
+        "parent": entry.data.get("parent_image") if entry else None,
+        "children": [c.key for c in children],
+        "ancestors": [a.key for a in ancestors],
+        "root": root,
+        "depth": len(ancestors),
+        "is_known": entry is not None,
+        "data": dict(entry.data) if entry else None,
+    }
+    return json.dumps(lineage_data, indent=2)

contree_mcp/resources/image_ls.py

@@ -0,0 +1,32 @@
+from urllib.parse import unquote
+
+from contree_mcp.context import CLIENT
+
+
+async def image_ls(image: str, path: str) -> str:
+    """List files and directories in a container image.
+
+    List files and directories in a container image. Free (no VM).
+    Output is ls -alh style text format.
+
+    URI: contree://image/{image}/ls/{path}
+
+    Where:
+    - image: Image UUID or tag prefixed with "tag:" (e.g., "tag:alpine:latest")
+    - path: Directory path without leading slash (e.g., "etc" or "usr/bin")
+    - For root directory, use path "."
+
+    Examples:
+    - contree://image/abc-123-def/ls/.
+    - contree://image/abc-123-def/ls/etc
+    - contree://image/abc-123-def/ls/usr/local/bin
+    - contree://image/tag:alpine:latest/ls/etc
+    """
+
+    client = CLIENT.get()
+    # URL-decode image and path since they may contain encoded characters
+    decoded_image = unquote(image)
+    decoded_path = unquote(path)
+    image_uuid = await client.resolve_image(decoded_image)
+    dir_path = "/" if decoded_path in (".", "") else "/" + decoded_path
+    return await client.list_directory_text(image_uuid, dir_path)

contree_mcp/resources/import_operation.py

@@ -0,0 +1,52 @@
+from contree_mcp.backend_types import ImportImageMetadata, OperationKind
+from contree_mcp.context import CLIENT
+
+
+async def import_operation(operation_id: str) -> str:
+    """
+    Read image import operation details. Free (no VM).
+
+    Return text in format:
+    ```
+    STATE: SUCCESS
+    RESULT_IMAGE: <uuid>
+    RESULT_TAG: latest
+    REGISTRY_URL: registry.example.com/repo/image:tag
+    ERROR:
+    multiline error message if any
+    ```
+
+    Strings might absent in case it's not applicable.
+
+    URI: contree://operations/import/{operation_id}
+
+    Example: contree://operations/import/op-abc-123-def
+    Returns:
+    ```
+    STATE: SUCCESS
+    RESULT_IMAGE: 550e8400-e29b-41d4-a716-446655440000
+    RESULT_TAG: latest
+    REGISTRY_URL: registry.example.com/repo/image:tag
+    """
+    client = CLIENT.get()
+    op = await client.get_operation(operation_id)
+    if op.kind != OperationKind.IMAGE_IMPORT:
+        raise ValueError(f"Operation {operation_id} is not an import operation (kind={op.kind})")
+
+    result = f"STATE: {op.status.value}"
+
+    if op.result and op.result.image:
+        result += f"\nRESULT_IMAGE: {op.result.image}"
+    if op.result and op.result.tag:
+        result += f"\nRESULT_TAG: {op.result.tag}"
+
+    # Extract registry URL from metadata
+    if isinstance(op.metadata, ImportImageMetadata):
+        registry_url = str(op.metadata.registry.url) if op.metadata.registry else None
+        if registry_url:
+            result += f"\nREGISTRY_URL: {registry_url}"
+
+    if op.error:
+        result += f"\nERROR:\n{op.error}"
+
+    return result

contree_mcp/resources/instance_operation.py

@@ -0,0 +1,52 @@
+import json
+
+from contree_mcp.backend_types import InstanceMetadata, OperationKind
+from contree_mcp.context import CLIENT
+
+
+async def instance_operation(operation_id: str) -> str:
+    """Read instance (command execution) operation details.
+
+    Read instance (command execution) operation details. Free (no VM).
+
+    URI: contree://operations/instance/{operation_id}
+
+    Returns cached operation data including:
+    - state: Operation state (SUCCESS, FAILED, etc.)
+    - exit_code: Command exit code
+    - stdout/stderr: Command output
+    - result_image: Output image UUID (if disposable=false)
+    - resources: CPU/memory usage statistics
+
+    Example: contree://operations/instance/op-abc-123-def
+    """
+    client = CLIENT.get()
+    # Use get_operation which checks cache first, then fetches from API
+    op = await client.get_operation(operation_id)
+
+    if op.kind != OperationKind.INSTANCE:
+        raise ValueError(f"Operation {operation_id} is not an instance operation (kind={op.kind})")
+
+    result_data: dict[str, object] = {
+        "state": op.status.value,
+    }
+
+    if op.error:
+        result_data["error"] = op.error
+
+    if op.result:
+        result_data["result_image"] = op.result.image
+        if op.result.tag:
+            result_data["result_tag"] = op.result.tag
+
+    # Extract instance-specific metadata
+    if isinstance(op.metadata, InstanceMetadata) and op.metadata.result:
+        instance_result = op.metadata.result
+        result_data["exit_code"] = instance_result.state.exit_code
+        result_data["timed_out"] = instance_result.state.timed_out
+        result_data["stdout"] = instance_result.stdout.text() if instance_result.stdout else ""
+        result_data["stderr"] = instance_result.stderr.text() if instance_result.stderr else ""
+        if instance_result.resources:
+            result_data["resources"] = instance_result.resources.model_dump()
+
+    return json.dumps(result_data, indent=2)

contree_mcp/resources/read_file.py

@@ -0,0 +1,33 @@
+import base64
+from urllib.parse import unquote
+
+from contree_mcp.context import CLIENT
+
+
+async def read_file(image: str, path: str) -> str:
+    """Read a file from a container image.
+
+    Read text files, config files, scripts, etc. without incurring VM costs.
+    Binary files will be returned as BASE64-encoded strings prefixed with "base64:".
+
+    URI: contree://image/{image}/read/{path}
+
+    Where:
+    - image: Image UUID or tag prefixed with "tag:" (e.g., "tag:alpine:latest")
+    - path: File path without leading slash (e.g., "etc/passwd")
+
+    Examples:
+    - contree://image/abc-123-def/read/etc/passwd
+    - contree://image/abc-123-def/read/usr/local/bin/python
+    - contree://image/tag:alpine:latest/read/etc/alpine-release
+    """
+    client = CLIENT.get()
+    image_uuid = await client.resolve_image(image)
+    file_path = "/" + unquote(path).lstrip("/")
+    content = await client.read_file(image_uuid, file_path)
+
+    try:
+        return content.decode("utf-8")
+    except (UnicodeDecodeError, AttributeError):
+        b64_content = base64.b64encode(content).decode("utf-8")
+        return f"base64:{b64_content}"

contree_mcp/resources/static.py

@@ -0,0 +1,12 @@
+from typing import Any
+
+from mcp.server.fastmcp.resources import Resource
+
+
+class StaticResource(Resource):
+    def __init__(self, content: str, /, **data: Any) -> None:
+        super().__init__(**data)
+        self._content = content
+
+    async def read(self) -> str | bytes:
+        return self._content

contree_mcp/server.py

@@ -0,0 +1,77 @@
+import contextvars
+import logging
+from contextlib import AsyncExitStack
+from functools import partial
+
+import uvicorn
+from starlette.requests import Request
+from starlette.responses import HTMLResponse
+
+from contree_mcp.app import create_mcp_app
+from contree_mcp.arguments import Parser, ServerMode
+from contree_mcp.cache import Cache
+from contree_mcp.client import ContreeClient
+from contree_mcp.context import CLIENT, FILES_CACHE, ContextMiddleware
+from contree_mcp.docs import generate_docs_html
+from contree_mcp.file_cache import FileCache
+from contree_mcp.resources.guide import SECTIONS
+
+log = logging.getLogger(__name__)
+
+
+async def index_page(docs_html: str, _: Request) -> HTMLResponse:
+    return HTMLResponse(docs_html)
+
+
+async def amain(parser: Parser) -> None:
+    async with AsyncExitStack() as stack:
+        # Initialize all dependencies
+        files_cache = await stack.enter_async_context(FileCache(db_path=parser.cache.files.expanduser()))
+        general_cache = await stack.enter_async_context(
+            Cache(
+                db_path=parser.cache.general.expanduser(),
+                retention_days=parser.cache.prune_days,
+            )
+        )
+        client = await stack.enter_async_context(
+            ContreeClient(base_url=parser.url, token=parser.token, cache=general_cache)
+        )
+
+        CLIENT.set(client)
+        FILES_CACHE.set(files_cache)
+
+        mcp = create_mcp_app()
+
+        log.debug("MCP app initialized: %s", CLIENT.get())
+
+        if parser.mode == ServerMode.HTTP:
+            log.info("Starting MCP server on http://%s:%d", parser.http.listen, parser.http.port)
+
+            # Generate docs HTML
+            tools = await mcp.list_tools()
+            templates = await mcp.list_resource_templates()
+            docs_html = generate_docs_html(
+                server_instructions=mcp.instructions or "",
+                tools=tools,
+                templates=templates,
+                guides=SECTIONS,
+                http_port=parser.http.port,
+            )
+
+            app = mcp.streamable_http_app()
+            app.add_middleware(ContextMiddleware, ctx=contextvars.copy_context())
+            app.add_route("/", partial(index_page, docs_html), methods=["GET"])
+
+            config = uvicorn.Config(
+                app,
+                host=parser.http.listen,
+                port=parser.http.port,
+                log_level="info",
+            )
+            server = uvicorn.Server(config)
+            await server.serve()
+        elif parser.mode == ServerMode.STDIO:
+            log.info("Starting MCP server in stdio mode")
+            await mcp.run_stdio_async()
+        else:
+            raise ValueError(f"Unsupported server mode: {parser.mode}")

contree_mcp/tools/__init__.py

@@ -0,0 +1,39 @@
+"""Contree MCP tools."""
+
+from .cancel_operation import cancel_operation
+from .download import download
+from .get_guide import get_guide
+from .get_image import get_image
+from .get_operation import get_operation
+from .import_image import import_image
+from .list_files import list_files
+from .list_images import list_images
+from .list_operations import list_operations
+from .read_file import read_file
+from .registry_auth import registry_auth
+from .registry_token_obtain import registry_token_obtain
+from .rsync import rsync
+from .run import run
+from .set_tag import set_tag
+from .upload import upload
+from .wait_operations import wait_operations
+
+__all__ = [
+    "cancel_operation",
+    "download",
+    "get_guide",
+    "get_image",
+    "get_operation",
+    "import_image",
+    "list_files",
+    "list_images",
+    "list_operations",
+    "read_file",
+    "registry_auth",
+    "registry_token_obtain",
+    "rsync",
+    "run",
+    "set_tag",
+    "upload",
+    "wait_operations",
+]

contree_mcp/tools/cancel_operation.py

@@ -0,0 +1,36 @@
+from pydantic import BaseModel, Field
+
+from contree_mcp.context import CLIENT
+
+
+class CancelOperationOutput(BaseModel):
+    cancelled: bool = Field(description="Whether cancellation succeeded")
+    operation_id: str = Field(description="UUID of the cancelled operation")
+
+
+async def cancel_operation(operation_id: str) -> CancelOperationOutput:
+    """
+    Cancel a running operation. Free (no VM).
+
+    TL;DR:
+    - PURPOSE: Stop operations taking too long or no longer needed
+    - COST: Free (no VM) - saves resources by stopping unnecessary work
+
+    USAGE:
+    - Stop long-running commands that are taking too long
+    - Cancel image imports that are stuck or no longer needed
+
+    RETURNS: cancelled, operation_id
+
+    GUIDES:
+    - [USEFUL] contree://guide/async - Async execution and cancellation
+    """
+
+    client = CLIENT.get()
+    result_status = await client.cancel_operation(operation_id)
+    # Check if operation was cancelled (CANCELLED status)
+    cancelled = result_status == "CANCELLED"
+    return CancelOperationOutput(
+        cancelled=cancelled,
+        operation_id=operation_id,
+    )

contree_mcp/tools/download.py

@@ -0,0 +1,128 @@
+import asyncio
+import contextlib
+import os
+import platform
+from collections.abc import AsyncIterable
+from pathlib import Path
+from queue import Queue
+from tempfile import mktemp
+
+from pydantic import BaseModel, ByteSize, Field
+
+from contree_mcp.context import CLIENT
+
+
+class DownloadSource(BaseModel):
+    image: str = Field(description="Image UUID")
+    path: str = Field(description="Path in container")
+
+
+class DownloadOutput(BaseModel):
+    success: bool = Field(description="Whether download succeeded")
+    source: DownloadSource = Field(description="Source image and path")
+    destination: str = Field(description="Local path where file was saved")
+    size: ByteSize = Field(description="File size in bytes")
+    executable: bool = Field(description="Whether file was made executable")
+
+
+async def async_file_writer(destination: Path, stream: AsyncIterable[bytes]) -> int:
+    queue: Queue[bytes | BaseException | None] = Queue(maxsize=16)
+    write_event = asyncio.Event()
+    loop = asyncio.get_running_loop()
+
+    def sync_writer(dest: Path) -> int:
+        total_bytes = 0
+        with dest.open("wb") as f:
+            while True:
+                match queue.get():
+                    case None:
+                        loop.call_soon_threadsafe(write_event.set)
+                        return total_bytes
+                    case BaseException():
+                        # Error occurred, close file and remove temp
+                        loop.call_soon_threadsafe(write_event.set)
+                        f.close()
+                        dest.unlink(missing_ok=True)
+                        return -1
+                    case bytes() as chunk:
+                        loop.call_soon_threadsafe(write_event.set)
+                        f.write(chunk)
+                        queue.task_done()
+                        total_bytes += len(chunk)
+
+    async def queue_waiter() -> None:
+        while queue.full():
+            write_event.clear()
+            # Circuit breaker to avoid deadlocks
+            with contextlib.suppress(asyncio.TimeoutError):
+                await asyncio.wait_for(write_event.wait(), timeout=1)
+
+    tmp_path = Path(mktemp(dir=destination.parent, prefix=".download-", suffix=".tmp"))
+    task = asyncio.create_task(asyncio.to_thread(sync_writer, tmp_path))
+    error: BaseException | None = None
+
+    try:
+        async for chunk in stream:
+            await queue_waiter()
+            queue.put_nowait(chunk)
+    except BaseException as e:
+        error = e
+    finally:
+        # Have to wait for queue to be drained before sending signal
+        await queue_waiter()
+        queue.put_nowait(error)  # None for success, exception for error
+
+    await task
+    if error is not None:
+        raise error
+
+    await asyncio.to_thread(os.replace, tmp_path, destination)
+    return task.result()
+
+
+async def download(
+    image: str,
+    path: str,
+    destination: str,
+    executable: bool = False,
+) -> DownloadOutput:
+    """
+    Download file from container image to local filesystem. Free (no VM).
+
+    TL;DR:
+    - PURPOSE: Extract files from container images to local filesystem
+    - EXECUTABLE: Set executable=true for binaries to run locally
+    - COST: Free (no VM)
+
+    USAGE:
+    - destination: Absolute path for downloaded file (~ expansion supported)
+    - Extract compiled binaries or build artifacts
+    - Save configuration files for local editing
+    - Retrieve logs or output files from completed runs
+
+    RETURNS: success, destination, size, size_human
+
+    GUIDES:
+    - [USEFUL] contree://guide/reference - Tool reference and resources
+    """
+    client = CLIENT.get()
+    image_uuid = await client.resolve_image(image)
+    dest_path = Path(os.path.expanduser(destination))
+    if not dest_path.is_absolute():
+        raise ValueError(f"destination must be an absolute path, got: {destination}")
+
+    dest_path.parent.mkdir(parents=True, exist_ok=True)
+
+    async with client.stream_file(image_uuid, path) as chunks:
+        file_size = await async_file_writer(dest_path, chunks)
+
+    if executable and platform.system() != "Windows":
+        dest_path.chmod(0o755)
+
+    return DownloadOutput(
+        success=True,
+        source=DownloadSource(image=image_uuid, path=path),
+        destination=str(dest_path),
+        size=ByteSize(file_size),
+        executable=executable,
+    )

contree_mcp/tools/get_guide.py

@@ -0,0 +1,54 @@
+from pydantic import BaseModel
+
+from contree_mcp.resources.guide import SECTIONS
+
+
+class GetGuideOutput(BaseModel):
+    section: str
+    content: str
+    available_sections: list[str]
+
+
+async def get_guide(section: str) -> GetGuideOutput:
+    """
+    Get agent guide sections for Contree best practices. Free (no VM).
+
+    TL;DR:
+    - PURPOSE: Access documentation and best practices for using Contree
+    - SECTIONS: workflow, reference, quickstart, state, async, tagging, errors
+    - COST: Free (no VM)
+
+    USAGE:
+    - Get workflow patterns: get_guide(section="workflow")
+    - Get tool reference: get_guide(section="reference")
+    - Get quick start examples: get_guide(section="quickstart")
+    - Get state management guide: get_guide(section="state")
+    - Get async execution guide: get_guide(section="async")
+    - Get tagging convention: get_guide(section="tagging")
+    - Get error handling guide: get_guide(section="errors")
+
+    RETURNS: section, content, available_sections
+
+    AVAILABLE SECTIONS:
+    - workflow: Complete workflow patterns with decision tree
+    - reference: Tool reference with parameters and data flow
+    - quickstart: Quick examples for common operations
+    - state: State management and rollback patterns
+    - async: Parallel execution and wait_operations
+    - tagging: Tagging convention for prepared environments
+    - errors: Error handling and debugging guide
+
+    RESOURCE ALTERNATIVE:
+    - contree://guide/{section} - Same content as MCP resource (if your agent supports resources)
+    """
+
+    available = sorted(SECTIONS.keys())
+
+    if section not in SECTIONS:
+        raise ValueError(f"Unknown guide section '{section}'. Available sections: {', '.join(available)}")
+
+    return GetGuideOutput(
+        section=section,
+        content=SECTIONS[section],
+        available_sections=available,
+    )

contree_mcp/tools/get_image.py

@@ -0,0 +1,30 @@
+from contree_mcp.backend_types import Image
+from contree_mcp.context import CLIENT
+
+
+async def get_image(image: str) -> Image:
+    """
+    Get image details by UUID or tag. Free (no VM).
+
+    TL;DR:
+    - PURPOSE: Verify image exists or resolve tag to UUID
+    - FORMAT: Use "tag:python:3.11" to look up by tag
+    - COST: Free (no VM)
+
+    USAGE:
+    - Look up image metadata (UUID, tag, creation time)
+    - Verify image exists before running commands
+    - Resolve tag to underlying UUID
+    - Prefer verifying an existing image before using import_image
+
+    RETURNS: uuid, tag, created_at
+
+    GUIDES:
+    - [USEFUL] contree://guide/quickstart - UUIDs vs tags guidance
+    """
+    client = CLIENT.get()
+    if image.startswith("tag:"):
+        img = await client.get_image_by_tag(image[4:])
+    else:
+        img = await client.get_image(image)
+    return Image(uuid=img.uuid, tag=img.tag, created_at=img.created_at)

contree_mcp/tools/get_operation.py

@@ -0,0 +1,26 @@
+from contree_mcp.backend_types import OperationResponse
+from contree_mcp.context import CLIENT
+
+
+async def get_operation(operation_id: str) -> OperationResponse:
+    """
+    Get status and result of an operation. Free (no VM).
+
+    TL;DR:
+    - PURPOSE: Poll async operations launched with wait=false
+    - PREFER: Use wait_operations for multiple operations
+    - COST: Free (no VM)
+
+    USAGE:
+    - Check status of async operations started with wait=false
+    - Retrieve stdout/stderr from completed command executions
+    - Get result_image UUID from non-disposable command runs
+
+    RETURNS: state, stdout, stderr, exit_code, result_image
+
+    GUIDES:
+    - [ESSENTIAL] contree://guide/async - Async execution and polling
+    """
+
+    client = CLIENT.get()
+    return await client.get_operation(operation_id)