Craft Suite API connector

A bounded connector for the ArtCraft Services backend. This version exposes nine source-reviewed GET operations through four SDK-backed MCP tools. It is not a connector to Craft documents or the native ArtCraft desktop editor. This partial surface does not meet the required full Craft-suite API/MCP parity; 259 documented backend operations and all native Craft applications remain unimplemented.

Supported operations

The image catalog accepts a provider query parameter, but the pinned handler ignores it. List endpoints return one page: pass maybe_cursor unchanged to the next call; the server defaults to 100 rows and clamps limits to 1000.

Job-status GETs are withheld because they write keepalives. Video model discovery is withheld because the public schema lacks source fields. Generation, uploads, account management, administrative routes and all other endpoints are unsupported in this version. No arbitrary route or method can be supplied through these tools.

Package identity

The connector is craft-suite-api, imported as craft_suite_api, with the craft-suite-mcp command and CRAFT_SUITE_API_ configuration prefix. Update existing installations and integration configuration to these names; legacy package, command and environment aliases are not provided. This identity change preserves the prior eight operations; this batch adds the source-reviewed status alert.

Usage

Set CRAFT_SUITE_API_BASE_URL to the approved backend HTTPS origin. For session operations, set CRAFT_SUITE_API_TOKEN_REF to an SDK credential reference such as env://CRAFT_SUITE_SESSION_VALUE; the resolver supplies the session header. No signed session or account is generated by this package. Bearer/OIDC delegation cannot substitute for a signed session. TLS verification stays enabled, redirects are refused, and credentials cannot cross the configured origin.

CRAFT_SUITE_API_ALLOW_WRITES defaults to false. The conservative gate also covers GET handlers that can populate the session cache; MCP additionally asks for confirmation from an elicitation-capable MCP client. Legacy clients use an elicitation request. Modern clients receive a pending input request and must return an explicit acceptance bound to the same action and arguments. Declined, missing, or changed confirmation state is rejected before dispatch. The four public catalog actions and service-status action work without that enablement or a credential. CRAFT_SUITE_API_ALLOW_PLAINTEXT defaults to false.

After installing the declared SDK and package dependencies in an approved source environment, run craft-suite-mcp (stdio by default). For example, call:

{"name":"omni_gen_operations","arguments":{"action":"omni_gen_audio_models_handler"}}

This repository is source-validated. Package release, registry installation, container startup, live service access and deployment are not certified here. Graph ingestion is unavailable: no tenant-scoped ArtCraft mapping or complete receipt contract has been implemented. The generic ingestion starter has been removed.

Provenance and regeneration

The official API reference supplies the captured OpenAPI document (268 operations). Full upstream snapshots are not bundled in the current tree. Its SHA-256 and the exact pinned public GitHub source are recorded in api-spec/source-review.json. The docs host does not attest a source commit.

api-spec/source-provenance.json records source-line links for each admitted route/handler/response, 26 Rust struct field/required-field checks, source-derived additions and explicit unknowns. Enum values and other serializer facets come from the captured public schema; complete parity with the pinned backend is not claimed. Two missing optional folder fields are mapped from explicit Option<Url> and Option<String> source declarations.

Use the installed, self-contained mcp-builder skill; no GitHub template repository or template-generation API is required:

python scripts/generate_source_contract.py --skill-dir /path/to/mcp-builder --evidence-dir /path/to/verified-artcraft-evidence
python scripts/generate_tool_schemas.py
python scripts/generate_tool_schemas.py --check
python -m pytest tests -q
pre-commit run --all-files

The reviewed SDK factory/delegation and typed-header generator changes must be present in that skill. Generator file hashes are recorded with this validation receipt; an unreviewed generator is not a substitute. Regeneration verifies the externally supplied schema/source hashes and fails on selected response-field drift. api-spec/source-review.json records exact source commit/blob hashes/URLs and the historical capture commit. Preserve original bytes in a separate evidence directory with artcraft.public.openapi.json and source/<upstream path>; no upstream code is reformatted or claimed as an identical bundled snapshot.

The approved clone policy admits only the three schema files listed in validation/generated-schemas.json. Before excluding a schema-to-schema clone pair, the hook regenerates the reviewed OpenAPI and runtime contract from exact captures with the recorded compiler, then checks the native MCP schema snapshot. It verifies the same committed or merged tree that the shared scanner examines. Handwritten pairs, including handwritten-to-schema pairs, remain enforced. Missing inputs, stale artifacts, extra paths and invalid receipts fail the gate. The scanner versions, thresholds and existing exclusions are unchanged.

For these checks, set MCP_BUILDER_SKILL_DIR to the recorded 1.3.10 skill source, ARTCRAFT_SOURCE_EVIDENCE_DIR to the exact preserved capture directory, and GENERATED_SCHEMA_PYTHON to the approved project environment's Python executable (default: .venv/bin/python). Run python scripts/verify_generated_schemas.py and both configured pre-commit stages. No verification receipt alone replaces a successful regeneration. When a diff upgrades the compiler, also set MCP_BUILDER_SNAPSHOT_ROOT to a directory containing each compared commit's compiler capture under its full builder commit ID. The clone gate selects the capture from each tree's manifest and still requires its compiler hashes and regeneration checks; a missing capture fails closed. The three shared Pipelines references follow main with explicit user approval; record its resolved commit with each validation run.

CI prepares locked project dependencies with the canonical builder bootstrap, then restores the original OpenAPI capture from its recorded Git commit and fetches pinned public Rust/compiler evidence. SHA-256 and Git blob checks precede the existing exact-tree regeneration proof. No scanner or native dependency is built by this workflow. Bootstrap authority is recorded in validation/ci-bootstrap.json.

URI and date-time schema formats are enforced with the declared validators. Authorization provenance is also enforced during execution. Unknown or missing declarations refuse before API transport and before native MCP credential resolution or write confirmation. The existing nine reviewed operations retain their declared public, optional-session or required-session rules. This guard admits no additional operations; the 259 broader candidates remain withheld. Missing required format support fails explicitly; provider date representation still requires source review before additional operations can be admitted.

Validation boundary

Tests use actual SDK HTTP/auth/MCP components with synthetic responses at the provider boundary. No production call, credential issuance, backend write, container deployment or Rust build was performed. See usage and api-spec/source-provenance.json for the supported and withheld surfaces.