@celigo/api-specs 0.2.218 → 0.2.219

package/dist/marketplace.yml

@@ -859,7 +859,19 @@ components:
             `Connection`s, `Flow`s, `Export`s, `Import`s, `Script`s and any
             other supporting resources; for an MCP server template it is the
             `McpServer` doc first, then its `Connection`s, `Export`s, `Import`s,
-            `Script`s and `Tool`s, then one `Prompt` entry per inline prompt.
+            `Script`s, `Tool`s and `Api`s, then one `Prompt` entry per inline
+            prompt and one `McpResource` entry per Celigo Storage file the
+            server serves. The `McpServer` doc is the template's secret-free
+            manifest: tool and API attachments (MCP-exposed `name`,
+            `annotations`, per-tool connection `overrides` with
+            `requiresEndUserCredentials`), inline `prompts`, `resources`,
+            `connections` that require end-user credentials,
+            `upstreamMcpConnections` with the selected proxied items,
+            `permissionSets` (capability sets as portable references),
+            `policies` and `oauth.useCeligoOauth` — each section present only
+            when the server has it. A template published before the artifact
+            widened carries tools and prompts only, so its `McpServer` doc has
+            none of the newer sections.
           items:
             type: object
             description: One resource doc tagged with its model type.
@@ -881,6 +893,7 @@ components:
                   - Api
                   - Tool
                   - Prompt
+                  - McpResource
                 x-enumDescriptions:
                   Integration: Integration workspace resource (integration templates only)
                   McpServer: MCP server resource (MCP server templates only)
@@ -896,6 +909,7 @@ components:
                   Api: Builder-mode API resource
                   Tool: Tool resource invoked by MCP servers, APIs, and flows
                   Prompt: Inline prompt definition of the MCP server (MCP server templates only)
+                  McpResource: Celigo Storage file the MCP server serves as a resource — name, description, MIME type and size, never the bytes (MCP server templates only)
                 description: |-
                   Resource class this doc describes. Which classes appear depends
                   on what the template zip contains; `Integration` and `Prompt`

package/dist/mcp-server.yml

@@ -1018,6 +1018,11 @@ paths:
         Every request starts a new install, so retrying after a timeout or an
         ambiguous failure creates a duplicate server or install-mode
         Integration.
+
+        Requires the `install:template` permission. A template that packs
+        resource files is refused up front in a sandbox account (422
+        `MCP_TEMPLATE_RESOURCE_UNAVAILABLE` naming `sandbox`) — install it from
+        a production account.
       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.
@@ -1118,6 +1123,8 @@ paths:
                         message: The MCP template contains an invalid entry.
         '401':
           $ref: '#/components/responses/401-unauthorized'
+        '403':
+          $ref: '#/components/responses/403-forbidden'
         '404':
           description: The `runKey` does not match an uploaded file.
           content:
@@ -1149,8 +1156,9 @@ paths:
             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.
+            `MCP_TEMPLATE_RESOURCE_TOO_LARGE`), plus `MCP_TEMPLATE_RESOURCE_UNAVAILABLE`
+            naming `sandbox` when the template packs resource files and the
+            account is a sandbox. Retrying with the same ZIP fails the same way.
           content:
             application/json:
               schema:
@@ -1166,6 +1174,12 @@ paths:
                     errors:
                       - code: MCP_TEMPLATE_DEPENDENCY_MISSING
                         message: The MCP template is missing connection 6ab130000000000000000c01.
+                sandboxResources:
+                  summary: Template packs resource files, installing account is a sandbox
+                  value:
+                    errors:
+                      - code: MCP_TEMPLATE_RESOURCE_UNAVAILABLE
+                        message: Resource file sandbox is missing or cannot be exported.
   /v1/mcpservers/template/{_templateId}:
     post:
       x-internal: false
@@ -1183,19 +1197,50 @@ paths:
         What the install creates depends on the template's contents, reported by
         the response's `destination` envelope:
 
-        - **Prompt-only templates** (no tools) create the MCP server
-          immediately, disabled. `destination.resourceType` is `mcpservers`.
-        - **Tool-bearing templates** hand off to the Integration installer:
-          `destination.resourceType` is `integrations` and names an Integration
-          in install mode, where connection mapping and the remaining install
-          steps continue. The MCP server is created — disabled — by the
-          Integration's terminal install step, after the tools are cloned.
+        - **Prompt-only templates** (inline prompts and nothing else) create
+          the MCP server immediately, disabled. `destination.resourceType` is
+          `mcpservers`.
+        - **Every other template** — one that packs tools, APIs, connections,
+          Celigo Storage resources, upstream MCP connections or capability sets
+          — hands off to the Integration installer: `destination.resourceType`
+          is `integrations` and names an Integration in install mode (it
+          carries the server's name; its setup page is titled *Install MCP
+          server: name*), with an install step per packed connection and a
+          terminal step that copies the resource files into that Integration's
+          folder in Celigo Storage and creates the MCP server, disabled. The
+          remaining refusals surface inside those steps, not on this request.
+          On a connection step's save: 409 `MCP_TEMPLATE_CONNECTION_INCOMPATIBLE`
+          when the template connection requires end-user credentials and the
+          installer reuses an existing connection of a different connector
+          type (only the type is compared — not the auth type or the end-user
+          fields; a newly created connection never trips it; the terminal step
+          re-checks the same rule as a backstop) — pick or create a connection
+          of the template's type on that step. On the terminal step: 422
+          `MCP_TEMPLATE_DEPENDENCY_MISSING` / `MCP_TEMPLATE_MEMBER_UNRESOLVED`
+          (a packed API or connection, or a capability-set member, that nothing
+          installed answers), the Celigo Storage refusals below, and 503
+          `MCP_TEMPLATE_INSTALL_RETRYABLE` (transient). The remedy is the same
+          for every one of them — fix the cause and retry that step, never
+          this POST, which installs again.
+
+        The installed server carries what the template packed: tools and APIs
+        (re-created in the companion Integration), prompts, resources, the
+        upstream MCP connections with the publisher's selected proxied
+        capabilities and overrides, which connections require end-user
+        credentials, the capability sets re-pointed at the new server's own
+        capabilities, the traffic policies, and Celigo as OAuth provider when
+        the publisher used it. It carries no end user, group, role, grant,
+        credential or network policy: the capability sets are created without
+        assignments, and nobody can call the server until an owner or
+        administrator grants access and enables it. A template published
+        before the artifact widened installs tools and prompts only until its
+        publisher re-exports it.
 
         Integration templates do not install through this path — they use
         `POST /v1/integrations/template/{_id}`. Each path rejects the other
         class: this one returns 404 for a template that is not a published
         MCP-server template, and the integration path rejects MCP-server
-        templates with a 400 `invalid_template` error.
+        templates with a 400 `invalid_template` error pointing at Upload MCP.
 
         Every request that reaches the platform starts a new install — there is
         no idempotency key, so retrying after a timeout or ambiguous failure
@@ -1206,9 +1251,11 @@ paths:
 
         Requires the `install:published:template` permission.
       x-celigo-ai-guidance:
-        - Send an empty JSON object as the body. Connection mapping for tool-bearing templates happens later, in the created Integration's install steps — never invent a connectionMap for this endpoint.
+        - Send an empty JSON object as the body. For every template beyond prompt-only (tools, APIs, connections, resources, upstream MCP connections or capability sets) connection mapping happens later, in the created Integration's install steps — never invent a connectionMap for this endpoint.
         - Never retry this POST after a timeout or an ambiguous failure — a request that reached the platform already started an install, and a second request installs a duplicate.
         - Branch the follow-up on destination.resourceType — "integrations" means install steps continue on the created Integration (its setup page); "mcpservers" means the disabled MCP server already exists and needs enabling and access before clients can use it.
+        - The installed server's capability sets have no assignments and the server is disabled — tell the installer to review the connections (which ones need end-user credentials), review any proxied capabilities, grant access, then enable it.
+        - A failure inside the created Integration's setup steps — a 409 on a connection step, a 422 / 503 on the terminal step — is fixed and retried on that step, never by sending this POST again.
       parameters:
         - name: _templateId
           in: path
@@ -1255,7 +1302,7 @@ paths:
                           - integrations
                         x-enumDescriptions:
                           mcpservers: The disabled MCP server created directly from a prompt-only template
-                          integrations: The install-mode Integration created for a tool-bearing template
+                          integrations: The install-mode Integration created for a template that packs tools, APIs, connections, resources, upstream MCP connections or capability sets
                         description: |-
                           Which resource type the install created — determines
                           where the caller continues the setup.
@@ -1300,15 +1347,24 @@ paths:
         '422':
           description: |-
             The install was rejected before anything was created. As-built
-            cases: the template packages capabilities an MCP-server template
-            cannot carry (`invalid_template` — only tools and inline prompts
-            are portable), a packaged tool is missing or inaccessible
-            (`invalid_template`), or `relativeURI` de-duplication exhausted its
-            `-2`…`-100` suffixes (`invalid_value` — the account already holds
-            100 servers on that URI; delete or rename some before installing
-            again). None of these are retryable unchanged — and never retry
-            the POST blindly, since a request that reached the platform may
-            already have installed something.
+            cases on this request: a packaged tool is missing or inaccessible
+            (`invalid_template`); the template packs resource files and the
+            installing account is a sandbox (`MCP_TEMPLATE_RESOURCE_UNAVAILABLE`
+            naming `sandbox` — install into a production account instead); or,
+            for a **prompt-only** template — the only class whose server is
+            created on this request — `relativeURI` de-duplication exhausted
+            its `-2`…`-100` suffixes (`invalid_value`: the account already
+            holds 100 servers on that URI; delete or rename some before
+            installing again). None of these are retryable unchanged — and
+            never retry the POST blindly, since a request that reached the
+            platform may already have installed something. For every other
+            template the server is created by the Integration's terminal
+            install step, so the same `invalid_value` exhaustion, the Storage
+            refusals for packed resources (`MCP_TEMPLATE_STORAGE_UNAVAILABLE`
+            when the account has no Celigo Storage,
+            `MCP_TEMPLATE_STORAGE_PERMISSION_REQUIRED`) and the other
+            terminal-step codes named in the description surface there, with
+            the Integration already in place — retry that step, not this POST.
           content:
             application/json:
               schema:
@@ -1320,12 +1376,12 @@ paths:
                     errors:
                       - code: invalid_value
                         message: Unable to generate a unique relative URI for the MCP server from /installed-mcp-server.
-                unsupportedCapability:
-                  summary: Template packages non-portable capabilities
+                sandboxResources:
+                  summary: Template packs resource files, installing account is a sandbox
                   value:
                     errors:
-                      - code: invalid_template
-                        message: 'Installing an MCP server supports only tools and prompts. Unsupported: apis, resources.'
+                      - code: MCP_TEMPLATE_RESOURCE_UNAVAILABLE
+                        message: Resource file sandbox is missing or cannot be exported.
   /v1/mcpservers/{_id}/template:
     get:
       x-internal: false
@@ -1334,24 +1390,36 @@ paths:
         - MCP Servers
       summary: Export an MCP server as a template ZIP
       description: |-
-        Generates a template ZIP from the MCP server and returns a temporary
-        signed URL for downloading it. The ZIP contains the server document,
-        its inline prompts, its tools, and the resources those tools depend on
-        (exports, imports, connections, scripts) — a prompt-only server (no
-        tools) exports successfully. The ZIP is the artifact a publisher
-        uploads when authoring an MCP-server marketplace template; installing
-        that template recreates the server via
-        `POST /v1/mcpservers/template/{_templateId}`.
+        Generates a template ZIP from the MCP server (the **Download MCP**
+        action) and returns a temporary signed URL for it. The ZIP carries the
+        whole server as a secret-free manifest (`mcpserver.json`) plus what it
+        depends on: tool and API attachments with their Tool and API documents
+        (and their exports, imports, connections, scripts), inline prompts,
+        the Celigo Storage files served as resources (bytes included),
+        upstream MCP connections with the selected proxied items and
+        overrides, which connections require end-user credentials, capability
+        sets (`permissionSets`) as portable references, traffic `policies`,
+        and whether Celigo is the OAuth identity provider. Never carried:
+        credentials, API tokens, end users, groups, roles, grants, end users'
+        own connections, network policies, request-log settings, the external
+        OAuth issuer and client, `showInPublicRegistry`. The manifest sets
+        `disabled: true`. A prompt-only server exports successfully.
 
-        Only tools and inline prompts are portable. A server that publishes
-        APIs (`apis[]`) or file resources (`resources[]`) fails the export up
-        front with a 400 `invalid_template` error — no ZIP is generated;
-        nothing is stripped to make it succeed.
+        The same ZIP feeds two paths: a Partner uploads it when publishing an
+        MCP-server marketplace template (installed with
+        `POST /v1/mcpservers/template/{_templateId}`); any account owner or
+        administrator installs it directly into another account or environment
+        with `POST /v1/mcpservers/template` after uploading it through
+        `GET /v1/s3SignedURL` (the **Upload MCP** action). A ZIP exported
+        before the artifact widened carries tools and prompts only — export
+        again to include the rest.
 
         The signed URL expires after about 60 seconds — download promptly, and
         call the endpoint again for a fresh URL rather than storing this one.
 
-        Requires the `create:mcpserver:template` permission.
+        Requires the `create:mcpserver:template` permission; a server that
+        serves resources also needs read access to those files in Celigo
+        Storage.
       parameters:
         - name: _id
           in: path
@@ -1391,33 +1459,73 @@ paths:
                   value:
                     signedURL: https://s3.amazonaws.com/templates/mcp-export/69eb9fb5b4fc023618e490b8.zip?X-Amz-Expires=60
                     key: mcp-export/69eb9fb5b4fc023618e490b8.zip
-        '400':
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
           description: |-
-            The server publishes capabilities a template cannot carry — only
-            tools and inline prompts are portable. Remove the APIs / file
-            resources (or export a server without them); retrying unchanged
-            fails identically.
+            The caller lacks the `create:mcpserver:template` permission
+            (`forbidden`), or — when the server serves resources — Celigo
+            Storage refused to read those files' metadata for the caller
+            (`MCP_TEMPLATE_STORAGE_PERMISSION_REQUIRED`). The export raises
+            that second code with the error store's shared message, which is
+            phrased for the install ("…required to install this MCP
+            template"); on this endpoint it means the download was refused
+            before any archive was built — nothing was installed. Grant the
+            caller read access to the server's resource files and retry.
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/Error'
               examples:
-                unsupportedCapability:
-                  summary: Server publishes APIs or file resources
+                forbidden:
+                  summary: The caller lacks the export permission
                   value:
                     errors:
-                      - code: invalid_template
-                        message: 'Installing an MCP server supports only tools and prompts. Unsupported: apis, resources.'
-        '401':
-          $ref: '#/components/responses/401-unauthorized'
-        '403':
-          $ref: '#/components/responses/403-forbidden'
+                      - code: forbidden
+                        message: You do not have permission to access this resource.
+                storagePermission:
+                  summary: The server serves resources the caller cannot read
+                  value:
+                    errors:
+                      - code: MCP_TEMPLATE_STORAGE_PERMISSION_REQUIRED
+                        message: Celigo Storage file creation is required to install this MCP template.
         '404':
           $ref: '#/components/responses/404-not-found'
+        '413':
+          description: |-
+            The resource files total more than the ZIP limit (32 MiB
+            uncompressed). Remove or shrink resources, or export a server
+            without them.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                zipTooLarge:
+                  value:
+                    errors:
+                      - code: MCP_TEMPLATE_ZIP_TOO_LARGE
+                        message: The MCP template zip exceeds the allowed size.
         '422':
           description: |-
-            The export could not assemble a complete ZIP — a tool or its
-            backing integration is missing or not accessible to the caller.
+            The export could not assemble a complete ZIP: a tool, API,
+            connection or backing integration is missing or not accessible to
+            the caller (`invalid_template`); a capability set names a member
+            that no longer exists on the server (`MCP_TEMPLATE_MEMBER_UNRESOLVED`,
+            naming the set and the member); a resource file is missing,
+            deleted, still uploading, or a folder (`MCP_TEMPLATE_RESOURCE_UNAVAILABLE`,
+            naming the file — folders and skills are not carried); or a
+            resource file exceeds 3 MiB (`MCP_TEMPLATE_RESOURCE_TOO_LARGE`,
+            naming the file). Fix the named dependency, set or file, or export
+            a server without it; retrying unchanged fails identically. The
+            export never refuses on resource count: a server cannot be saved
+            with more than 100 resources (`POST` and `PUT /v1/mcpservers`
+            answer 422 `resource_invalid` on `resources`), so a saved server
+            never meets the count cap. That refusal —
+            `MCP_TEMPLATE_RESOURCE_TOO_LARGE` naming `resource count` — is
+            raised by the ZIP's readers (the upload preview and both installs)
+            and is reached only by a manifest edited by hand to declare more
+            than 100.
           content:
             application/json:
               schema:
@@ -1429,6 +1537,24 @@ paths:
                     errors:
                       - code: invalid_template
                         message: The MCP server template contains a missing or inaccessible tool dependency.
+                memberUnresolved:
+                  summary: A capability set names a member the server no longer has
+                  value:
+                    errors:
+                      - code: MCP_TEMPLATE_MEMBER_UNRESOLVED
+                        message: Capability set Finance references 6ab130000000000000000a07, which cannot be installed.
+                resourceUnavailable:
+                  summary: A resource file cannot be exported
+                  value:
+                    errors:
+                      - code: MCP_TEMPLATE_RESOURCE_UNAVAILABLE
+                        message: Resource file pricing-policy.pdf is missing or cannot be exported.
+                resourceTooLarge:
+                  summary: A resource file exceeds 3 MiB
+                  value:
+                    errors:
+                      - code: MCP_TEMPLATE_RESOURCE_TOO_LARGE
+                        message: Resource file product-catalog.pdf exceeds the allowed size.
   /v1/mcpservers/{_id}/dependencies:
     get:
       x-internal: false
@@ -4265,9 +4391,10 @@ components:
           description: |-
             Files from Celigo Storage exposed to MCP clients as MCP resources.
             Each entry references a storage file by `_fileId`; the same file can
-            appear only once. Always returned in responses — servers created
-            before resource support return an empty array. Not supported on
-            sandbox servers.
+            appear only once, and a server holds at most 100 (a larger array is
+            refused with 422 `resource_invalid`). Always returned in responses —
+            servers created before resource support return an empty array. Not
+            supported on sandbox servers.
           x-celigo-ai-guidance:
             - |-
               Each resource exposes a Celigo Storage file to MCP clients.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celigo/api-specs",
-  "version": "0.2.218",
+  "version": "0.2.219",
   "private": false,
   "description": "Public OpenAPI bundles (dist/) and the celigo-cli lint schema pack (schemas.json).",
   "keywords": [

package/schemas.json

@@ -1,7 +1,7 @@
 {
 	"provenance": {
 		"repo": "celigo/integrator-api-specs",
-		"iasCommit": "a159c7c3",
+		"iasCommit": "adbfb1b8",
 		"generatedAt": "2026-11-02"
 	},
 	"roots": {