@jskit-ai/connectors-catalog 0.1.1

package/docs/algolia.md

@@ -0,0 +1,190 @@
+# Algolia
+
+Import `algoliaProvider` from `@jskit-ai/connectors-catalog/server/algolia`.
+This adapter verifies a backend key, searches indices, maintains records and checks indexing tasks.
+The portable configuration also carries the optional frontend key reference;
+the backend runtime neither resolves nor publishes that optional key.
+
+## Create the application and keys
+
+1. Sign into the Algolia dashboard. Open **Settings → Applications → Create
+   Application**. Choose the application name, plan and cluster region; supply
+   billing details when the selected plan requires them. Select the new
+   application before creating its keys.
+   [Application creation](https://support.algolia.com/hc/en-us/articles/4406975239441-How-do-I-create-an-application).
+2. Open **API Keys** and copy the **Application ID**. Under **All API Keys**,
+   choose **New API Key**. Name it for this application's backend, enable
+   `listIndexes` and `search`. Add `addObject` for indexing and task status,
+   and `deleteObject` for deletion when needed. Restrict it to the intended indices. Create
+   the key and store it in the backend environment as `ALGOLIA_API_KEY`.
+   The runtime does not require the Admin key.
+   [Key creation](https://support.algolia.com/hc/en-us/articles/9438531643665-How-do-I-generate-keys).
+3. If the frontend will query Algolia directly, create a separate key with only
+   `search`, restricted to indices containing data that those clients may read.
+   Store that value as `ALGOLIA_SEARCH_KEY`. The predefined Search-only key can
+   search all application indices, so do not assume it isolates private data.
+   [Key types](https://www.algolia.com/doc/guides/security/api-keys).
+4. Set appropriate validity, index and request restrictions when creating keys.
+   Referrer restrictions alone are not authorization. Replace or delete keys in
+   **API Keys → All API Keys** when access should end at Algolia. Local connector
+   disconnect only removes the local connection.
+   [Key restrictions](https://www.algolia.com/doc/guides/security/api-keys/in-depth/api-key-restrictions).
+
+## File and field ownership
+
+The editor and a manually composed CLI edit the same `integrations.json`:
+
+```json
+{
+  "schemaVersion": 1,
+  "registrations": {},
+  "integrations": {
+    "search": {
+      "provider": "algolia",
+      "displayName": "Product search",
+      "accountMode": "shared",
+      "scopes": [],
+      "authentication": {
+        "method": "api-key",
+        "secretRef": "env:ALGOLIA_API_KEY"
+      },
+      "settings": {
+        "applicationId": "YOURAPPLICATIONID",
+        "publicApiKeyRef": "env:ALGOLIA_SEARCH_KEY"
+      }
+    }
+  }
+}
+```
+
+The application ID is public configuration. The two key values stay outside
+source. Omit `publicApiKeyRef` when all searches go through the backend. The
+reference validator accepts the same `env:NAME` format as other connectors.
+The shared UI provides an Application ID text field, optional public-key
+reference and the primary API-key reference. Vibe64 provides a separate Env
+shortcut for each configured key, including a notice that the frontend key may
+be published. Clearing its reference removes the shortcut, not the Env value.
+Sharing grants remain a separate host responsibility.
+
+The app ID must be 1–63 alphanumeric characters in this fragment so it forms
+one DNS label. This is a runtime validation boundary, not a claim that Algolia
+issues IDs of every such length. Settings changes require verification again.
+The destination is fixed to `https://<application-id>.algolia.net`; arbitrary
+hosts and another application's host cannot receive this connection's key.
+
+## Runtime and AI composition
+
+Use the [API-key source pattern](../patterns/api-key-connection/PATTERN.md) with
+`providers: [algoliaProvider]`, the file connection store, the application's
+reference resolver and its authorization policy. Both configuration and runtime
+state are text files. No database, editor process or managed service is required.
+
+```js
+await connections.connectApiKey({ context, integrationId: "search" });
+const indices = await connections.invoke({
+  context, integrationId: "search", operation: "indices.list",
+  input: { page: 0, hitsPerPage: 100 }
+});
+const results = await connections.invoke({
+  context, integrationId: "search", operation: "index.search",
+  input: { indexName: "products", query: "phone", page: 0, hitsPerPage: 20 }
+});
+```
+
+`indices.list` performs `GET /1/indexes`; verification invokes its default page
+zero, with 100 entries requested. `listIndexes` permission is required, and the
+response's `items` and optional `nbPages` remain intact. Empty indices still
+allow verification. This does not prove that `search` is granted on a particular
+index. [List indices](https://www.algolia.com/doc/rest-api/search/list-indices).
+
+`index.search` performs `POST /1/indexes/{indexName}/query`, with JSON query,
+page and page-size values. It requires `search`, preserves hits and pagination,
+and defaults to an empty query, page zero and 20 hits. Index names are encoded
+as one path component, limited to 255 characters and cannot be `.` or `..`.
+Both operations accept pages from zero to 2147483647 and page sizes 1–1000 as
+local fragment bounds; provider index/key limits may be tighter. Search does not
+bypass Algolia's retrieval limits or automatically browse the full dataset.
+[Single-index search](https://www.algolia.com/doc/rest-api/search/search-single-index).
+Queries must fit 512 UTF-8 bytes; the validator checks bytes as well as string
+length. [Query limits](https://www.algolia.com/doc/api-reference/api-parameters/query).
+
+For direct frontend search, the application may deliberately resolve and expose
+only `publicApiKeyRef` plus `applicationId` after configuring a suitable
+search-only key. Never serialize `authentication.secretRef`'s resolved value to
+the browser. This runtime does not inspect the frontend key's ACL or install a
+search widget. Index settings, secured-key generation,
+recommendations and host failover are outside the fragment.
+
+## Automation and application ownership
+
+AI-assisted provisioning can use Algolia's CLI after a human completes
+`algolia auth login`; that creates a dashboard OAuth session. This is a separate
+operator bootstrap, not the API-key connection above.
+[CLI authentication](https://www.algolia.com/doc/tools/cli/authentication).
+Current CLI documentation exposes `algolia application create`, with name,
+region, plan and dry-run options. For example, review each request first:
+
+```sh
+algolia application create --name dogandgroom-search --region EU --plan free --dry-run
+```
+
+Actual creation requires the chosen plan's terms and, for paid plans, a payment
+method. An AI can prepare the requests; the operator owns those choices.
+[Create command](https://www.algolia.com/doc/tools/cli/commands/application/create).
+The older application-management guide says no programmatic management API
+exists; the July 2026 CLI documentation explicitly supports creation through the
+Dashboard API. Use the supported CLI rather than guessing private endpoints.
+
+With an explicitly supplied Admin key, the Search API can create restricted
+keys through `POST /1/keys`, including `acl`, `indexes`, description, validity
+and rate limits. Keep that bootstrap key out of the running connector and issue
+a lesser backend key for its required operations.
+[Key provisioning](https://www.algolia.com/doc/rest-api/search/add-api-key).
+
+The application owner creates its Algolia application and supplies a scoped key
+through private Env. Two keys in one Algolia application do not establish
+independent application capacity. Separate applications have their own plans;
+dedicated server isolation is a separate provider offering.
+[Application isolation](https://www.algolia.com/doc/guides/sending-and-managing-data/manage-indices-and-apps/manage-your-apps).
+This flow needs no OAuth callback, so editor VM and custom application domains
+do not add provider redirect registrations. This is search access, not user login.
+
+## Proof
+
+Focused tests use simulated provider responses and real temporary encrypted JSON
+state. They cover endpoint/header binding, public-key separation, rotation,
+restart, ownership, configuration changes, encoded index paths, UTF-8 query
+limits, paging, malformed responses and failures. Browser tests cover validated
+text inputs, optional-reference clearing, CLI import and save/reload. Live
+provider use, real account creation and generated sample apps are untested.
+
+## Maintain the search index
+
+Use `records.replace` with `{ indexName, objectID, attributes }` to create or
+fully replace a record. Pick a stable ID from the application's source record;
+omitted attributes are removed on replacement. Use `records.update` with the
+same inputs to update only specified attributes; this explicitly sets
+`createIfNotExists=false`. Both require `addObject`. Supply a nonempty attributes
+object and keep the record ID in `objectID`, not inside attributes.
+[Replace a record](https://www.algolia.com/doc/rest-api/search/add-or-update-object),
+[partial update](https://www.algolia.com/doc/rest-api/search/partial-update-object).
+
+`records.delete` takes `{ indexName, objectID }` and requires `deleteObject`.
+Each mutation returns a task ID, not evidence that search results already reflect
+the change. Call `tasks.get` with `{ indexName, taskID }`; keep the application
+work item pending for `notPublished` and complete it only for `published`.
+Task checks require `addObject`. Use a bounded application-owned polling schedule
+and retain task IDs for later recovery rather than blocking requests indefinitely.
+[Delete a record](https://www.algolia.com/doc/rest-api/search/delete-object),
+[task status](https://www.algolia.com/doc/rest-api/search/get-task).
+
+Keep ingestion behind application authorization. Publish only deliberately
+searchable data to frontend-accessible indices, and never publish the backend
+write key. Do not grant write ACLs to the public search key. A timeout does not
+prove a write failed; reconcile the known record/task before retrying, especially
+for partial update operators such as increments. No automatic retries are added.
+
+`test/algolia.test.js` now includes replacement, partial update, deletion and
+pending/published task progression through the real connection service. It
+retains existing search, key-separation, restart and failure tests. Six tests
+passed with controlled HTTP, without live indexing or account credentials.

package/docs/amazon-redshift.md

@@ -0,0 +1,229 @@
+# Amazon Redshift
+
+Import `amazonRedshiftProvider` from
+`@jskit-ai/connectors-catalog/server/amazon-redshift`. The runtime uses the official
+AWS Redshift Data SDK and explicit AWS credential references. It supports shared
+and assistant connections to a serverless workgroup or provisioned cluster.
+Per-user Identity Center federation is still unfinished; this shared connection
+must not be presented as each application user's independent AWS identity.
+
+## Portable configuration
+
+```json
+{
+  "schemaVersion": 1,
+  "registrations": {},
+  "integrations": {
+    "warehouse": {
+      "provider": "amazon-redshift",
+      "displayName": "Reporting warehouse",
+      "accountMode": "shared",
+      "scopes": [],
+      "authentication": {
+        "method": "api-key",
+        "secretRef": "env:AWS_SECRET_ACCESS_KEY"
+      },
+      "settings": {
+        "deploymentType": "serverless",
+        "region": "us-east-1",
+        "accessKeyIdRef": "env:AWS_ACCESS_KEY_ID",
+        "workgroup": "analytics",
+        "database": "dev"
+      }
+    }
+  }
+}
+```
+
+For a provisioned cluster, set `deploymentType` to `provisioned`, replace
+`workgroup` with `clusterIdentifier`, and optionally add `databaseUser`. For
+temporary AWS credentials add `sessionTokenRef`; the host renews the complete
+credential set. The default type is `serverless` and default region is
+`us-east-1`. Explicitly select the warehouse's real region. The form lists 34
+commercial regions; that list does not guarantee that every account/deployment
+supports every region. Noncommercial partitions and arbitrary endpoints are not
+accepted. This fragment takes a workgroup **name**, not an ARN.
+
+The shared schema selects the correct fields. Serverless requires `workgroup`;
+provisioned requires `clusterIdentifier` and accepts optional `databaseUser`.
+Both require `database` and AWS key references. CLI mixed-mode fields fail
+validation. Switching type in the shared form removes the other type's fields;
+it preserves credentials, region, database, other slots and extension data.
+Database identifiers retain their exact spelling and whitespace.
+
+## Administrator setup
+
+Use an existing warehouse when one is available. For a new serverless warehouse:
+
+1. In the AWS console, select the intended account and region and open Amazon
+   Redshift. Choose **Serverless dashboard > Create workgroup**.
+2. Enter the workgroup name and select the IP mode, VPC, subnets and security
+   groups for that workload. Choose capacity suitable for the account's budget.
+3. Create a namespace or select an existing namespace. For a new namespace,
+   supply its database name and configure administrator credentials, encryption
+   and logging. A warehouse's associated IAM role for data access is separate
+   from the identity that calls this connector.
+4. Review the selections and save. Once available, copy the workgroup name and
+   database name into the configuration.
+
+These console steps follow [Create a workgroup with a namespace](https://docs.aws.amazon.com/redshift/latest/mgmt/serverless-console-workgroups-create-workgroup-wizard.html).
+
+For a provisioned warehouse:
+
+1. In Amazon Redshift, choose **Clusters** and select the intended cluster.
+   To create one, choose **Create cluster** and supply its identifier, node
+   configuration and administrator credential method.
+2. Review database, VPC/subnet, security group, encryption and maintenance
+   settings before creating it. Copy its identifier and database name.
+3. Choose whether calls should use an IAM-derived database user or a specific
+   existing database user. Only the latter needs `databaseUser` in this file.
+
+See [Create a cluster](https://docs.aws.amazon.com/redshift/latest/mgmt/create-cluster.html).
+
+For either deployment type:
+
+1. Follow [AWS credential setup](aws-credentials.md). Grant the caller only the
+   needed `redshift-data` actions: `ListDatabases`, `ListSchemas`, `ListTables`, `DescribeTable`,
+   `ExecuteStatement`, `DescribeStatement`, `GetStatementResult` and
+   `CancelStatement` for the operations the application exposes.
+2. Grant the matching database credential action: serverless needs
+   `redshift-serverless:GetCredentials`; provisioned IAM-derived users need
+   `redshift:GetClusterCredentialsWithIAM`; provisioned explicit database users
+   need `redshift:GetClusterCredentials`. Restrict resource access in IAM.
+3. Have the database administrator grant access to the intended schemas/tables
+   to the resulting database identity. Use database permissions to enforce
+   read-only access where required; accepting SQL does not make it SELECT-only.
+4. Store the access key ID, secret key and any session token in the application's
+   secret environment. Enter references through Vibe64 or edit the JSON file.
+5. Save, then explicitly call `connectApiKey`. It lists one metadata page in the
+   configured database. An empty table list can still be a successful connection;
+   it does not prove permission to read every table or execute every statement.
+
+The credential combinations are specified by [ExecuteStatement](https://docs.aws.amazon.com/redshift-data/latest/APIReference/API_ExecuteStatement.html).
+The adapter does not use a host profile, instance metadata, database passwords
+or a Secrets Manager ARN as an implicit fallback.
+
+## Runtime contract
+
+| Operation | Input | Output |
+|---|---|---|
+| `databases.list` | Optional `maxResults` 1–1000 (default 100), opaque `nextToken` | `Databases` name page and optional `NextToken` |
+| `schemas.list` | Optional `schemaPattern`, `maxResults` 1–1000, `nextToken` | `Schemas` name page and optional `NextToken` |
+| `tables.list` | Optional `schemaPattern`, `tablePattern`, `maxResults` 1–1000 (default 100), opaque `nextToken` | `Tables` metadata page and optional `NextToken` |
+| `table.describe` | `table`; optional `schema`, `maxResults` 1–1000, `nextToken` | `ColumnList`, `TableName` and optional cursor |
+| `query.start` | Exact `sql`, required `clientToken` 1–64 characters; optional `parameters: [{name, value}]` | `Id` and submission metadata |
+| `query.status` | `statementId` | AWS statement status and execution metadata |
+| `query.results` | `statementId`; optional `nextToken` | One JSON result page with typed cells and column metadata |
+| `query.cancel` | `statementId` | AWS boolean `Status` acknowledgement |
+
+Database discovery uses the configured database to authenticate and can return
+other visible database names. It does not grant access to them or change this
+connection's target. Schema and table discovery remain in the configured database;
+use another explicitly configured connection to work in another database.
+The application authorizes metadata visibility as well as SQL. Names and opaque
+cursors remain unchanged; an absent or empty cursor ends pagination.
+See [ListDatabases](https://docs.aws.amazon.com/redshift-data/latest/APIReference/API_ListDatabases.html)
+and [ListSchemas](https://docs.aws.amazon.com/redshift-data/latest/APIReference/API_ListSchemas.html).
+Native framework consumers use those same SDK operations and project credentials.
+
+Table filters retain SQL metadata wildcards `%` and `_`; names and cursors are
+passed unchanged. See [ListTables](https://docs.aws.amazon.com/redshift-data/latest/APIReference/API_ListTables.html)
+and [DescribeTable](https://docs.aws.amazon.com/redshift-data/latest/APIReference/API_DescribeTable.html).
+
+SQL is preserved and locally capped at 200000 UTF-8 bytes. Parameter names are
+unique alphanumeric/underscore strings; values are nonempty strings, including
+exact decimal/large-integer text. The fragment permits 1–100 parameters, values
+up to 65536 characters. Omit the array for statements without parameters.
+These are local bounds; AWS validates SQL and converts parameter values.
+Use parameters for values rather than concatenating user input into SQL.
+See [SqlParameter](https://docs.aws.amazon.com/redshift-data/latest/APIReference/API_SqlParameter.html).
+
+The host authorizes the exact SQL, target and logical request before starting.
+Persist `clientToken` and the returned `Id` with application ownership in
+application-owned state; files work. AWS deduplication tokens have a limited
+retention window, so an ambiguous submission is not permission to issue a new
+token. AWS currently documents an eight-hour token window and 24-hour result
+retention in [Data API considerations](https://docs.aws.amazon.com/redshift/latest/mgmt/data-api.html).
+The runtime performs no automatic retries, polling, session reuse or batch SQL.
+
+Status/results/cancel first describe the statement and check its ID, database,
+workgroup or cluster, and explicit database user when configured. Matching a
+warehouse is not application-user ownership. The host must enforce ownership
+within a shared warehouse. Status metadata can contain SQL and database errors;
+return it only to an authorized caller. See [DescribeStatement](https://docs.aws.amazon.com/redshift-data/latest/APIReference/API_DescribeStatement.html).
+
+Results require `FINISHED` and `HasResultSet`. Preserve AWS column metadata and
+typed cells, including null, empty string, boolean, number and binary values.
+Binary fields are SDK `Uint8Array` values; encode them explicitly if your own
+transport sends JSON. Integers outside JavaScript's safe range are rejected;
+cast exact large integers to VARCHAR in SQL when they must be returned as text.
+No row-size parameter is invented for this endpoint: request another page only
+with AWS's cursor and use an authorized SQL limit when appropriate. See
+[GetStatementResult](https://docs.aws.amazon.com/redshift-data/latest/APIReference/API_GetStatementResult.html).
+
+Local abort, timeout or disconnect does not stop a remote query. Explicit
+`query.cancel` requests cancellation; inspect status separately if the final
+outcome is needed. A boolean acknowledgement is not proof of rollback. See
+[CancelStatement](https://docs.aws.amazon.com/redshift-data/latest/APIReference/API_CancelStatement.html).
+HTTP failures are redacted; credential renewal, IAM denial, throttling,
+configuration errors and missing resources are distinct outcomes.
+
+## Automation and application ownership
+
+An already authorized AI can create/configure resources using AWS APIs. The
+Serverless APIs expose `CreateNamespace`, `CreateWorkgroup` and their update/read
+operations; see [Workgroups and namespaces](https://docs.aws.amazon.com/redshift/latest/mgmt/serverless-workgroup-namespace.html).
+Provisioned creation uses [CreateCluster](https://docs.aws.amazon.com/redshift/latest/APIReference/API_CreateCluster.html).
+IAM policies, resource creation, database grants, billing choices and credential
+renewal require the corresponding administrator authority. This connector runs
+Data API operations; it does not provision accounts or warehouses.
+
+There is **no OAuth callback URL** for the implemented credential mode. Online,
+desktop and independent CLI can all use the same JSON and runtime. A customer's
+VPS or custom domain does not change the AWS API endpoint or credential binding.
+The application owner supplies AWS credentials through private Env or its
+credential store. Resource names and editable `env:` references do not grant
+AWS permissions. Separate IAM keys alone do not promise isolated service quotas. See [AWS ownership](aws-credentials.md#online-public-editor-and-independent-cli).
+
+## Per-user federation still to deliver
+
+The per-user design requires an organizational identity provider and IAM
+Identity Center trusted identity propagation. It is not implemented by this
+adapter's API-key mode. AWS describes the database integration and identity-bound
+statement access in [Data API trusted identity propagation](https://docs.aws.amazon.com/redshift/latest/mgmt/data-api-trusted-identity-propagation.html).
+
+The remaining configuration must capture the **identity provider issuer URL,
+OAuth client ID and secret reference, AWS region, Identity Center application
+ARN, bootstrap role ARN, and access role ARN**. The provider registration needs
+the application's explicitly configured callback, whether hosted by Vibe64 or
+operated independently. Start from the project's actual public address and
+register the exact callback implemented by the application. No production
+Redshift federation callback implementation is shipped yet.
+
+Remaining runtime work includes OIDC discovery and token verification, the
+bootstrap web-identity role exchange, IAM Identity Center token exchange,
+identity-enhanced access-role credentials, renewal and individual connection
+ownership. Each step must preserve issuer, audience, application and user
+boundaries. Detailed federation setup screens and controlled exchange tests
+remain planned. Do not substitute the builder's AWS credentials for this mode.
+
+## Focused verification
+
+`test/amazon-redshift.test.js` uses the real AWS SDK against controlled HTTP
+responses and protected temporary files. It covers both target types, explicit
+DB users, conditional CLI validation, metadata pages, SQL parameters, query
+states, results, target isolation, credentials, errors and cancellation.
+Shared-form browser checks pass at 390, 820 and 1440 pixels, including CLI
+imports, invalid fields, deployment changes and configuration export. Public
+editor phone/desktop checks pass for region selection, credential references,
+both target types, invalid-save rejection, inactive-field removal and reload.
+No live AWS registration, warehouse, SQL, generated app or federation flow has
+been exercised.
+
+## Existing-scope closeout — 13 September 2026
+
+Shared project-owned AWS credentials support serverless/provisioned targets, databases/schemas/tables discovery, table description, parameterized SQL submission, status, typed result pages and cancellation.
+
+No per-user Identity Center/OIDC federation or trusted identity propagation; no role-exchange/automatic credential renewal, default host credential chain, database password or Secrets Manager ARN mode, noncommercial partitions, custom endpoints, warehouse/IAM provisioning, batch SQL, automatic polling/retries or application job-ownership registry. SQL is not SELECT-only: database grants and application authorization enforce allowed work. The host stores request/statement ownership, handles uncertain submission and explicitly cancels remote jobs; local timeout/disconnect cannot do that. Unsafe JavaScript integer results are rejected; cast exact values to text. To extend: implement the already documented federation inputs/exchanges and tests, optional authentication modes and desired orchestration separately. No live provider account, provider registration, paid request or generated-application execution was tested. No new editor coding-assistant tool attachment is claimed. Other frameworks use the same project configuration and their own native tools; JSKIT is optional.
+
+16 source and 16 installed-package tests passed on September 13 using the actual AWS SDK with controlled HTTP and private files. September 12 compact/expanded form/lifecycle evidence is retained; no new UI run.

package/docs/amplitude.md

@@ -0,0 +1,210 @@
+# Amplitude assistant MCP
+
+Import `amplitudeProvider` and the explicit setup helper
+`registerAmplitudeClient` from `@jskit-ai/connectors-catalog/server/amplitude`.
+This is an assistant-owner OAuth connection. It exposes MCP tool discovery and
+authorized calls for analytics/content work, not event ingestion or app login.
+Amplitude's [client guide](https://amplitude.com/docs/amplitude-ai/amplitude-mcp/other-clients)
+requires remote HTTP MCP with OAuth; an API key cannot replace this flow.
+
+## Manual setup and account controls
+
+1. Sign into the intended Amplitude account and identify its US or EU residency.
+   Use that same region in the editor and client registration.
+2. If MCP access is blocked, an organization administrator opens **Settings →
+   Content Access → MCP** and reviews the organization-level setting.
+3. For project-specific access, the administrator opens **Org Settings → Role
+   Management**, creates/edits the role, and selects **AI Features → Use MCP
+   (read)** and, when needed, **Use MCP (write)**. Assign the role to the intended
+   user/group/service account and projects.
+4. In Vibe64, leave the new Client ID empty, set the Suggested callback URL and
+   choose **Register client and connect**. The workspace owner can register once
+   at the selected regional authority; Vibe64 saves the client ID in configuration
+   and its secret, callback and recovery client ID in development Env before
+   starting the application’s connection command. Existing Env values are not
+   overwritten. If local saving fails, recover the client from Env/provider state
+   before trying again. CLI users can use the setup operation below. The reviewed
+   documentation establishes dynamic registration, not a manual developer-app
+   creation screen; do not search for an invented console form.
+5. Enter the returned **Client ID** in Vibe64. Store its secret and the exact
+   callback URL through Env, then fill **Client secret reference** and
+   **Callback URL reference**. Keep secrets outside `integrations.json`.
+6. Save. Through the runtime's authorization flow, open the returned URL, sign
+   into Amplitude, review requested permissions and complete consent. The
+   callback must recover the same authenticated assistant owner.
+
+[Amplitude organization and role controls](https://amplitude.com/docs/amplitude-ai/amplitude-mcp#admin-controls).
+Tool discovery remains visible even where project-level calls are forbidden;
+discovery is not proof of access to every project or write operation.
+
+## Registration automation
+
+The US server's public
+[authorization metadata](https://mcp.amplitude.com/.well-known/oauth-authorization-server)
+advertises `/register`, code grants, refresh tokens, S256 PKCE, and
+`client_secret_post`/`none` authentication. Its
+[resource metadata](https://mcp.amplitude.com/.well-known/oauth-protected-resource)
+identifies `https://mcp.amplitude.com` as the OAuth resource. Equivalent EU
+metadata is served at `https://mcp.eu.amplitude.com`. These public metadata
+documents were read on 9 September 2026; no client or user account was created.
+
+After the operator authorizes registration, a setup script can call:
+
+```js
+import { registerAmplitudeClient } from "@jskit-ai/connectors-catalog/server/amplitude";
+
+const client = await registerAmplitudeClient({
+  region: "us",
+  clientName: "My assistant",
+  callbackUrl: "https://assistant.example/connections/amplitude/callback",
+  scopes: ["mcp:read", "offline_access"]
+});
+// Securely store client.clientSecret in the host's existing secret owner.
+// Put client.clientId in the portable registration; never log this object.
+```
+
+The helper uses the official MCP SDK to POST confidential-client metadata to
+the fixed regional registration endpoint. It requests one exact redirect URI,
+code/refresh grants and `client_secret_post`, and validates the returned client
+and redirect metadata. It returns `clientId`, `clientSecret` and any
+`clientSecretExpiresAt` value. This is a privileged setup result, never an
+ordinary connection-status response. The host must authorize invoking it and
+store its secret before exposing the nonsecret configuration.
+
+HTTPS callbacks and HTTP loopback callbacks are supported; credentials, query
+strings and fragments are rejected. The helper does not follow redirects,
+automatically retry, create an Amplitude account or complete consent. If
+registration times out, inspect the provider before retrying: a client might
+already exist. Registration metadata does not prove live issuance will succeed
+for every account or client policy; that acceptance check remains unperformed.
+
+For manual registration, use an HTTP client on your own machine:
+
+In Vibe64, expand **Set up Amplitude → OAuth client registration**. Set the
+region, permissions and **Suggested callback URL** first. **Copy registration
+endpoint** and **Copy registration request** provide the values for this
+project without requiring a Client ID. Copying sends no request. The example
+below is for CLI users or an HTTP client configured by hand.
+
+1. Create a **POST** request to `https://mcp.amplitude.com/register` for US,
+   or `https://mcp.eu.amplitude.com/register` for EU. Do not send it to the
+   `/mcp`, `/authorize` or `/token` endpoint.
+2. Set the request header `Content-Type: application/json`. Set the body to
+   raw JSON using the example below. Replace the example name and callback
+   with the owning application's name and exact callback shown in Vibe64.
+   The application must implement that route before user consent can finish.
+3. Match `scope` to the permissions selected in Vibe64. The example uses the
+   default read and refresh permissions; add `mcp:write` only when needed.
+4. Send once. On a successful response, copy `client_id` into **Client ID**.
+   Store `client_secret` as `AMPLITUDE_CLIENT_SECRET` through the project's
+   Env editor; enter `env:AMPLITUDE_CLIENT_SECRET` in **Client secret reference**.
+   Store the exact registered callback as `AMPLITUDE_CALLBACK_URL`; enter
+   `env:AMPLITUDE_CALLBACK_URL` in **Callback URL reference**.
+5. Do not save an error response, missing credentials or a different returned
+   redirect URI as a valid registration. Treat the response as secret material;
+   do not paste it into source, chat or a shared HTTP-client collection.
+
+```json
+{
+  "client_name": "My assistant",
+  "redirect_uris": ["https://assistant.example/connections/amplitude/callback"],
+  "token_endpoint_auth_method": "client_secret_post",
+  "grant_types": ["authorization_code", "refresh_token"],
+  "response_types": ["code"],
+  "scope": "mcp:read offline_access"
+}
+```
+
+The HTTP response uses `client_id` and `client_secret`; the JavaScript helper
+returns `clientId` and `clientSecret`. The helper also validates the response,
+so Node applications should reuse it. Other frameworks implement this same
+provider protocol using their own HTTP and secret-storage tools.
+
+## Portable configuration and runtime
+
+```json
+{
+  "schemaVersion": 1,
+  "registrations": {
+    "amplitude": {
+      "source": "own",
+      "clientId": "assigned-client-id",
+      "clientSecretRef": "env:AMPLITUDE_CLIENT_SECRET",
+      "callbackUrlRef": "env:AMPLITUDE_CALLBACK_URL"
+    }
+  },
+  "integrations": {
+    "analytics": {
+      "provider": "amplitude",
+      "accountMode": "assistant",
+      "scopes": ["mcp:read", "offline_access"],
+      "authentication": { "method": "oauth2", "registrationRef": "amplitude" },
+      "settings": { "region": "us" }
+    }
+  }
+}
+```
+
+The UI and CLI use the same parser and JSON. Region defaults to US. Read access
+and refresh access default on; content writes default off. `tools.list` and
+`tools.call` require a granted read permission. Amplitude additionally enforces
+write/project permissions at call time. The host's authorization callback must
+validate each requested tool name and its argument ownership before execution.
+
+Use the ordinary [OAuth file pattern](../patterns/oauth-connection/PATTERN.md)
+with `providers: [amplitudeProvider]`, and the
+[assistant OAuth pattern](../patterns/assistant-mcp-oauth/PATTERN.md) for tool policy.
+`beginAuthorization` creates a state/PKCE attempt. `completeAuthorization`
+exchanges the code, initializes MCP and lists tools before persisting the grant.
+Consent, code exchange and refresh all target the selected regional origin;
+authorization and both token grants include its OAuth resource identifier.
+Changing region invalidates pending/connected grants. Runtime state remains
+encrypted text files using the existing file-store owner.
+
+`tools.list` takes an optional opaque cursor. `tools.call` takes a tool `name`
+and `arguments` object. The provider uses the standard `/mcp` endpoint and the
+existing MCP transport; it does not automatically execute tools, attach them
+to an assistant, follow returned URLs or grant sampling/elicitation capabilities.
+Tool-level `isError` results remain data for the host to handle. Cancellation
+stops local work and attempts session cleanup; it cannot undo accepted writes.
+Disconnect removes local state without revoking all provider access.
+
+## Connection ownership and callbacks
+
+This fragment is for an explicitly configured assistant host. That host owns its
+client registration, callback, private credentials and grants; it may be an
+application-owned assistant or an opt-in editor tool. Merely adding the provider
+to a project does not authorize the editor's coding assistant. It does not supply
+published app-user login. The host's callback may differ from the published app's
+domain, but it must match that host's real route and registered redirect URI.
+
+AI can automate client registration and prepare configuration after authorized
+setup inputs are supplied. Register the host's actual callback with the selected
+US or EU endpoint, then retain the returned credentials in that host's private
+Env. User sign-in/consent and organization permission changes remain owner/admin
+actions. Separate client IDs do not prove independent Amplitude quotas for users
+of the same organization. If the callback changes, update the client registration
+and callback Env; a new hostname does not change the connection owner.
+
+This adapter does not implement native public-client authentication, the
+production event API, progressive-discovery UI, Amplitude service-account setup
+or app-user OAuth.
+
+## Focused proof
+
+Eight tests cover US/EU registration metadata and code/refresh resource binding,
+PKCE, file restart, credential encryption, region changes, owner isolation,
+exact tool policy, declined/insufficient consent, malformed discovery, provider
+failures, cancellation and no automatic registration replay. Editor proof
+covers region, permission choices, secret references and persistence. Provider
+signup, live registration/consent, live tool calls and generated apps are excluded.
+
+
+## LIMITATIONS
+
+Editor coding-assistant tool attachment is deferred. For example, this runtime
+can call an authorized Amplitude analytics tool from an explicitly composed
+application-owned assistant, but configuring it in Vibe64 does not let Codex or
+OpenCode answer “where are customers dropping out of my funnel?” from your live
+Amplitude data. Registration and consent do not attach tools to editor chat.
+No live Amplitude registration, consent or generated application was exercised.