# KonfigurátorSPZ.cz

> Czech registration-mark visualization, rule evaluation, advisory registry lookup, and PNG rendering.

## Quick visualization

Open https://spz-gen-pr61.dokploy.martinmachava.com/?text={URL_ENCODED_TEXT}&type={type}. URL-encode the requested text and choose one type from: standard, carrier, truck, van-square, square, motorbike, moped. The application reads this deterministic form and may canonicalize it to a stable share URL. This public page is for visualization; it is not proof that a mark can be reserved or approved.

## Agent instructions and schemas

- Agent guide: https://spz-gen-pr61.dokploy.martinmachava.com/developers/agent.md
- Reusable skill: https://spz-gen-pr61.dokploy.martinmachava.com/developers/SKILL.md
- OpenAPI 3.1: https://spz-gen-pr61.dokploy.martinmachava.com/openapi.json
- Human-readable API documentation: https://spz-gen-pr61.dokploy.martinmachava.com/developers/docs
- SDK and embeds: https://spz-gen-pr61.dokploy.martinmachava.com/developers/docs/embeds

## Current REST API

- Generate a PNG operation: POST https://spz-gen-pr61.dokploy.martinmachava.com/api/v1/plates/generate
- Evaluate plate rules: POST https://spz-gen-pr61.dokploy.martinmachava.com/api/v1/plates/verify
- Check the registry snapshot: POST https://spz-gen-pr61.dokploy.martinmachava.com/api/v1/plates/availability
- Create a browser session from a server-held project credential: POST https://spz-gen-pr61.dokploy.martinmachava.com/api/v1/browser-sessions
- Public provisional pricing: GET https://spz-gen-pr61.dokploy.martinmachava.com/api/v1/pricing
- Authenticated usage: GET https://spz-gen-pr61.dokploy.martinmachava.com/api/v1/usage
- Poll an operation: GET https://spz-gen-pr61.dokploy.martinmachava.com/api/v1/operations/{id}
- Retrieve an owned artifact: GET https://spz-gen-pr61.dokploy.martinmachava.com/api/v1/artifacts/{id}

The REST API is a public beta. Billable POST requests require authentication and an idempotency key. Keep project credentials server-side and out of URLs, browser bundles, logs, cookies, and postMessage payloads.

## Autonomous agent onboarding and MCP

- Trial issuance: POST https://spz-gen-pr61.dokploy.martinmachava.com/api/v1/agent-trials with Content-Type application/json, an empty JSON object, and a stable Idempotency-Key. A new issuance returns 201 with the API key and claim URL once; a replay returns 200 and omits both one-time bearers.
- Domain challenge creation: POST https://spz-gen-pr61.dokploy.martinmachava.com/api/v1/agent-trials/domain-challenges with {"hostname":"project.example"}.
- Challenge status: GET https://spz-gen-pr61.dokploy.martinmachava.com/api/v1/agent-trials/domain-challenges/{challengeId}
- Challenge verification: POST https://spz-gen-pr61.dokploy.martinmachava.com/api/v1/agent-trials/domain-challenges/{challengeId}/verify with an empty JSON object.
- Human claim handoff: https://spz-gen-pr61.dokploy.martinmachava.com/developers/claim/{claimHandle}
- MCP Streamable HTTP endpoint: POST https://spz-gen-pr61.dokploy.martinmachava.com/mcp

Send the issued server credential only in the HTTP Authorization: Bearer header for REST and MCP challenge calls; never put it in JSON-RPC arguments. create_agent_trial remains public. MCP accepts current stateless protocol 2026-07-28 and initialization-based 2025-06-18 compatibility.

## Evaluation, legal, and privacy boundaries

An evaluation principal is short-lived, narrowly scoped, metered, provider-attributed, and unable to buy credits or accept human terms. Anonymous evaluation does not verify identity. Domain promotion requires HTTPS control proof at the exact /.well-known/konfiguratorspz.json path issued with a challenge; accountable claim requires an authenticated Clerk principal and current terms acceptance, directly or via explicitly authorized delegate.

Rule evaluation and registry availability are advisory. They do not reserve a registration mark or replace approval by the competent Czech authority. Do not submit personal, confidential, unlawful, or third-party credential data. Requests may process supplied plate text plus technical, usage, abuse-prevention, and security metadata as described in:

- Developer terms: https://spz-gen-pr61.dokploy.martinmachava.com/developers/terms
- Developer privacy notice: https://spz-gen-pr61.dokploy.martinmachava.com/developers/privacy

Anonymous trial scopes are exactly generate, verify and artifacts; owned operation polling is allowed. Anonymous trial credentials cannot call availability, usage or browser-session issuance, accept customer terms, purchase credits or establish durable ownership. Read returned credits/scopes/expiresAt. A serviceMode of paid can consume evaluation credits; it is not evidence of a payment. If issuance is ambiguous, retain the original idempotency key and use authenticated owner/operator recovery, not another trial to evade limits.

The public iframe is a separate anonymous provider-attributed preview, not a debit to a developer wallet or a private artifact contract. It may put non-sensitive text in publicly cached image URLs; private authenticated artifacts are no-store. For the complete server generate/verify/availability → poll → artifact recipe, see https://spz-gen-pr61.dokploy.martinmachava.com/developers/docs/getting-started. For copy-ready HTML, React, vanilla and configuration/theme examples, see https://spz-gen-pr61.dokploy.martinmachava.com/developers/docs/embeds.

SDK 0.1.0 is distributed as https://spz-gen-pr61.dokploy.martinmachava.com/developers/sdk/konfigurator-spz-sdk-0.1.0.tgz, not from the public npm registry. In your own application directory, install the HTTPS tarball with npm install, following https://spz-gen-pr61.dokploy.martinmachava.com/developers/docs/embeds#install-the-public-sdk-tarball. No repository checkout is required.

Production rollout remains on hold pending operator release confirmation, provider readiness and measured capacity. A preview artifact, current published terms/privacy notice or provisional CZK pricing is not production activation. The legal documents are current published documents, not draft placeholders. Confirm commercial rollout with info@konfiguratorspz.cz.


## MCP request envelope (read-only discovery)

MCP protocol revisions and the JSON-RPC envelope version are different fields. Both supported MCP revisions (2026-07-28 and 2025-06-18) require the exact string "jsonrpc":"2.0"; "2" is not a modern alternate spelling.

For 2026-07-28, each request is independent: send MCP-Protocol-Version, MCP-Method, MCP-Name for tools/call, and matching per-request protocol/client-capabilities _meta. There is no initialize or session prerequisite. This read-only tools/list call creates no trial and needs no credential:

```sh
curl --fail-with-body 'https://spz-gen-pr61.dokploy.martinmachava.com/mcp' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2026-07-28' \
  -H 'MCP-Method: tools/list' \
  --data '{"jsonrpc":"2.0","id":"list-1","method":"tools/list","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{}}}}'
```

For a read-only tools/call, use describe_integration with arguments {} and add MCP-Name: describe_integration plus MCP-Method: tools/call; retain the same per-request _meta. Never issue a trial merely to test an envelope.

For legacy 2025-06-18, initialize first, retain the returned MCP-Session-Id, send notifications/initialized, and include both session and protocol-version headers on subsequent calls. Both modes require Content-Type: application/json and Accept: application/json, text/event-stream. Authentication for protected tools is an HTTP Bearer header, never JSON-RPC arguments. Use only Streamable HTTP, not deprecated HTTP+SSE.


## Accountable delegated acceptance and claim (REST)

An anonymous evaluation principal cannot accept terms, bind a customer, purchase credits, or claim accountable ownership. Domain control is not identity. An existing authenticated Clerk account owner/admin may explicitly delegate bounded acts; the agent is not recorded as that human.

1. Create a trial and retain its trialId and separate claim bearer securely. The legacy claimUrl contains the bearer as its last path segment; extract it locally and do not navigate to or log it for the delegated flow.
2. The accountable owner authorizes once at /developers/agents or through GET/POST /api/v1/agent-authority/authorizations using the existing Clerk session. GET returns the active account, principalUserId, CSRF token, exact authorization statements and recent authorizations. POST requires same-origin Origin, X-CSRF-Token, a stable Idempotency-Key for grant issuance, Content-Type application/json, and the complete JSON body below. Replace placeholders with the exact management GET values; do not submit placeholders. Owner identity and account come from the session, never input names or claimed identities. This grants no purchase authority. The response body returns capability once. No page-click acceptance is required for subsequent delegated acts.
3. GET /api/v1/agent-authority/terms returns canonicalDocumentVersion, version, sections, documentSha256, canonicalization, and delegateAttestation. Verify SHA-256 over UTF-8 JSON.stringify({version:canonicalDocumentVersion,sections}) yourself. Read the exact document before acceptance.
4. POST /api/v1/agent-authority/accept with only {capability,termsVersion:version,documentSha256,attestation:delegateAttestation}. This is an explicit delegated act on behalf of the named principal, not a claim to have performed a human click. The exact authorized version/hash is required. A changed document requires new owner authorization.
5. POST /api/v1/agent-authority/claim with only {capability,claimSecret}. Both the capability (bound to that exact trial) and separate claim bearer are required. Claim preserves trial account/project/ledger identity, attaches the accountable principal as owner, revokes all preclaim keys and browser sessions, and returns the rotated API key in the response body once.
6. Operation spending is NOT implied by claim. By default the returned key has only artifacts and usage:read and a zero monthly project credit budget. To authorize operation calls, explicitly include operationScopes (generate, verify, availability), monthlyCreditBudget (0–10000), and spendingAuthorization (exact statement from management GET) when issuing authority. These scopes do not include browser-session issuance. The rotated operation key expires with authority (maximum one hour), revocation also revokes it, and the existing project monthly spend guard meters queued/running/succeeded operation credits. The budget is monthly, not a lifetime allowance; no credit purchases or checkout permissions are granted.
7. Revoke using authenticated POST /api/v1/agent-authority/authorizations with {intent:"revoke",authorityId}, Origin and X-CSRF-Token. GET lists the latest 100 of this principal's active-account authorizations without secrets. Completed ownership and legal evidence remain; revocation prevents future use, not retroactive erasure.

Owner management POST body (valid JSON with explicit placeholders, no operation-spending grant):

```json
{
  "intent": "issue",
  "authorization": {
    "trialId": "<trialId from the retained trial response>",
    "agentName": "Owner-approved deployment agent",
    "scopes": [
      "terms:accept",
      "trial:claim"
    ],
    "expiresInSeconds": 900,
    "termsVersion": "<termsVersion from management GET>",
    "documentSha256": "<documentSha256 from management GET>",
    "authorization": "<exact authorization statement from management GET>"
  }
}
```

Never infer customer consent from a successful evaluation, domain proof, or contractor assignment. The authenticated owner must review and authorize these exact acts first. Use /developers/agents for the interactive owner flow. The example intentionally omits operationScopes, monthlyCreditBudget and spendingAuthorization; adding operation spending requires a separate explicit owner decision and the exact management statement.

Capability and rotated key are body-only one-time responses. Never put capability or claimSecret in a URL, logs, analytics or a cookie. Delegated endpoints reject every query parameter. Grant issuance retries with the same Idempotency-Key return the same record without capability; changed payloads conflict. Acceptance/claim are single-use transactions: concurrent/repeated requests return 409 after the successful act and never repeat secrets or duplicate legal evidence. If a response is lost, the authenticated owner can inspect state; issue a fresh key through existing owner controls rather than replaying a secret. Expired/revoked, wrong-scope, wrong-account/member/role, wrong-trial/bearer, stale-version/hash, and anonymous requests fail closed. Delegated acts retain immutable authorization and acceptance/claim evidence with accountable principal, agent label, scope/budget, account, exact terms/hash, attestation and timestamps. An agent label is an owner-provided label, not independently verified software identity.