craft-suite-api 0.2.0__py3-none-any.whl

craft_suite_api/__init__.py

@@ -0,0 +1,51 @@
+#!/usr/bin/env python
+
+import importlib
+import inspect
+import warnings
+
+warnings.filterwarnings("ignore", message=".*urllib3.*or chardet.*")
+
+__all__: list[str] = []
+
+CORE_MODULES = [
+    "craft_suite_api.api",
+    "craft_suite_api.error_authority",
+]
+
+OPTIONAL_MODULES = {
+    "craft_suite_api.mcp_server": "mcp",
+}
+
+
+def _import_module_safely(module_name: str):
+    """Try to import a module and return it, or None if not available."""
+    try:
+        return importlib.import_module(module_name)
+    except ImportError:
+        return None
+
+
+def _expose_members(module):
+    """Expose public classes and functions from a module into globals and __all__."""
+    for name, obj in inspect.getmembers(module):
+        if (inspect.isclass(obj) or inspect.isfunction(obj)) and not name.startswith(
+            "_"
+        ):
+            globals()[name] = obj
+            __all__.append(name)
+
+
+for module_name in CORE_MODULES:
+    module = importlib.import_module(module_name)
+    _expose_members(module)
+
+for module_name, extra_name in OPTIONAL_MODULES.items():
+    module = _import_module_safely(module_name)
+    if module is not None:
+        _expose_members(module)
+        globals()[f"_{extra_name.upper()}_AVAILABLE"] = True
+    else:
+        globals()[f"_{extra_name.upper()}_AVAILABLE"] = False
+
+__all__.extend(["_MCP_AVAILABLE"])

craft_suite_api/__main__.py

@@ -0,0 +1,4 @@
+from .mcp_server import mcp_server
+
+if __name__ == "__main__":
+    mcp_server()

craft_suite_api/api/__init__.py

@@ -0,0 +1,3 @@
+from .api_client_system import ApiClientSystem
+
+__all__ = ["ApiClientSystem"]

craft_suite_api/api/api_client_system.py

@@ -0,0 +1,7 @@
+"""Provider client with operation-bound OpenAPI dispatch."""
+
+from ..openapi_client import OpenApiClient
+
+
+class ApiClientSystem(OpenApiClient):
+    """Use the canonical client factory with validated domain actions."""

craft_suite_api/auth.py

@@ -0,0 +1,92 @@
+"""Resolve provider credentials through canonical SDK APIs and owned resources."""
+
+from contextlib import ExitStack
+
+import httpx
+from agent_connector_sdk.auth.delegation import DelegatedTokenAuth, DelegationSettings
+from agent_connector_sdk.auth.static import api_key_auth, bearer_auth
+from agent_connector_sdk.config import load_config, setting
+from agent_connector_sdk.http.client import create_http_client
+from agent_connector_sdk.http.options import HttpClientOptions
+from agent_connector_sdk.tls.resolve import resolve_tls_profile
+
+from .api import ApiClientSystem
+from .openapi_auth_scheme import AuthKind, declared_scheme
+from .openapi_client import ClientPolicy
+from .openapi_schema import CONTRACT
+
+_client = None
+_resources = ExitStack()
+
+
+def _reference_auth(definition):
+    reference = setting("CRAFT_SUITE_API_TOKEN_REF", "")
+    if not reference:
+        return httpx.Auth(), None
+    if definition is None:
+        raise ValueError("Unsupported provider authentication scheme")
+    if definition.kind is AuthKind.HEADER:
+        return api_key_auth(reference, header=definition.header), definition.name
+    return bearer_auth(reference), definition.name
+
+
+def _delegated_auth(definition, delegation, resources):
+    if definition is None or definition.kind is not AuthKind.BEARER:
+        raise ValueError("Delegation requires a declared HTTP bearer auth scheme")
+    token_tls = resolve_tls_profile("oidc")
+    resources.callback(token_tls.cleanup)
+    token_client = create_http_client(
+        HttpClientOptions(base_url=delegation.token_endpoint, tls=token_tls)
+    )
+    resources.callback(token_client.close)
+    return DelegatedTokenAuth(delegation, http_client=token_client), definition.name
+
+
+def _build_client(base_url, resources):
+    scheme = setting("CRAFT_SUITE_API_AUTH_SCHEME", "signed_session")
+    definition = declared_scheme(scheme, CONTRACT["security_schemes"])
+    tls = resolve_tls_profile("craft-suite-api")
+    resources.callback(tls.cleanup)
+    delegation = DelegationSettings.from_settings()
+    if delegation.enabled:
+        auth, credential_scheme = _delegated_auth(definition, delegation, resources)
+    else:
+        auth, credential_scheme = _reference_auth(definition)
+    policy = ClientPolicy(
+        allow_writes=setting("CRAFT_SUITE_API_ALLOW_WRITES", False),
+        allow_plaintext=setting("CRAFT_SUITE_API_ALLOW_PLAINTEXT", False),
+    )
+    client = ApiClientSystem(
+        base_url=base_url,
+        auth=auth,
+        tls_profile=tls,
+        credential_scheme=credential_scheme,
+        policy=policy,
+    )
+    resources.callback(client.close)
+    return client
+
+
+def get_client():
+    """Build one client; delegated auth resolves the verified caller per request."""
+    global _client, _resources
+    if _client is not None:
+        return _client
+    load_config()
+    base_url = setting("CRAFT_SUITE_API_BASE_URL", "")
+    if not base_url:
+        raise ValueError("Provider base URL is required")
+    with ExitStack() as resources:
+        client = _build_client(base_url, resources)
+        _resources = resources.pop_all()
+        _client = client
+    return client
+
+
+def close_client():
+    """Close the cached client, token client and materialized TLS resources."""
+    global _client
+    try:
+        _resources.close()
+    finally:
+        _client = None

craft_suite_api/connector_manifest.yml

@@ -0,0 +1,47 @@
+{
+  "connector": "craft-suite-api",
+  "ontology_source": "artcraft",
+  "schema_version": "1",
+  "resources": [
+    {
+      "name": "ArtcraftResource"
+    },
+    {
+      "name": "Document"
+    },
+    {
+      "name": "MediaAsset"
+    }
+  ],
+  "identity": {
+    "id_field": {
+      "ArtcraftResource": "id"
+    },
+    "title_field": {
+      "ArtcraftResource": "name"
+    }
+  },
+  "schema_mappings": {
+    "ArtcraftResource": {
+      "fields": {
+        "name": "xsd:string"
+      }
+    }
+  },
+  "sync": [],
+  "provenance": {
+    "generated_by": "mcp-builder/scripts/scaffold_package.py",
+    "source_artifacts": [
+      "ontology/artcraft.ttl"
+    ],
+    "integrity": {
+      "algorithm": "sha256",
+      "hash": "a759f5a7effd1151539a1f9918225939ea8bc2484ff28b36852310e054d1d9db"
+    }
+  },
+  "review_todos": [
+    "Replace the starter resource mapping with the reviewed source model.",
+    "Declare real source presets and matching sync entries before certification.",
+    "Integrity is an ontology byte hash, not canonical RDF or release certification."
+  ]
+}

craft_suite_api/connectors/mcp_source_presets.json

@@ -0,0 +1 @@
+{}

craft_suite_api/connectors/tool_schema_fingerprints.json

@@ -0,0 +1,6 @@
+{
+  "algorithm": "agent-connector-sdk:mcp-tool-contract-compat:v2",
+  "connector": "craft-suite-api",
+  "schema_version": "1",
+  "tools": {}
+}

craft_suite_api/error_authority.py

@@ -0,0 +1,140 @@
+"""Negotiate representations of the canonical bounded problem details."""
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+
+from .problem_details import (
+    AGENT_ERROR_ACCEPT,
+    BROWSER_HTML_MEDIA_TYPE,
+    MAX_DETAIL_CHARS,
+    PROBLEM_JSON_MEDIA_TYPE,
+    STRUCTURED_MARKDOWN_MEDIA_TYPE,
+    ProblemDetails,
+)
+
+
+@dataclass(frozen=True)
+class RenderedError:
+    """A transport-neutral response ready for an HTTP/MCP adapter."""
+
+    status_code: int
+    media_type: str
+    body: str
+    headers: Mapping[str, str]
+
+
+def _media_candidate(item: str, offered: str, order: int):
+    bits = [part.strip() for part in item.split(";")]
+    token = bits[0].lower()
+    try:
+        quality = next(
+            float(part.split("=", 1)[1].strip())
+            for part in bits[1:]
+            if part.lower().startswith("q=")
+        )
+    except (StopIteration, ValueError):
+        quality = 1.0
+    if not 0.0 <= quality <= 1.0:
+        return None
+    specificity = {offered: 2, "*/*": 1, offered.split("/", 1)[0] + "/*": 1}.get(token)
+    if specificity is None:
+        return None
+    return specificity, quality, -order
+
+
+def _accept_quality(accept: str, offered: str) -> tuple[float, int, int]:
+    """Return q, specificity, and source order for one offered media type."""
+    candidates = (
+        _media_candidate(item, offered, order)
+        for order, item in enumerate(accept.split(","))
+    )
+    specificity, quality, source_order = max(
+        (candidate for candidate in candidates if candidate is not None),
+        default=(-1, 0.0, -10_000),
+    )
+    return quality, specificity, source_order
+
+
+def negotiate_media_type(accept: str | None) -> str:
+    """Prefer agent formats, while retaining HTML for browser Accept headers."""
+    if not accept or not accept.strip():
+        return PROBLEM_JSON_MEDIA_TYPE
+    offered = (
+        PROBLEM_JSON_MEDIA_TYPE,
+        STRUCTURED_MARKDOWN_MEDIA_TYPE,
+        BROWSER_HTML_MEDIA_TYPE,
+    )
+    ranked = [
+        (*_accept_quality(accept, media_type), -priority, media_type)
+        for priority, media_type in enumerate(offered)
+    ]
+    supported = [candidate for candidate in ranked if candidate[0] > 0]
+    return max(supported)[-1] if supported else PROBLEM_JSON_MEDIA_TYPE
+
+
+def render_error(
+    problem: ProblemDetails, *, accept: str | None = None
+) -> RenderedError:
+    """Negotiate one bounded representation without changing its semantics."""
+    media_type = negotiate_media_type(accept)
+    if media_type == STRUCTURED_MARKDOWN_MEDIA_TYPE:
+        body = problem.to_markdown()
+    elif media_type == BROWSER_HTML_MEDIA_TYPE:
+        body = problem.to_html()
+    else:
+        media_type = PROBLEM_JSON_MEDIA_TYPE
+        body = problem.to_json()
+    headers = {
+        "Content-Type": f"{media_type}; charset=utf-8",
+        "Vary": "Accept",
+    }
+    if problem.retry_after_s is not None:
+        headers["Retry-After"] = str(problem.retry_after_s)
+    return RenderedError(
+        status_code=problem.status,
+        media_type=media_type,
+        body=body,
+        headers=headers,
+    )
+
+
+def error_response(
+    *,
+    status: int,
+    code: str,
+    instance: str,
+    detail: str,
+    type_uri: str = "",
+    title: str = "",
+    retryable: bool = False,
+    retry_after_s: float | None = None,
+    accept: str | None = None,
+) -> RenderedError:
+    """Construct and render a problem through the single package authority."""
+    return render_error(
+        ProblemDetails(
+            status=status,
+            code=code,
+            instance=instance,
+            detail=detail,
+            type_uri=type_uri,
+            title=title,
+            retryable=retryable,
+            retry_after_s=retry_after_s,
+        ),
+        accept=accept,
+    )
+
+
+__all__ = [
+    "BROWSER_HTML_MEDIA_TYPE",
+    "AGENT_ERROR_ACCEPT",
+    "MAX_DETAIL_CHARS",
+    "PROBLEM_JSON_MEDIA_TYPE",
+    "ProblemDetails",
+    "RenderedError",
+    "STRUCTURED_MARKDOWN_MEDIA_TYPE",
+    "error_response",
+    "negotiate_media_type",
+    "render_error",
+]

craft_suite_api/mcp/__init__.py

@@ -0,0 +1,20 @@
+"""Catalog-bound registrars preserving the SDK's per-domain toggles."""
+
+from functools import partial
+
+from ..auth import get_client
+from ..openapi_runtime import CONTRACT, register_domain
+
+
+def _domain_registrar(domain):
+    registrar = partial(register_domain, domain=domain, client_factory=get_client)
+    registrar.__name__ = f"register_{domain}_tools"
+    return registrar
+
+
+globals().update(
+    {
+        f"register_{domain}_tools": _domain_registrar(domain)
+        for domain in sorted(CONTRACT["domains"])
+    }
+)

craft_suite_api/mcp_config.json

@@ -0,0 +1,3 @@
+{
+  "mcpServers": {}
+}

craft_suite_api/mcp_server.py

@@ -0,0 +1,50 @@
+import sys
+from pathlib import Path
+
+from agent_connector_sdk.config import load_config
+from agent_connector_sdk.mcp.content import ConnectorContent
+from agent_connector_sdk.mcp.server import create_mcp_server
+from agent_connector_sdk.mcp.tool_surface import register_tool_surface
+
+from . import mcp as tool_modules
+
+__version__ = "0.2.0"
+
+
+def get_mcp_instance(*, command_args=None):
+    """Construct one SDK-governed server and its native package content."""
+    load_config()
+    package_root = Path(__file__).resolve().parent
+    args, mcp, middlewares = create_mcp_server(
+        name="Craft Suite",
+        version=__version__,
+        instructions="Craft Suite connector; nine reviewed ArtCraft backend reads",
+        command_args=command_args,
+        content=ConnectorContent(
+            connector="craft-suite-api",
+            package_root=package_root,
+            package_version=__version__,
+            manifest_path=package_root / "connector_manifest.yml",
+        ),
+    )
+    register_tool_surface(mcp, service="craft-suite-api", tools_module=tool_modules)
+    for middleware in middlewares:
+        mcp.add_middleware(middleware)
+    return mcp, args, middlewares
+
+
+def build_server(*, command_args=None):
+    return get_mcp_instance(command_args=command_args)[0]
+
+
+def mcp_server():
+    mcp, args, _ = get_mcp_instance()
+    print("Starting Craft Suite MCP", file=sys.stderr)
+    options = (
+        {} if args.transport == "stdio" else {"host": args.host, "port": args.port}
+    )
+    mcp.run(transport=args.transport, **options)
+
+
+if __name__ == "__main__":
+    mcp_server()

craft_suite_api/ontology/__init__.py

@@ -0,0 +1,6 @@
+"""ArtCraft ontology contribution (CONCEPT:AU-KG.ontology.federation-provider-leg).
+
+Data-only subpackage carrying ``artcraft.ttl`` (the ``owl:Ontology``
+``http://knuckles.team/kg/artcraft`` module) which the agent-connector-sdk hub
+federates via the ``agent_connector_sdk.ontology_providers`` entry-point.
+"""

craft_suite_api/ontology/artcraft.ttl

@@ -0,0 +1,29 @@
+@prefix : <http://knuckles.team/kg#> .
+@prefix owl: <http://www.w3.org/2002/07/owl#> .
+@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
+@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
+
+# TODO: replace this stub with the real domain model. Classes/properties live in the
+# SHARED : (kg#) namespace; only the owl:Ontology node gets the per-package IRI. Do NOT
+# redefine classes another package owns (:MediaAsset/:Blob/:Document/:Person) — reuse them.
+
+:ArtcraftResource a owl:Class ;
+    rdfs:label "ArtCraft Resource" ;
+    rdfs:comment "A primary object managed by ArtCraft (STUB — rename/expand)." .
+
+:managedBy a owl:ObjectProperty ;
+    rdfs:label "managed by" ;
+    rdfs:comment "Links a ArtCraft resource to the Person responsible (STUB)." ;
+    rdfs:domain :ArtcraftResource ;
+    rdfs:range :Person .
+
+:artcraftId a owl:DatatypeProperty ;
+    rdfs:label "artcraft id" ;
+    rdfs:comment "External identifier of the ArtCraft resource (STUB)." ;
+    rdfs:domain :ArtcraftResource ;
+    rdfs:range xsd:string .
+
+<http://knuckles.team/kg/artcraft> a owl:Ontology ;
+    rdfs:label "ArtCraft Ontology" ;
+    rdfs:comment "ArtCraft domain extensions federated into the KG hub. STUB." ;
+    owl:imports <http://knuckles.team/kg> .

craft_suite_api/openapi_auth_scheme.py

@@ -0,0 +1,67 @@
+"""Typed, declared provider authentication backed by SDK credential references."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import Any
+
+
+class AuthKind(StrEnum):
+    """Supported wire representations; neither implies provider permissions."""
+
+    BEARER = "bearer"
+    HEADER = "header"
+
+
+@dataclass(frozen=True)
+class ProviderAuthScheme:
+    """One named OpenAPI scheme, never a credential value or a default header."""
+
+    name: str
+    kind: AuthKind
+    header: str = ""
+
+
+def declared_scheme(
+    name: str, definitions: Mapping[str, Any]
+) -> ProviderAuthScheme | None:
+    """Fail closed for an explicit unknown or unsupported scheme."""
+    if not name:
+        return None
+    if name not in definitions:
+        raise ValueError("Selected authentication scheme is not declared")
+    definition = definitions[name]
+    if not isinstance(definition, Mapping):
+        raise TypeError("Authentication scheme must be an OpenAPI object")
+    wire_scheme = definition.get("scheme", "")
+    if (
+        definition.get("type") == "http"
+        and isinstance(wire_scheme, str)
+        and wire_scheme.casefold() == "bearer"
+    ):
+        return ProviderAuthScheme(name, AuthKind.BEARER)
+    if definition.get("type") != "apiKey" or definition.get("in") != "header":
+        raise ValueError("Unsupported provider authentication scheme")
+    return ProviderAuthScheme(name, AuthKind.HEADER, _credential_header(definition))
+
+
+def _credential_header(definition):
+    header = definition.get("name")
+    if not isinstance(header, str) or not re.fullmatch(
+        r"[!#$%&'*+.^_`|~0-9A-Za-z-]+", header
+    ):
+        raise ValueError("Invalid credential header name")
+    if header.casefold() in {
+        "host",
+        "connection",
+        "content-length",
+        "transfer-encoding",
+        "proxy-authorization",
+        "proxy-authenticate",
+        "cookie",
+    }:
+        raise ValueError("Credential header conflicts with HTTP transport")
+    return header

craft_suite_api/openapi_client.py

@@ -0,0 +1,121 @@
+"""Operation-bound HTTP dispatch with explicit caller policy."""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+from typing import Any
+from urllib.parse import urlsplit
+
+from agent_connector_sdk.http.client import create_http_client
+from agent_connector_sdk.http.options import HttpClientOptions
+from agent_connector_sdk.http.retry import RetryPolicy
+
+from .openapi_execution import require_authorization
+from .openapi_parameters import parameters, request_body
+from .openapi_responses import read_response, response_value
+from .openapi_schema import CONTRACT, validate
+
+MAX_BYTES = 16 * 1024 * 1024
+
+
+@dataclass(frozen=True)
+class ClientPolicy:
+    """Default-deny write and transport permissions from the operator."""
+
+    allow_writes: bool = False
+    allow_plaintext: bool = False
+
+
+class OpenApiClient:
+    """Dispatch only catalogued actions; perform each HTTP request exactly once."""
+
+    def __init__(
+        self,
+        base_url,
+        auth,
+        tls_profile=None,
+        *,
+        credential_scheme=None,
+        policy: ClientPolicy | None = None,
+        transport=None,
+    ):
+        policy = policy or ClientPolicy()
+        parsed = urlsplit(base_url)
+        if parsed.path not in {"", "/"} or parsed.query or parsed.fragment:
+            raise ValueError("Base URL must be the provider origin without a path")
+        if credential_scheme and parsed.scheme == "http" and not policy.allow_plaintext:
+            raise ValueError(
+                "Credential-bearing plaintext HTTP requires allow_plaintext"
+            )
+        self.session = create_http_client(
+            HttpClientOptions(
+                base_url=base_url,
+                auth=auth,
+                tls=tls_profile,
+                retry=RetryPolicy(max_attempts=1),
+                allow_plaintext=policy.allow_plaintext,
+                timeout=30.0,
+            ),
+            transport=transport,
+        )
+        self.credential_scheme = credential_scheme
+        self.allow_writes = policy.allow_writes
+
+    def close(self):
+        self.session.close()
+
+    def _authorize(self, operation):
+        require_authorization(operation, CONTRACT)
+        if not operation["read_only"] and not self.allow_writes:
+            raise PermissionError("Writes require explicit operator enablement")
+        requirements = operation["security"]
+        if requirements and not any(
+            not choice or set(choice) == {self.credential_scheme}
+            for choice in requirements
+        ):
+            raise PermissionError("Action requires a supported credential reference")
+
+    def execute(self, domain: str, arguments: dict[str, Any]):
+        if domain not in CONTRACT["domains"]:
+            raise ValueError("Unknown domain")
+        validate(arguments, CONTRACT["schemas"][domain][0])
+        operation = CONTRACT["operations"][arguments["action"]]
+        if operation["domain"] != domain:
+            raise ValueError("Action is outside this domain")
+        self._authorize(operation)
+        path, query, headers = parameters(operation, arguments)
+        target = self.session.base_url.join(path)
+        origin = self.session.base_url
+        if (target.scheme, target.host, target.port) != (
+            origin.scheme,
+            origin.host,
+            origin.port,
+        ):
+            raise ValueError(
+                "Operation must stay within the configured provider origin"
+            )
+        options = {"params": query, "headers": headers, "follow_redirects": False}
+        if "body" in arguments:
+            options.update(
+                request_body(operation, arguments["body"], max_bytes=MAX_BYTES)
+            )
+        return self._send(operation, path, options)
+
+    def _send(self, operation, path, options):
+        deadline = time.monotonic() + 60
+        with self.session.stream(operation["method"], path, **options) as response:
+            if not 200 <= response.status_code < 300:
+                raise RuntimeError(
+                    f"Provider returned HTTP {response.status_code}; no automatic retry"
+                )
+            body = read_response(response, deadline, max_bytes=MAX_BYTES)
+            content_type, data = response_value(operation, response, body)
+            result = {
+                "action": operation["action"],
+                "status": response.status_code,
+                "content_type": content_type,
+                "data": data,
+            }
+            validate(result, CONTRACT["schemas"][operation["domain"]][1])
+            return result