contree-mcp 0.1.0__py3-none-any.whl

contree_mcp/__main__.py

@@ -0,0 +1,25 @@
+import asyncio
+import logging
+import os
+import sys
+
+from contree_mcp.arguments import Parser
+from contree_mcp.server import amain
+
+
+def main() -> None:
+    parser = Parser(
+        config_files=[os.getenv("CONTREE_MCP_CONFIG", "~/.config/contree/mcp.ini")],
+        auto_env_var_prefix="CONTREE_MCP_",
+    )
+    parser.parse_args()
+
+    logging.basicConfig(level=parser.log_level, format="[%(levelname)s] %(message)s", stream=sys.stderr)
+    try:
+        asyncio.run(amain(parser))
+    except KeyboardInterrupt:
+        logging.info("Gracefully exited on keyboard interrupt")
+
+
+if __name__ == "__main__":
+    main()

contree_mcp/app.py

@@ -0,0 +1,240 @@
+"""
+## MANDATORY WORKFLOW
+
+Every task MUST follow this sequence:
+
+### Step 1: CHECK for Prepared Environment
+```
+list_images(tag_prefix="common/")
+```
+Search for existing prepared images before creating new ones.
+
+### Step 2: PREPARE Environment (if not found)
+```
+import_image(registry_url="docker://python:3.11-slim")
+run(command="pip install ...", image="<uuid>", disposable=false)
+set_tag(image_uuid="<result>", tag="common/python-ml/python:3.11-slim")
+```
+Build and TAG prepared images for reuse. CRITICAL: Use `disposable=false` to save state.
+
+### Step 3: EXECUTE Task
+```
+run(command="...", image="tag:common/python-ml/python:3.11-slim")
+```
+Use tagged image for efficient execution.
+
+---
+
+## Tagging Convention
+
+```
+{scope}/{purpose}/{base}:{tag}
+```
+
+| Component | Description | Examples |
+|-----------|-------------|----------|
+| `{scope}` | `common` or project name | `common`, `myproject` |
+| `{purpose}` | What was added/configured | `rust-toolchain`, `python-ml`, `web-deps` |
+| `{base}:{tag}` | Original base image | `ubuntu:noble`, `python:3.11-slim` |
+
+**Examples:**
+- `common/rust-toolchain/ubuntu:noble` - Ubuntu with Rust
+- `common/python-ml/python:3.11-slim` - Python with ML libraries
+- `myproject/dev-env/python:3.11-slim` - Project-specific setup
+
+---
+
+## NEVER DO THESE
+
+| Anti-pattern | Consequence | Correct approach |
+|--------------|-------------|------------------|
+| Import without checking | Wastes 10s-30min on duplicate imports | `list_images(tag_prefix="...")` first |
+| Skip tagging prepared images | Rebuilds from scratch next time | `set_tag()` after installing deps |
+| Chain commands in one run | Cannot rollback individual steps | One step per `run` |
+| Use `disposable=true` for installs | Loses all installed packages | `disposable=false` for setup |
+
+---
+
+## Tool Cost Reference
+
+| Tool | Cost | Notes |
+|------|------|-------|
+| `run` | VM (~2-5s) | Command execution |
+| `import_image` | VM (~10-30s) | Image pull from registry |
+| `rsync`, `upload`, `download` | Free | File transfer operations |
+| `list_images`, `get_image`, `set_tag` | Free | Image metadata |
+| `list_files`, `read_file` | Free | Inspect container filesystem |
+| `get_operation`, `list_operations`, `wait_operations`, `cancel_operation` | Free | Async management |
+| `get_guide` | Free | Access documentation |
+
+**Cost Optimization:** Use `list_files`/`read_file` instead of `run("ls")`/`run("cat")`.
+
+---
+
+## Image Inspection (Free)
+
+Inspect container filesystem without VM cost:
+
+```
+list_files(image="<uuid>", path="/etc")       # List directory contents
+read_file(image="<uuid>", path="/etc/passwd") # Read file contents
+```
+
+Prefer these over `run("ls ...")`/`run("cat ...")` for simple inspection.
+
+---
+
+## Guides
+
+Access documentation via resource URI or tool:
+
+| Guide | Resource URI | Tool Alternative |
+|-------|--------------|------------------|
+| Workflow patterns | `contree://guide/workflow` | `get_guide(section="workflow")` |
+| Async execution | `contree://guide/async` | `get_guide(section="async")` |
+| Tagging convention | `contree://guide/tagging` | `get_guide(section="tagging")` |
+| Tool reference | `contree://guide/reference` | `get_guide(section="reference")` |
+| Error handling | `contree://guide/errors` | `get_guide(section="errors")` |
+
+Use resources if supported by your agent runtime, otherwise use `get_guide()`.
+"""
+
+import re
+from collections.abc import Awaitable, Callable
+from textwrap import dedent
+from typing import Any
+
+from mcp.server import FastMCP
+from mcp.server.fastmcp.prompts import Prompt
+from mcp.server.fastmcp.resources import ResourceTemplate
+from pydantic import AnyUrl
+
+from contree_mcp import prompts
+
+from . import resources, tools
+
+
+class PathResourceTemplate(ResourceTemplate):
+    """Resource template that supports path parameters with slashes.
+
+    FastMCP's default ResourceTemplate uses [^/]+ for parameters, which doesn't
+    match paths containing slashes. This subclass overrides the matches() method
+    to use .+ for the last parameter named 'path', allowing paths like 'etc/passwd'.
+    """
+
+    def matches(self, uri: str) -> dict[str, Any] | None:
+        """Check if URI matches template and extract parameters.
+
+        Uses .+ for the last {path} parameter to capture paths with slashes.
+        """
+        # Build regex pattern, using .+ for the last {path} parameter
+        pattern = self.uri_template
+
+        # Find all parameter names
+        param_names = re.findall(r"\{(\w+)\}", pattern)
+
+        for i, param in enumerate(param_names):
+            is_last = i == len(param_names) - 1
+            is_path = param == "path"
+
+            if is_last and is_path:
+                # Last path parameter: match anything including slashes
+                pattern = pattern.replace(f"{{{param}}}", f"(?P<{param}>.+)")
+            else:
+                # Regular parameter: don't match slashes
+                pattern = pattern.replace(f"{{{param}}}", f"(?P<{param}>[^/]+)")
+
+        match = re.match(f"^{pattern}$", uri)
+        if match:
+            return match.groupdict()
+        return None
+
+
+def register_resource_template(mcp: FastMCP, url: str, resource_template_func: Callable[..., Awaitable[Any]]) -> None:
+    """
+    Register a resource template with the MCP app.
+
+    Uses PathResourceTemplate for URLs containing {path} to support
+    paths with slashes (e.g., etc/passwd) without URL encoding.
+    """
+    description = dedent(resource_template_func.__doc__ or "") or ""
+
+    # Use PathResourceTemplate for URLs with {path} parameter
+    if "{path}" in url:
+        template = PathResourceTemplate.from_function(
+            resource_template_func,
+            uri_template=url,
+            description=description,
+        )
+        # Directly add to resource manager's templates dict
+        mcp._resource_manager._templates[url] = template
+    else:
+        # Use standard FastMCP registration
+        decorator = mcp.resource(url, description=description)
+        decorator(resource_template_func)
+
+
+def register_tool(mcp: FastMCP, tool_func: Callable[..., Awaitable[Any]], **kwargs: Any) -> None:
+    mcp.add_tool(tool_func, description=dedent(tool_func.__doc__ or "") or "", **kwargs)
+
+
+def create_mcp_app(**kwargs: Any) -> FastMCP:
+    mcp = FastMCP(
+        name="contree-mcp",
+        instructions=dedent(__doc__).strip(),
+        streamable_http_path="/mcp",
+        json_response=True,
+        **kwargs,
+    )
+
+    register_tool(mcp, tools.list_images)
+    register_tool(mcp, tools.registry_token_obtain)
+    register_tool(mcp, tools.registry_auth)
+    register_tool(mcp, tools.import_image)
+    register_tool(mcp, tools.get_image)
+    register_tool(mcp, tools.set_tag)
+    register_tool(mcp, tools.run)
+    register_tool(mcp, tools.rsync)
+    register_tool(mcp, tools.upload)
+    register_tool(mcp, tools.download)
+    register_tool(mcp, tools.get_operation)
+    register_tool(mcp, tools.list_operations)
+    register_tool(mcp, tools.wait_operations)
+    register_tool(mcp, tools.cancel_operation)
+
+    # some agents can not use resources, so we expose these as tools too
+    register_tool(mcp, tools.list_files)
+    register_tool(mcp, tools.read_file)
+    register_tool(mcp, tools.get_guide)
+
+    mcp.add_prompt(Prompt.from_function(prompts.prepare_environment, name="prepare-environment"))
+    mcp.add_prompt(Prompt.from_function(prompts.run_python, name="run-python"))
+    mcp.add_prompt(Prompt.from_function(prompts.run_shell, name="run-shell"))
+    mcp.add_prompt(Prompt.from_function(prompts.sync_and_run, name="sync-and-run"))
+    mcp.add_prompt(Prompt.from_function(prompts.install_packages, name="install-packages"))
+    mcp.add_prompt(Prompt.from_function(prompts.parallel_tasks, name="parallel-tasks"))
+    mcp.add_prompt(Prompt.from_function(prompts.build_project, name="build-project"))
+    mcp.add_prompt(Prompt.from_function(prompts.debug_failure, name="debug-failure"))
+    mcp.add_prompt(Prompt.from_function(prompts.inspect_image, name="inspect-image"))
+    mcp.add_prompt(Prompt.from_function(prompts.multi_stage_build, name="multi-stage-build"))
+
+    register_resource_template(mcp, "contree://image/{image}/read/{path}", resources.read_file)
+    register_resource_template(mcp, "contree://image/{image}/ls/{path}", resources.image_ls)
+    register_resource_template(mcp, "contree://image/{image}/lineage", resources.image_lineage)
+    register_resource_template(mcp, "contree://operations/instance/{operation_id}", resources.instance_operation)
+    register_resource_template(mcp, "contree://operations/import/{operation_id}", resources.import_operation)
+
+    # Register guide sections as static resources for discovery
+    for section, content in resources.SECTIONS.items():
+        mcp.add_resource(
+            resources.StaticResource(
+                content,
+                uri=AnyUrl(f"contree://guide/{section}"),
+                name=section,
+                title=f"Contree Guide: {section.replace('-', ' ').title()}",
+                description=f"Guide section on {section.replace('-', ' ')}",
+                mime_type="text/markdown",
+            )
+        )
+
+    return mcp

contree_mcp/arguments.py

@@ -0,0 +1,35 @@
+from enum import Enum
+from pathlib import Path
+
+import argclass
+
+
+class ServerMode(str, Enum):
+    STDIO = "stdio"
+    HTTP = "http"
+
+
+class HTTPGroup(argclass.Group):
+    listen: str = argclass.Argument(default="127.0.0.1")
+    port: int = argclass.Argument(default=9452)
+
+
+class Cache(argclass.Group):
+    files: Path = Path("~") / ".cache" / "contree_mcp" / "files.db"
+    general: Path = Path("~") / ".cache" / "contree_mcp" / "cache.db"
+    prune_days: int = argclass.Argument(
+        default=60,
+        help="Delete cached entries older than this many days",
+    )
+
+
+class Parser(argclass.Parser):
+    url: str = argclass.Argument(default="https://contree.dev", help="Contree API base URL")
+    token: str = argclass.Argument(secret=True, help="Contree API authentication token", required=True)
+    mode: ServerMode = argclass.EnumArgument(
+        ServerMode, default=ServerMode.STDIO, lowercase=True, help="Server transport mode"
+    )
+
+    log_level: int = argclass.LogLevel
+    http: HTTPGroup = HTTPGroup()
+    cache: Cache = Cache()

contree_mcp/auth/__init__.py

@@ -0,0 +1,2 @@
+from .registry import RegistryAuth as RegistryAuth
+from .registry import RegistryToken as RegistryToken

contree_mcp/auth/registry.py

@@ -0,0 +1,236 @@
+from __future__ import annotations
+
+import re
+import webbrowser
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from types import MappingProxyType
+from typing import cast
+
+import httpx
+from httpx import URL
+from pydantic import BaseModel, Field
+
+# Known registries and their PAT creation URLs
+KNOWN_REGISTRIES: Mapping[str, URL] = MappingProxyType(
+    {
+        "docker.io": URL("https://app.docker.com/settings/personal-access-tokens"),
+        "ghcr.io": URL("https://github.com/settings/tokens?type=beta"),
+        "registry.gitlab.com": URL("https://gitlab.com/-/user_settings/personal_access_tokens"),
+        "gcr.io": URL("https://console.cloud.google.com/apis/credentials"),
+        "us.gcr.io": URL("https://console.cloud.google.com/apis/credentials"),
+        "eu.gcr.io": URL("https://console.cloud.google.com/apis/credentials"),
+        "asia.gcr.io": URL("https://console.cloud.google.com/apis/credentials"),
+    }
+)
+
+# Registry hostname aliases (some registries have different API hostnames)
+REGISTRY_API_HOSTS: Mapping[str, str] = MappingProxyType({"docker.io": "registry-1.docker.io"})
+
+
+@dataclass
+class AuthEndpoint:
+    """Authentication endpoint discovered from registry /v2/ response."""
+
+    realm: str  # Token endpoint URL
+    service: str  # Service name for token request
+
+
+@dataclass
+class RegistryAuth:
+    """OCI registry authentication handler.
+
+    Provides methods for token discovery, validation, and exchange
+    using the OCI distribution spec.
+    """
+
+    registry: str
+    _endpoint: AuthEndpoint | None = field(default=None, repr=False)
+
+    @classmethod
+    def from_url(cls, registry_url: str) -> RegistryAuth:
+        """Create RegistryAuth from an image URL.
+
+        Note: oci:// scheme is transparently converted to docker:// (same protocol)
+
+        Examples:
+        - "docker://ghcr.io/org/image:tag" -> RegistryAuth(registry="ghcr.io")
+        - "oci://registry.gitlab.com/org/img" -> RegistryAuth(registry="registry.gitlab.com")
+        - "myorg/myimage:latest" -> RegistryAuth(registry="docker.io")
+        - "alpine" -> RegistryAuth(registry="docker.io")
+        """
+        # Normalize oci:// to docker://
+        if registry_url.startswith("oci://"):
+            registry_url = "docker://" + registry_url[6:]
+
+        # If no scheme, it's a bare image name -> docker.io
+        if "://" not in registry_url:
+            return cls(registry="docker.io")
+
+        # Use httpx.URL for parsing
+        url = httpx.URL(registry_url)
+        return cls(registry=url.host or "docker.io")
+
+    @property
+    def api_host(self) -> str:
+        """Get the API hostname for this registry.
+
+        Some registries (like docker.io) use a different hostname for API calls.
+        """
+        return REGISTRY_API_HOSTS.get(self.registry, self.registry)
+
+    @property
+    def pat_url(self) -> str | None:
+        """Get PAT creation URL for this registry.
+
+        Returns None if registry is not in the known list.
+        """
+        url = KNOWN_REGISTRIES.get(self.registry)
+        return str(url) if url is not None else None
+
+    @property
+    def is_known(self) -> bool:
+        """Check if this registry is in the known list."""
+        return self.registry in KNOWN_REGISTRIES
+
+    def open_pat_page(self) -> str | None:
+        """Open browser to PAT creation page.
+
+        Returns the URL if opened, None if registry is unknown.
+        """
+        url = self.pat_url
+        if url:
+            webbrowser.open(url)
+        return url
+
+    async def discover_endpoint(self) -> AuthEndpoint:
+        """Discover token endpoint from registry's /v2/ response.
+
+        Calls the registry's /v2/ endpoint and parses the Www-Authenticate header
+        to find the token realm and service. Caches the result for reuse.
+        """
+        if self._endpoint is not None:
+            return self._endpoint
+
+        url = f"https://{self.api_host}/v2/"
+
+        async with httpx.AsyncClient() as client:
+            response = await client.get(url, follow_redirects=True)
+
+            if response.status_code == 401:
+                www_auth = response.headers.get("Www-Authenticate", "")
+                endpoint = self._parse_www_authenticate(www_auth)
+                if endpoint:
+                    self._endpoint = endpoint
+                    return endpoint
+
+            # If we get 200, try catalog request to get auth info
+            if response.status_code == 200:
+                catalog_url = f"https://{self.api_host}/v2/_catalog"
+                catalog_response = await client.get(catalog_url, follow_redirects=True)
+                if catalog_response.status_code == 401:
+                    www_auth = catalog_response.headers.get("Www-Authenticate", "")
+                    endpoint = self._parse_www_authenticate(www_auth)
+                    if endpoint:
+                        self._endpoint = endpoint
+                        return endpoint
+
+        raise ValueError(f"Could not discover auth endpoint for registry {self.registry}")
+
+    async def validate_token(self, username: str, token: str) -> bool:
+        """Validate token by requesting a token from the auth endpoint.
+
+        Args:
+            username: Registry username
+            token: Personal Access Token
+
+        Returns True if the token is valid and can be used for authentication.
+        """
+        try:
+            endpoint = await self.discover_endpoint()
+        except ValueError:
+            return False
+
+        async with httpx.AsyncClient() as client:
+            response = await client.get(
+                endpoint.realm,
+                params={"service": endpoint.service},
+                auth=httpx.BasicAuth(username, token),
+            )
+            return response.status_code == 200
+
+    async def get_bearer_token(self, username: str, token: str, scope: str) -> str | None:
+        """Exchange stored PAT for a scoped registry bearer token.
+
+        Args:
+            username: Registry username
+            token: Personal Access Token
+            scope: Scope string (e.g., "repository:myorg/myimage:pull")
+
+        Returns:
+            Bearer token for the specified scope, or None if authentication failed
+        """
+        endpoint = await self.discover_endpoint()
+
+        params = {
+            "service": endpoint.service,
+            "scope": scope,
+        }
+
+        async with httpx.AsyncClient() as client:
+            response = await client.get(
+                endpoint.realm,
+                params=params,
+                auth=httpx.BasicAuth(username, token),
+            )
+            if response.status_code != 200:
+                return None
+            return cast(str | None, response.json().get("token"))
+
+    @staticmethod
+    def _parse_www_authenticate(header: str) -> AuthEndpoint | None:
+        """Parse Www-Authenticate header to extract realm and service.
+
+        Example header:
+        Bearer realm="https://auth.docker.io/token",service="registry.docker.io"
+        """
+        if not header.startswith("Bearer "):
+            return None
+
+        # Extract realm
+        realm_match = re.search(r'realm="([^"]+)"', header)
+        if not realm_match:
+            return None
+        realm = realm_match.group(1)
+
+        # Extract service
+        service_match = re.search(r'service="([^"]+)"', header)
+        service = service_match.group(1) if service_match else ""
+
+        return AuthEndpoint(realm=realm, service=service)
+
+
+class RegistryToken(BaseModel):
+    """Stored registry authentication token."""
+
+    registry: str
+    username: str
+    token: str
+    scopes: list[str] = Field(default_factory=lambda: ["pull"])
+    created_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+
+
+def normalize_registry_url(registry_url: str) -> str:
+    """Normalize registry URL to docker:// scheme.
+
+    oci:// is transparently converted to docker:// as they use the same protocol.
+    """
+    if registry_url.startswith("oci://"):
+        registry_url = "docker://" + registry_url[6:]
+
+    # Add docker:// if no scheme
+    if "://" not in registry_url:
+        registry_url = f"docker://docker.io/{registry_url}"
+
+    return registry_url