@celigo/api-specs 0.2.200 → 0.2.202

package/dist/mcp-server.yml

@@ -780,6 +780,390 @@ paths:
           $ref: '#/components/responses/401-unauthorized'
         '404':
           $ref: '#/components/responses/404-not-found'
+  /v1/mcpservers/template/preview:
+    get:
+      x-internal: false
+      operationId: previewMcpServerTemplateUpload
+      tags:
+        - MCP Servers
+      summary: Preview an uploaded MCP server template
+      description: |-
+        Reads an MCP-server template ZIP you uploaded and returns the resource
+        docs installing it would create. Nothing is created. Get an upload URL
+        from `GET /v1/s3SignedURL?file_type=application/zip`, PUT the ZIP to its
+        `signedURL` with the header `x-amz-server-side-encryption: AES256`, then
+        pass that call's `runKey` here and to `POST /v1/mcpservers/template`.
+
+        The install runs the same ZIP checks with the same errors. Integration
+        template ZIPs use `GET /v1/integrations/template/preview`, which rejects
+        an MCP-server ZIP with a 400 `invalid_template` error.
+      parameters:
+        - name: runKey
+          in: query
+          required: true
+          description: |-
+            The `runKey` returned by `GET /v1/s3SignedURL` for the uploaded
+            template ZIP.
+          schema:
+            type: string
+            examples:
+              - 78f30205bdda4c4bb2a75eb121172250
+      responses:
+        '200':
+          description: Preview of the resources the install would create.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/McpServerTemplatePreview'
+              examples:
+                promptOnly:
+                  summary: Template with one inline prompt
+                  value:
+                    type: mcpserver
+                    objects:
+                      - model: McpServer
+                        doc:
+                          name: Support assistant
+                          description: ''
+                          relativeURI: /support-assistant
+                          disabled: true
+                          tools: []
+                          prompts:
+                            - name: summarize-ticket
+                              description: Summarize a support ticket.
+                              disabled: false
+                              arguments:
+                                - name: ticket
+                                  description: Ticket text.
+                                  required: true
+                              messagesTemplate:
+                                - role: user
+                                  contentType: text
+                                  template: Summarize {{ticket}}.
+                      - model: Prompt
+                        doc:
+                          name: summarize-ticket
+                          description: Summarize a support ticket.
+                          disabled: false
+                          arguments:
+                            - name: ticket
+                              description: Ticket text.
+                              required: true
+                          messagesTemplate:
+                            - role: user
+                              contentType: text
+                              template: Summarize {{ticket}}.
+                    stackRequired: false
+                connectionAndFile:
+                  summary: Template with a connection and a Celigo Storage file
+                  value:
+                    type: mcpserver
+                    objects:
+                      - model: McpServer
+                        doc:
+                          name: Support assistant
+                          description: ''
+                          relativeURI: /support-assistant
+                          disabled: true
+                          tools: []
+                          connections:
+                            - _connectionId: 6ab130000000000000000c01
+                              requiresEndUserCredentials: false
+                          resources:
+                            - fileKey: 6ab130000000000000000f01
+                              title: Support handbook
+                              disabled: false
+                              name: handbook.txt
+                              mimeType: text/plain
+                      - model: Connection
+                        doc:
+                          _id: 6ab130000000000000000c01
+                          type: http
+                          name: Support Desk API
+                          http:
+                            mediaType: json
+                            baseURI: https://api.example.com
+                            auth:
+                              type: custom
+                      - model: McpResource
+                        doc:
+                          fileKey: 6ab130000000000000000f01
+                          title: Support handbook
+                          disabled: false
+                          name: handbook.txt
+                          mimeType: text/plain
+                          size: 2048
+                    stackRequired: false
+        '400':
+          description: |-
+            The request or the ZIP is malformed: `runKey` is missing
+            (`missing_required_field`); the file is not a readable ZIP, including
+            one with two entries of the same name (`MCP_TEMPLATE_INVALID_ZIP`); or
+            an entry is invalid (`MCP_TEMPLATE_INVALID_ENTRY` — for example an
+            entry path containing `..`, a resource file the manifest declares but
+            the ZIP lacks, or a null tool row).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                missingRunKey:
+                  value:
+                    errors:
+                      - code: missing_required_field
+                        message: runKey is required.
+                invalidZip:
+                  value:
+                    errors:
+                      - code: MCP_TEMPLATE_INVALID_ZIP
+                        message: The MCP template zip is damaged or is not a zip file.
+                invalidEntry:
+                  value:
+                    errors:
+                      - code: MCP_TEMPLATE_INVALID_ENTRY
+                        message: The MCP template contains an invalid entry.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          description: The `runKey` does not match an uploaded file.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                invalidKey:
+                  value:
+                    errors:
+                      - code: invalid_key
+                        message: We couldn't find any integration template zip file.
+        '413':
+          description: |-
+            The ZIP exceeds an MCP template limit: more than 32 MiB uncompressed in
+            total, more than 500 entries, or a JSON entry over 1 MiB.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                tooLarge:
+                  value:
+                    errors:
+                      - code: MCP_TEMPLATE_ZIP_TOO_LARGE
+                        message: The MCP template zip exceeds the allowed size.
+        '422':
+          description: |-
+            The ZIP opened but is not an installable MCP-server template:
+            `mcpserver.json` is missing (`invalid_ref`, or `invalid_template` when
+            `integration.json` is missing too), a tool the server attaches is not
+            packed (`invalid_template`), an attached API or connection document is
+            not packed (`MCP_TEMPLATE_DEPENDENCY_MISSING`), or a resource file is
+            over 3 MiB or the manifest declares more than 100 of them
+            (`MCP_TEMPLATE_RESOURCE_TOO_LARGE`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                noManifest:
+                  value:
+                    errors:
+                      - code: invalid_ref
+                        message: mcpserver.json not found.
+                noManifests:
+                  value:
+                    errors:
+                      - code: invalid_template
+                        message: integration.json file is missing.
+                toolNotPacked:
+                  value:
+                    errors:
+                      - code: invalid_template
+                        message: MCP server references tool 6ab130000000000000000a01, which is missing from the template zip.
+                dependencyMissing:
+                  value:
+                    errors:
+                      - code: MCP_TEMPLATE_DEPENDENCY_MISSING
+                        message: The MCP template is missing connection 6ab130000000000000000c01.
+                resourceTooLarge:
+                  value:
+                    errors:
+                      - code: MCP_TEMPLATE_RESOURCE_TOO_LARGE
+                        message: Resource file 6ab130000000000000000f02 exceeds the allowed size.
+  /v1/mcpservers/template:
+    post:
+      x-internal: false
+      operationId: installMcpServerTemplateFromUpload
+      tags:
+        - MCP Servers
+      summary: Install an uploaded MCP server template
+      description: |-
+        Installs an MCP-server template from a ZIP you uploaded with the URL
+        from `GET /v1/s3SignedURL`. The body carries only that call's `runKey`;
+        the server's name and `relativeURI` come from the template. Check the
+        ZIP first with `GET /v1/mcpservers/template/preview`, which runs the
+        same ZIP checks with the same errors and creates nothing.
+
+        The response's `destination` envelope names what was created. A
+        template with only inline prompts creates the MCP server immediately,
+        disabled (`destination.resourceType` is `mcpservers`); when its
+        `relativeURI` is taken, the server gets a `-2`, `-3`, … suffix. A
+        template that also packs dependencies, such as a connection, creates an
+        Integration in install mode instead (`destination.resourceType` is
+        `integrations`), with an install step per packed connection and a last
+        step that copies the template's resources; no MCP server exists yet
+        when the request returns.
+
+        Every request starts a new install, so retrying after a timeout or an
+        ambiguous failure creates a duplicate server or install-mode
+        Integration.
+      x-celigo-ai-guidance:
+        - Never retry this POST after a timeout or an ambiguous failure — each request installs again; a prompt-only template yields a second server with a -2 suffix on its relativeURI, and a template with dependencies a second install-mode Integration.
+        - Branch the follow-up on destination.resourceType — "mcpservers" means the disabled MCP server already exists; "integrations" means the install continues in that Integration's install steps and the server does not exist yet.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - runKey
+              properties:
+                runKey:
+                  type: string
+                  description: |-
+                    The `runKey` returned by `GET /v1/s3SignedURL` for the uploaded
+                    template ZIP.
+                  examples:
+                    - 78f30205bdda4c4bb2a75eb121172250
+            examples:
+              default:
+                value:
+                  runKey: 78f30205bdda4c4bb2a75eb121172250
+      responses:
+        '201':
+          description: Installation started.
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - destination
+                properties:
+                  destination:
+                    type: object
+                    description: The resource the install created first.
+                    required:
+                      - resourceType
+                      - resourceId
+                    properties:
+                      resourceType:
+                        type: string
+                        enum:
+                          - mcpservers
+                          - integrations
+                        x-enumDescriptions:
+                          mcpservers: The disabled MCP server, created immediately from a template with only inline prompts
+                          integrations: The install-mode Integration created for a template that packs dependencies, such as a connection
+                        description: |-
+                          Which resource type the install created — determines
+                          where the caller continues the setup.
+                      resourceId:
+                        type: string
+                        format: objectId
+                        description: |-
+                          The created resource's ID, in the collection named by
+                          `resourceType`.
+              examples:
+                promptOnly:
+                  summary: Prompt-only template — disabled MCP server
+                  value:
+                    destination:
+                      resourceType: mcpservers
+                      resourceId: 6ab130000000000000000d02
+                withConnection:
+                  summary: Template with a connection — Integration in install mode
+                  value:
+                    destination:
+                      resourceType: integrations
+                      resourceId: 6ab130000000000000000d01
+        '400':
+          description: |-
+            The request or the ZIP is malformed: `runKey` is missing
+            (`missing_required_field`); the file is not a readable ZIP, including
+            one with two entries of the same name (`MCP_TEMPLATE_INVALID_ZIP`); or
+            an entry is invalid (`MCP_TEMPLATE_INVALID_ENTRY` — for example an
+            entry path containing `..`, a resource file the manifest declares but
+            the ZIP lacks, or a null tool row).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                missingRunKey:
+                  value:
+                    errors:
+                      - code: missing_required_field
+                        message: runKey is required.
+                invalidZip:
+                  value:
+                    errors:
+                      - code: MCP_TEMPLATE_INVALID_ZIP
+                        message: The MCP template zip is damaged or is not a zip file.
+                invalidEntry:
+                  value:
+                    errors:
+                      - code: MCP_TEMPLATE_INVALID_ENTRY
+                        message: The MCP template contains an invalid entry.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          description: The `runKey` does not match an uploaded file.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                invalidKey:
+                  value:
+                    errors:
+                      - code: invalid_key
+                        message: We couldn't find any integration template zip file.
+        '413':
+          description: |-
+            The ZIP exceeds an MCP template limit: more than 32 MiB uncompressed in
+            total, more than 500 entries, or a JSON entry over 1 MiB.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                tooLarge:
+                  value:
+                    errors:
+                      - code: MCP_TEMPLATE_ZIP_TOO_LARGE
+                        message: The MCP template zip exceeds the allowed size.
+        '422':
+          description: |-
+            The ZIP is not an installable MCP-server template, so nothing was
+            created: the same checks and codes as the preview (`invalid_ref`,
+            `invalid_template`, `MCP_TEMPLATE_DEPENDENCY_MISSING`,
+            `MCP_TEMPLATE_RESOURCE_TOO_LARGE`). Retrying with the same ZIP fails
+            the same way.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                noManifest:
+                  value:
+                    errors:
+                      - code: invalid_ref
+                        message: mcpserver.json not found.
+                dependencyMissing:
+                  value:
+                    errors:
+                      - code: MCP_TEMPLATE_DEPENDENCY_MISSING
+                        message: The MCP template is missing connection 6ab130000000000000000c01.
   /v1/mcpservers/template/{_templateId}:
     post:
       x-internal: false
@@ -4159,6 +4543,64 @@ components:
       minItems: 1
       items:
         $ref: '#/components/schemas/JsonPatchOperation'
+    McpServerTemplatePreview:
+      type: object
+      description: |-
+        What installing an uploaded MCP-server template ZIP would create.
+        `objects[]` lists each resource doc tagged by `model`. Packed docs keep
+        the template's placeholder ids; the install assigns new ones.
+      required:
+        - type
+        - objects
+        - stackRequired
+      properties:
+        type:
+          type: string
+          enum:
+            - mcpserver
+          x-enumDescriptions:
+            mcpserver: The ZIP is an MCP-server template; install it with `POST /v1/mcpservers/template`
+          description: |-
+            Kind of template the uploaded ZIP holds. Always `mcpserver` on this
+            route — a ZIP without `mcpserver.json`, such as an integration
+            template, is rejected before a preview is built.
+          examples:
+            - mcpserver
+        objects:
+          type: array
+          description: |-
+            Resource docs the install would create, in order: the `McpServer`
+            doc, then each document packed in the ZIP (a `Connection`, for
+            example), then one `Prompt` entry per inline prompt and one
+            `McpResource` entry per Celigo Storage file the server serves. The
+            ZIP's `integration.json` is never listed.
+          items:
+            type: object
+            description: One resource doc tagged with its model type.
+            required:
+              - model
+              - doc
+            properties:
+              model:
+                type: string
+                description: |-
+                  Resource class this doc describes: `McpServer`, `Prompt`, or
+                  `McpResource` for the server and what it serves, otherwise the
+                  model of the packed document, such as `Connection`.
+                examples:
+                  - Connection
+              doc:
+                type: object
+                description: |-
+                  The resource document as packed in the template. The `McpServer`
+                  doc has no `_id`; an `McpResource` doc also carries the file's
+                  `size` in bytes.
+                additionalProperties: true
+        stackRequired:
+          type: boolean
+          description: |-
+            When true, the template packs something that runs on a stack, such
+            as a wrapper connection.
     DependencyEntry:
       type: object
       description: A single resource that depends on the queried resource.
@@ -7241,6 +7683,22 @@ components:
               an `auth.type` `oauth` connection: 422 invalid_field_update "Removing _iClientId is
               not allowed for oauth connections due to security reasons." — switch it to another
               iClient instead.
+        _tokenStoreId:
+          type: string
+          format: objectId
+          readOnly: true
+          description: |-
+            Token store holding the expiring Shopify access token that this connection shares with
+            the other connections of the same app and shop. Set only by the platform, and present
+            only when set; no API route reads the store itself. Sending the field on POST, even as
+            `null`, fails with 422 `token_store_id_not_writable`. On PUT or PATCH only a value
+            different from the stored one fails the same way (any id, on a connection that has
+            none), so sending it back unchanged or omitting it is accepted.
+          x-celigo-ai-guidance:
+            - |-
+              When creating a connection from another connection's GET response, drop
+              `http._tokenStoreId` from the body: a POST that carries it with any value, `null`
+              included, fails with 422 `token_store_id_not_writable`.
         _httpConnectorId:
           type: string
           format: objectId

package/dist/template.yml

@@ -511,6 +511,12 @@ paths:
         Previews the resources that would be created by installing a template
         from an uploaded zip file. The `runKey` query parameter ties this request
         to a previously uploaded zip (obtained from `GET /v1/s3SignedURL`).
+
+        The zip must be at most 1 MB, and its entries at most 64 MB once
+        uncompressed; the preview applies the same checks as
+        `POST /v1/integrations/template`. An MCP server template (a zip with a
+        root `mcpserver.json`) is refused here: preview it with
+        `GET /v1/mcpservers/template/preview`.
       parameters:
         - name: runKey
           in: query
@@ -535,6 +541,7 @@ paths:
                 preview:
                   summary: Template that creates an integration and one connection
                   value:
+                    type: integration
                     stackRequired: false
                     objects:
                       - model: Integration
@@ -551,7 +558,10 @@ paths:
                             wsdlVersion: '2020.2'
                             concurrencyLevel: 1
         '400':
-          description: Missing required `runKey` query parameter.
+          description: |-
+            Missing required `runKey` query parameter, the uploaded zip is larger
+            than 1 MB (`invalid_zip`), or the zip is an MCP server template
+            (`invalid_template`).
           content:
             application/json:
               schema:
@@ -562,6 +572,17 @@ paths:
                     errors:
                       - code: missing_required_field
                         message: runKey is required.
+                zipTooLarge:
+                  value:
+                    errors:
+                      - code: invalid_zip
+                        message: Template can't be imported as the maximum allowed zip file size is 1 MB. Please re-import a new zip file.
+                mcpServerTemplate:
+                  summary: A zip with a root mcpserver.json
+                  value:
+                    errors:
+                      - code: invalid_template
+                        message: MCP server templates cannot be installed through the Integration template path. Use Upload MCP.
         '401':
           $ref: '#/components/responses/401-unauthorized'
         '403':
@@ -577,7 +598,26 @@ paths:
                   value:
                     errors:
                       - code: invalid_key
-                        message: The specified runKey was not found.
+                        message: We couldn't find any integration template zip file.
+        '422':
+          description: |-
+            The zip's entries exceed 64 MB uncompressed (`invalid_zip`), or an entry
+            is corrupted (`corrupted_file`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                uncompressedTooLarge:
+                  value:
+                    errors:
+                      - code: invalid_zip
+                        message: Template can't be imported as the uncompressed zip contents exceed the maximum allowed size. Please re-import a smaller zip file.
+                corrupted:
+                  value:
+                    errors:
+                      - code: corrupted_file
+                        message: Looks like the uploaded zip is corrupted. Please contact Celigo support if the issue persists.
   /v1/integrations/template:
     post:
       x-internal: false
@@ -594,6 +634,12 @@ paths:
         installed integration receives new connection `_id`s. Configure each
         connection in the new integration before running its flows; connection
         `_id`s that existed only in the zip are not preserved.
+
+        The zip must be at most 1 MB, and its entries at most 64 MB once
+        uncompressed. A zip that breaks either limit, or holds a corrupted entry,
+        is refused before anything is created. So is an MCP server template (a
+        zip with a root `mcpserver.json`): install it with
+        `POST /v1/mcpservers/template`.
       requestBody:
         required: true
         content:
@@ -626,21 +672,43 @@ paths:
                 value:
                   runKey: abc123def456
       responses:
-        '200':
-          description: Template installed from uploaded zip.
+        '201':
+          description: |-
+            Template installed. Each entry names a document the install created;
+            the `Integration` entry is the new integration.
           content:
             application/json:
               schema:
-                type: object
-                description: The created integration and related resources.
-                additionalProperties: true
+                type: array
+                items:
+                  type: object
+                  required:
+                    - model
+                    - _id
+                  properties:
+                    model:
+                      type: string
+                      description: Model of the created document.
+                      examples:
+                        - Integration
+                    _id:
+                      type: string
+                      format: objectId
+                      description: Id of the created document.
+                      examples:
+                        - 6405b9d73496e05ff253d587
               examples:
                 installed:
                   summary: Integration created from the uploaded zip
                   value:
-                    _integrationId: 6405b9d73496e05ff253d587
+                    - model: Integration
+                      _id: 6405b9d73496e05ff253d587
         '400':
-          description: Missing required `runKey` in request body.
+          description: |-
+            Missing required `runKey` in request body, the uploaded zip is larger
+            than 1 MB (`invalid_zip`), the zip is an MCP server template
+            (`invalid_template`), or the preview reports `stackRequired: true` and
+            the body has no `_stackId` (`stack_not_found`).
           content:
             application/json:
               schema:
@@ -651,12 +719,31 @@ paths:
                     errors:
                       - code: missing_required_field
                         message: runKey is required.
+                zipTooLarge:
+                  value:
+                    errors:
+                      - code: invalid_zip
+                        message: Template can't be imported as the maximum allowed zip file size is 1 MB. Please re-import a new zip file.
+                mcpServerTemplate:
+                  summary: A zip with a root mcpserver.json
+                  value:
+                    errors:
+                      - code: invalid_template
+                        message: MCP server templates cannot be installed through the Integration template path. Use Upload MCP.
+                stackMissing:
+                  summary: The zip has a stack hook and the body has no _stackId
+                  value:
+                    errors:
+                      - code: stack_not_found
+                        message: The integration template has stack reference but _stackId not found in the request body.
         '401':
           $ref: '#/components/responses/401-unauthorized'
         '403':
           $ref: '#/components/responses/403-cannot-install'
         '404':
-          description: The `runKey` does not match any uploaded zip.
+          description: |-
+            The `runKey` does not match any uploaded zip (`invalid_key`), or
+            `_stackId` matches no stack (`stack_not_found`).
           content:
             application/json:
               schema:
@@ -666,7 +753,31 @@ paths:
                   value:
                     errors:
                       - code: invalid_key
-                        message: The specified runKey was not found.
+                        message: We couldn't find any integration template zip file.
+                unknownStack:
+                  value:
+                    errors:
+                      - code: stack_not_found
+                        message: 'Failed to create the integration using the integration template provided as no stack found with _id: ''000000000000000000000000''.'
+        '422':
+          description: |-
+            The zip's entries exceed 64 MB uncompressed (`invalid_zip`), or an entry
+            is corrupted (`corrupted_file`). Nothing is installed.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                uncompressedTooLarge:
+                  value:
+                    errors:
+                      - code: invalid_zip
+                        message: Template can't be imported as the uncompressed zip contents exceed the maximum allowed size. Please re-import a smaller zip file.
+                corrupted:
+                  value:
+                    errors:
+                      - code: corrupted_file
+                        message: Looks like the uploaded zip is corrupted. Please contact Celigo support if the issue persists.
 components:
   securitySchemes:
     bearerAuth: