Metadata-Version: 2.4
Name: craft-suite-api
Version: 0.3.0
Summary: Craft suite API connector and MCP server; current ArtCraft backend subset
Author: Repository Maintainers
License: MIT
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved :: MIT License
Classifier: Environment :: Console
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Requires-Python: <3.15,>=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: rfc3986-validator<0.2,>=0.1.1
Requires-Dist: rfc3339-validator<0.2,>=0.1.4
Requires-Dist: jsonschema<5,>=4.26.0
Requires-Dist: regex>=2026.9.29
Requires-Dist: agent-connector-sdk[mcp]<1.0.0,>=0.3.0
Provides-Extra: mcp
Requires-Dist: agent-connector-sdk[mcp]<1.0.0,>=0.3.0; extra == "mcp"
Provides-Extra: all
Requires-Dist: agent-connector-sdk[mcp]<1.0.0,>=0.3.0; extra == "all"
Provides-Extra: test
Requires-Dist: pytest-xdist>=3.8.0; extra == "test"
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-asyncio; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Dynamic: license-file

# 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

| MCP tools | Authentication | Effect policy |
| --- | --- | --- |
| `craft_suite_status_alert_handler` | Public | Service alert configuration read |
| `craft_suite_omni_gen_audio_models_handler`, `craft_suite_omni_gen_image_models_handler`, `craft_suite_omni_gen_mesh_models_handler`, `craft_suite_omni_gen_splat_models_handler` | Public | Static catalog reads |
| `craft_suite_list_tags_handler`, `craft_suite_list_media_file_tags_handler` | Signed session; optional for public/hidden media tags | Session-cache effects require explicit enablement and MCP confirmation |
| `craft_suite_list_folders_handler`, `craft_suite_get_folder_handler` | Owner's signed session | Session-cache effects require explicit enablement and MCP confirmation |

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:

```json
{"name":"craft_suite_omni_gen_audio_models_handler","arguments":{}}
```

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](https://storyteller-docs.netlify.app/) 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:

```bash
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](docs/usage.md)
and `api-spec/source-provenance.json` for the supported and withheld surfaces.
