connectors 0.1.0

data/CONTRIBUTING.md

@@ -0,0 +1,60 @@
+# Development and contributing
+
+Read the [README](README.md) for host setup, the [architecture](docs/architecture.md) for execution boundaries, and the [connector guide](docs/adding-connectors.md) for provider additions.
+
+## Local setup
+
+Use Ruby 3.4.8 (`.ruby-version`), PostgreSQL 16 and Python 3.9+ for the independent MCP fixture. Bundler installs the development/test dependencies from `Gemfile`; consumers receive only `connectors.gemspec` runtime dependencies. `Gemfile.lock` records the development baseline.
+
+From the repository root:
+
+```sh
+bundle install
+export RAILS_ENV=test
+export DATABASE_URL=postgresql://localhost/connectors_test
+bundle exec rake app:db:prepare
+bundle exec rspec --order random
+bundle exec rubocop
+```
+
+Use a disposable database: the suite includes committed-record concurrency tests and cleanup. Do not point it at a host's development or production data. PostgreSQL role permissions must allow database creation, or create the test database beforehand. `PYTHON` can select the Python executable; otherwise tests use `python3`. Local socket/loopback access is required by MCP interoperability and streaming tests.
+
+Use a TCP database connection, as CI does, when validating concurrency changes. MCP tests use `stub_mcp_dns` to replace only provider fixture lookups; never stub all DNS resolution, because the PostgreSQL driver uses it too.
+
+The dummy Rails application lives in `test/dummy`. It provides UUID owners, synthetic encryption keys, test routes and fixture connectors. Its keys and authentication setup are not installation defaults for host applications.
+
+## Test workflow
+
+For behavior changes, first write a failing RSpec example that demonstrates the requirement; run it, implement the smallest change, then rerun it. Use request tests for HTTP access/response contracts and service tests for Ruby entry points. Stub external providers with WebMock; never require personal credentials or real writes in the automated suite. Use real PostgreSQL connections for locking/concurrency claims.
+
+Examples:
+
+```sh
+bundle exec rspec spec/requests/credentials_crud_spec.rb
+bundle exec rspec spec/connectors/mcp/client_spec.rb
+bundle exec rspec --order random
+bundle exec rubocop
+```
+
+Report the command and seed when reporting a failure. A test count is not a coverage percentage; there is currently no enforced line/branch coverage threshold.
+
+## Package verification
+
+```sh
+bundle exec ruby script/verify_package.rb
+```
+
+This strict-builds the gem, checks required files and local documentation links, installs it into a temporary gem directory without downloading dependencies, then boots a separate Rails host against the installed artifact. It checks the shipped registry, migration paths and vendored MCP schema. Dependencies must already be installed with Bundler. Temporary artifacts are removed automatically. The same check runs through `spec/packaging_spec.rb` in the full suite, so CI exercises it too.
+
+The test suite validates provider behavior with fixtures and local interoperability servers. It does not certify live provider availability, account permissions, every supported Ruby version, or production load.
+
+## Change conventions
+
+- Keep provider-specific code under `app/connectors/<provider>/`; reusable mechanisms belong under `lib/connectors/`.
+- Add host requirements, examples and API changes to the relevant guide and `openapi.yaml`. Record compatibility changes under `Unreleased` in `CHANGELOG.md`.
+- Avoid provider secrets in fixtures, logs, failures and screenshots. Use synthetic credentials and sanitized captured public metadata.
+- Do not edit already released migrations to upgrade existing hosts. Add migrations and upgrade instructions.
+- For protocol changes, retain upstream attribution and add contract/interoperability tests. See the [vendored schema notes](lib/connectors/mcp/protocol/README.md).
+- Keep HTTP retries explicit, particularly for actions that can produce side effects.
+
+Before handing off a change, include the problem, changed behavior, tests run and any unresolved limitation. Release preparation is documented separately in [releasing](docs/releasing.md).

data/MCP_CLIENT.md

@@ -0,0 +1,168 @@
+# External MCP connections
+
+The engine consumes remote MCP **2026-07-28** servers through Streamable HTTP. It supports public servers, bearer tokens, custom authentication headers, and user OAuth with discovery, PKCE, registration, refresh and scope upgrades. Tools remain scoped to their grant; they are not added to the global connector registry.
+
+The implementation uses public helpers from `mcp` **1.6.0**, `json_schemer` **2.5**, and `event_stream_parser` **1.0**. Its durable OAuth coordinator and HTTP transport are owned by this engine. The SDK's synchronous OAuth flow and high-level tool projection did not meet the reviewed requirements. No SDK private methods are patched or invoked. Server result types are validated against the vendored, versioned official schema; its source and license are in [protocol/README.md](lib/connectors/mcp/protocol/README.md).
+
+## Installation and host setup
+
+Run `bundle install` and the host's migrations. The new migration creates encrypted, expiring authorization and interaction records, with PostgreSQL foreign keys and one-time claims. Existing connector tables and credentials are preserved.
+
+Follow the [host installation guide](README.md#installation), including encryption and trusted authentication middleware. Configure the engine's existing owner/principal resolvers. These remain the authentication boundary; callers must never supply their own trusted principal list through request parameters.
+
+```ruby
+Connectors.configure do |config|
+  config.owner_class_name = "User"
+  config.current_owner_resolver = ->(controller) { controller.request.env["connectors.current_owner"] }
+  config.host_base_url = ENV.fetch("APP_BASE_URL")
+
+  # Must match the URI registered with the authorization server / CIMD document.
+  config.mcp.callback_url = ENV.fetch("MCP_CALLBACK_URL")
+end
+```
+
+Without an explicit MCP callback URL, the engine uses its mounted `/mcp/oauth/callback` endpoint under `host_base_url`. A split frontend/backend host can configure a frontend callback and POST the returned parameters to the engine callback endpoint. The callback request must resolve to the same owner that started authorization.
+
+Only HTTPS destinations are allowed by default. Private, loopback and link-local addresses are refused after DNS resolution. The chosen address is pinned for the request while preserving TLS hostname verification. Redirects and environment proxies are not followed. Configure an explicit hostname in `config.mcp.private_hosts` for an intended private enterprise server; use `config.mcp.allow_loopback_http = true` only for deliberate local development/testing.
+
+## Create a connection
+
+Use the existing credential endpoint, with `type: "mcp"`:
+
+```json
+{
+  "type": "mcp",
+  "name": "My MCP server",
+  "data": {
+    "server_url": "https://server.example/mcp",
+    "auth_mode": "oauth"
+  }
+}
+```
+
+Supported credential fields:
+
+| Field | Use |
+| --- | --- |
+| `server_url` | Exact remote MCP endpoint. |
+| `auth_mode` | `none`, `bearer`, `headers`, or `oauth`. |
+| `bearer_token` | Secret for `bearer` mode. |
+| `headers` | Secret JSON object for custom header authentication. Transport-owned headers cannot be overridden. A custom `Authorization` header requires `headers` mode. |
+| `authorization_server` | Optional issuer selection when the resource advertises multiple authorization servers. |
+| `client_information` | Optional preregistered OAuth client: `client_id`, exact `issuer`, optional `client_secret`, and `token_endpoint_auth_method`. |
+
+OAuth token/client state is internal. Credential APIs reject attempts to inject it. `include_data=true` returns only server URL, authentication mode and issuer selection for MCP connections. Editors can invoke shared connections; only owners can replace credentials or perform OAuth. Sharing grants access to the remote account represented by the grant.
+
+For managed credentials, the existing secrets resolver can supply authentication fields. Configured client secrets are resolved at exchange/refresh time and are not duplicated into pending transactions or the token namespace. Changes to owner, destination, authentication fields or managed-secret reference invalidate pending work and token bindings.
+
+## ClickUp
+
+ClickUp is a built-in named MCP connector. Create it without supplying an endpoint or secrets:
+
+```http
+POST /connectors/credentials
+Content-Type: application/json
+
+{"type":"clickup","name":"ClickUp workspace"}
+```
+
+Then POST `/connectors/credentials/:id/mcp/authorize`, open the returned `authorization_url` for the owner to consent and select Workspaces, and complete the shared MCP callback. The host must configure its callback URL and owner resolver as described above. ClickUp's advertised dynamic registration handles client registration; a preregistered client is optional. This does not use the separate ClickUp REST API OAuth configuration.
+
+After authorization, GET `/connectors/credentials/:id/mcp/tools` and invoke a returned tool name through the shared call endpoint. The tool catalog and schemas come from the authorized server; the engine does not maintain a fixed ClickUp tool list. Permissions and remote rate limits remain controlled by ClickUp.
+
+The named connector fixes the official endpoint to `https://mcp.clickup.com/mcp` and authentication to OAuth. API tokens, custom authentication headers and endpoint overrides are rejected, including values supplied by a managed-secret resolver. Owners can replace client registration, which clears previous authorization. Disconnect uses the shared local revocation behavior.
+
+`GET /connectors/types/clickup` exposes `connector.mcp` metadata with endpoint, authentication mode, protocol version and grant-scoped URL templates. Replace `:id` with the created credential ID. `connector.redirect_uri` uses the same callback resolver as authorization. The generic MCP type exposes the same workflow metadata, with a user-configured endpoint and authentication mode.
+
+**Evidence and validation (2026-09-22):** [ClickUp's official documentation](https://developer.clickup.com/docs/connect-an-ai-assistant-to-clickups-mcp-server) specifies the endpoint and OAuth-only authentication. Its live 401 challenge points to [protected-resource metadata](https://mcp.clickup.com/.well-known/oauth-protected-resource/mcp), advertising `read` and `write` scopes. Its [authorization-server metadata](https://mcp.clickup.com/.well-known/oauth-authorization-server) advertises S256 PKCE, dynamic registration, public-client token authentication and required callback issuer identification. It advertises `authorization_code` without `refresh_token`; registration requests respect that metadata. Endpoints and scopes are discovered at runtime, not copied into provider-specific OAuth code.
+
+Request specs use captured public metadata and simulated registration/token/tool responses. The synthetic tool in those specs is explicitly a fixture. Live verification has covered public discovery and a demo owner completing consent with encrypted credential storage. Authenticated tool discovery/invocation against that Workspace has not been verified by the automated fixture suite.
+
+## Discover, invoke and resume
+
+Paths below are relative to the engine mount, normally `/connectors`.
+
+| Method and path | Behavior |
+| --- | --- |
+| `GET /credentials/:id/mcp/tools` | Returns `{ "tools": [...] }` with complete native descriptors and schemas. Requires viewer access. |
+| `POST /credentials/:id/mcp/tools/call` | Body: `{ "name": "tool_name", "arguments": {} }`. Requires editor access. Returns the MCP tool result. |
+| `POST /credentials/:id/mcp/interactions/resume` | Body: `{ "interaction_id": "...", "responses": { ... } }`. Requires the initiating actor's editor access. |
+| `POST /credentials/:id/mcp/authorize` | Owner-only. Returns `authorization_url`. Accepts an optional `authorization_context` from a failed MCP request. |
+| `GET` or `POST /mcp/oauth/callback` | Accepts `state`, `code`, `iss` or an OAuth `error`; completes a one-time authorization transaction. |
+| `POST /credentials/:id/revoke` | Owner-only local disconnect: marks the grant revoked and clears stored authentication fields. It does not claim to revoke tokens at the remote authorization server. |
+
+Arguments are validated without coercion or dropping extra fields. JSON Schema 2020-12 and draft-07 are supported; external schema references are disabled. Output schemas are checked. Content blocks and structured results, including arrays/scalars/null, are preserved. `isError: true` is a completed tool result, distinct from HTTP or protocol failure.
+
+The Ruby application entry points use the same access policy as HTTP:
+
+```ruby
+client = Connectors::MCP::Client.new(grant: grant, actor: current_owner)
+client.tools
+result = client.call_tool(name: "search", arguments: { "query" => "ruby" })
+```
+
+Pass trusted `principals:` when the host uses team/workspace sharing. Create a client for the operation; do not share a mutable client instance across worker threads. Use `Client` and `Authorization` as application entry points; transport and schema classes are implementation helpers.
+
+A failed call can return HTTP 401 with `error.type: "authorization_required"` and an encrypted `authorization_context`. Pass that context to the owner-only authorize endpoint so it retains the **actual failed operation's** scope challenge. After consent, retry the intended operation explicitly. Unrelated 403s are not treated as scope upgrades. Ruby callers can catch `Connectors::MCP::AuthorizationRequired` and pass its `challenge` to `Authorization#start`.
+
+No tool call is automatically replayed after a timeout or broken stream. Its remote outcome may be unknown. A recognized authentication failure can trigger one coordinated refresh and one retry. Protocol errors retain their numeric code in Ruby but never trigger an automatic legacy downgrade.
+
+## OAuth registration and token handling
+
+The engine follows protected-resource, OAuth authorization-server and OIDC discovery. It requires advertised S256 PKCE, binds client information to the selected issuer, validates callback issuer/state, and includes the MCP resource in authorization/token requests.
+
+Registration preference is preregistration, advertised Client ID Metadata Documents (CIMD), then advertised Dynamic Client Registration (DCR). Otherwise the owner must provide client information. DCR is a compatibility mechanism, not assumed universally available.
+
+To use CIMD, publish a public HTTPS JSON document with matching `client_id`, `client_name` and `redirect_uris`, then set `config.mcp.client_metadata_url`. The URL must identify that document. The engine validates it before use; it does not publish a document for your host automatically.
+
+Token endpoint authentication supports `none`, `client_secret_basic`, `client_secret_post`, and host-signed `private_key_jwt`, subject to server metadata. For the last method, configure:
+
+```ruby
+config.mcp.assertion_provider = ->(client_id, token_endpoint) {
+  # Return a short-lived JWT signed by the host's key manager with the required
+  # issuer, subject, audience, expiry and replay protection for this registration.
+  MyKeyManager.oauth_client_assertion(client_id: client_id, audience: token_endpoint)
+}
+```
+
+The host owns signing-key management; the engine does not invent a signing key or JWT policy. Requested scopes are retained separately from token response scopes. `offline_access` is requested only when advertised. Refresh rotation is serialized across processes; transient failures preserve credentials, while `invalid_grant` requires reconnect. Grants expose token expiry through their existing `expires_at` field.
+
+## Elicitation, subscriptions and cancellation
+
+A host that implements the corresponding presentation can enable `config.mcp.elicitation_modes = ["form", "url"]`. The default is empty, and unadvertised modes are rejected.
+
+An `input_required` result includes `interaction_id` and the server's input requests. The engine retains the original call and opaque state in encrypted storage. Present the request to the user, then resume with responses keyed by the server's input-request IDs. Form acceptance includes schema-valid `content`; URL acceptance, decline and cancel omit content. URL acceptance is consent to an external interaction, not proof that it completed. Never prefetch/open a URL automatically; show the requesting server and full URL, then open it only after user consent. Third-party credentials must stay outside this client.
+
+Each resume is claimed once. A duplicate submission is rejected, not replayed. State-only continuations can be resumed with `{}`; hosts should back off rather than loop immediately. Limits bound rounds and expiry. This is not a guarantee of exactly-once execution at the remote server.
+
+For on-demand tools-list notifications:
+
+```ruby
+cancellation = Connectors::MCP::Cancellation.new
+client = Connectors::MCP::Client.new(grant: grant, actor: current_owner, cancellation: cancellation)
+client.subscribe { |notification| handle_mcp_notification(notification) }
+# Another thread can call cancellation.cancel to close an idle stream.
+```
+
+The stream validates acknowledgment, filter and correlation. It ends on cancellation, graceful completion, deadline, size limit or error. Hosts can start a fresh subscription after disconnection. The engine starts no background daemon and maintains no cross-request tool cache.
+
+## Limits, maintenance and supported scope
+
+Defaults: 5-second connection timeout, 30-second request/authorization deadline, 300-second subscription deadline, 4 MiB request/response limit, 100 pages, 1,000 tools, 10 interaction rounds, 15-minute pending-state expiry, and a 1-second schema-validation deadline. Settings are available on `config.mcp`; configure positive bounds appropriate for the host. Error messages and filtered Rails parameters avoid exposing authentication material and tool input bodies.
+
+Upstream HTTP 429 responses return HTTP 429 with `error.type: "rate_limited"`. Valid `Retry-After` guidance is exposed in the response header and `error.retry_after` as a string containing seconds or an HTTP date; missing or malformed guidance is omitted. Tool calls are not automatically replayed. Other upstream HTTP failures remain sanitized 502 responses.
+
+Schedule `bundle exec rake connectors:mcp:cleanup` through the host's existing scheduler to delete expired pending records. There is no additional scheduler dependency.
+
+This release targets **2026-07-28 remote tools**. It does not advertise historical session-based transports, local stdio execution, prompts/resources product APIs, sampling, roots, Tasks, Apps, client-credentials grant extensions or enterprise authorization extensions. Those are separate protocol features, not implicit support claims. `private_key_jwt` client authentication above is supported for user OAuth; that does not imply support for the separate machine-to-machine grant extension.
+
+## Validation
+
+Validated on 2026-09-22 after packaging and documentation review: **543 examples, 0 failures** (random seed `17450`, frozen lockfile), **200 Ruby files with no RuboCop offenses**, and a strict gem build plus isolated installation/boot check. This includes the existing connector regression suite.
+
+RSpec covers protocol/schema contracts, authentication/registration, access isolation, secret serialization, real PostgreSQL concurrency, durable resume, real chunked SSE and idle cancellation. Interoperability runs against:
+
+1. The official Ruby SDK 1.6.0 server over real HTTP.
+2. An independent Python stdlib fixture (`spec/support/mcp/oauth_server.py`, fixture version 1), covering public/bearer access and OAuth discovery, PKCE, callback completion in a separate Rails process, scope upgrade and refresh. Its test-only consent is automatic.
+
+Run `bundle exec rspec --order random` and `bundle exec rubocop` after preparing an isolated PostgreSQL test database. Tests also need Python 3.9+ for the independent fixture. No production credentials or external account authorization is needed. These tests establish the documented integration behavior; they are not an official conformance certification or a claim that every hosted MCP provider has been tested.

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright Jackson Helio
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,146 @@
+# Connectors
+
+A mountable Rails engine for connecting accounts to provider APIs and remote MCP servers. It owns credential storage, authentication with providers, action execution, webhooks and polling. Your application owns user authentication, business workflows and scheduling.
+
+**Status:** initial release series `0.1.x`. Check [RubyGems](https://rubygems.org/gems/connectors) for published versions. Package validation is separate from production acceptance for a particular host and provider.
+
+## Requirements
+
+| Component | Requirement | Validation baseline |
+| --- | --- | --- |
+| Ruby | 3.2 or later | Ruby 3.4.8 locally and in the CI configuration |
+| Rails | 8.1.3 or later in the 8.1 series | Rails 8.1.3 |
+| Database | PostgreSQL 13+; migrations use UUIDs, JSONB and partial indexes | CI targets PostgreSQL 16 |
+| Identity | Persisted owner model with UUID primary keys; sharing principals also use UUIDs | Dummy `Owner` model in tests |
+| Encryption | Host-configured Active Record Encryption keys and stable Rails `secret_key_base` | Synthetic keys in tests |
+
+The declared Ruby minimum matches Rails' requirement; it is not a claim that every Ruby/OS combination has been tested. SQLite, MySQL and integer owner IDs are not supported by the shipped migrations. Install the host's PostgreSQL adapter (`pg`) in its Gemfile.
+
+## Installation
+
+For a published release, add to your host's Gemfile:
+
+```ruby
+gem "connectors", "~> 0.1.0"
+gem "pg"
+```
+
+Then run `bundle install`. Before the first publication, or to test unreleased changes, use `gem "connectors", git: "https://github.com/jackhelio/connectors.git", ref: "<reviewed-commit-sha>"` instead, replacing the ref with an actual reviewed commit. Local development can use `gem "connectors", path: "../connectors"`. See [release checks](docs/releasing.md).
+
+Mount the engine in `config/routes.rb`:
+
+```ruby
+Rails.application.routes.draw do
+  mount Connectors::Engine => "/connectors"
+end
+```
+
+Configure encryption before saving credentials:
+
+```sh
+bin/rails db:encryption:init
+bin/rails credentials:edit
+```
+
+Store the generated `active_record_encryption` entries in the target environment's Rails credentials, or configure the equivalent Rails settings from your secret store. Keep the keys stable across restarts and all application/worker instances; retain them when restoring encrypted data. See the [Rails encryption setup](https://guides.rubyonrails.org/active_record_encryption.html#setup).
+
+Configure the host identity boundary in `config/initializers/connectors.rb`:
+
+```ruby
+Connectors.configure do |config|
+  config.owner_class_name = "User" # an existing model with UUID IDs
+  config.host_base_url = ENV.fetch("APP_BASE_URL")
+  config.current_owner_resolver = lambda do |controller|
+    controller.request.env["connectors.current_owner"]
+  end
+end
+```
+
+Here, `connectors.current_owner` is a Rack environment entry that **your authenticated host middleware must populate** with the owner record. It is an integration example, not a built-in authentication mechanism. You can instead resolve through your existing trusted authentication middleware; for example, a Warden host can read `controller.request.env["warden"]&.user`. Never derive the trusted owner directly from a caller-supplied ID. Engine controllers inherit `ActionController::API`, so host `ApplicationController` methods and authentication callbacks are not inherited automatically.
+
+Run the host migrations:
+
+```sh
+bin/rails db:migrate
+```
+
+The engine appends its migration directory; copying migrations is unnecessary. Owners must exist before creating grants. If building a new owner table, use `create_table :users, id: :uuid`; an existing integer-ID table requires a host schema decision before integration.
+
+## First connection
+
+The installed gem ships these connector profiles:
+
+| Key | Connection |
+| --- | --- |
+| `resend` | Resend REST API, API key |
+| `gmail` | Gmail REST API, user OAuth2 |
+| `mcp` | Configurable remote MCP server |
+| `clickup` | ClickUp's official OAuth-only MCP server |
+
+Slack, GitHub and Echo under `test/dummy` are test fixtures, not shipped connectors. Inspect `GET /connectors/types` for the installed catalog and each connector's credential fields and actions.
+
+In a Rails console, create a Resend connection for an existing owner:
+
+```ruby
+owner = User.find(ENV.fetch("CONNECTOR_OWNER_ID"))
+grant = Connectors::Grant.create!(
+  owner: owner,
+  connector_key: "resend",
+  display_name: "Transactional email",
+  credentials: { "api_key" => ENV.fetch("RESEND_API_KEY") }
+)
+Connectors::CredentialTester.run(grant)
+```
+
+The connection test calls Resend's domains endpoint. It requires a key that can list domains; a sending-only key can still send email but will fail this read test.
+
+For an authenticated HTTP client, the equivalent creation request is:
+
+```http
+POST /connectors/credentials
+Content-Type: application/json
+
+{"type":"resend","name":"Transactional email","data":{"api_key":"YOUR_API_KEY"}}
+```
+
+Use the returned `id` for `GET /connectors/credentials/:id/actions` to discover actions. Calling an action executes a real provider operation:
+
+```http
+POST /connectors/credentials/:id/actions/send_email
+Content-Type: application/json
+
+{"data":{"from":"sender@your-verified-domain.example","to":"recipient@example.com","subject":"Hello","text":"Hello from Connectors"}}
+```
+
+The backend validates required action parameters, attaches credentials, calls the provider and returns `{ "status": "ok", "action": "send_email", "data": ... }` or a typed error. REST action validation checks required values and filters undeclared inputs; it is not general JSON Schema validation. Direct Ruby callers use `Connectors::ActionRunner.call(grant, :send_email, input)` and must select an authorized grant themselves; HTTP endpoints enforce sharing roles.
+
+For Gmail, configure `config.oauth_credentials = { gmail: { client_id: ..., client_secret: ... } }` from your secret store and register the callback shown by the connector catalog with Google. The default callback is `<APP_BASE_URL>/connectors/gmail/callback`. Start with `GET /connectors/gmail/authorize.json`, open `authorize_url`, and complete consent. Without `grant_id`, authorization creates a new connection; passing it explicitly reconnects an owned connection.
+
+For ClickUp, create `{"type":"clickup","name":"ClickUp workspace"}`, then use the shared MCP authorization and tool endpoints. [The MCP guide](MCP_CLIENT.md#clickup) covers consent, discovery, invocation and supported protocol features. Applications do not implement ClickUp's provider transport or authentication. REST actions and MCP tools currently have distinct API endpoints.
+
+## Operating the engine
+
+- Configure a durable Active Job backend and run its workers for webhook delivery. The gem supplies jobs, not a queue service.
+- Schedule polling with `Connectors::PollRunner.run(grant, instance_key: trigger_id)` for each independent consumer. The host supplies the stable key and handles downstream delivery.
+- Configure a shared `Rails.cache` if using connector quotas across workers. The dummy application's null cache is for tests.
+- Schedule `bundle exec rake connectors:mcp:cleanup` to remove expired authorization and interaction records. The engine does not start a scheduler.
+- Shared viewers can inspect metadata; editors can execute actions. Only the owner role can retrieve regular decrypted credential `data` with `include_data=true`. MCP returns only public configuration, even to owners.
+- Revoked grants are rejected before actions and HTTP attempts, including cached clients and retries. Already in-flight requests cannot be recalled. REST revocation requires a provider declaration; MCP disconnect is local and clears stored authentication.
+- Regular HTTP clients retry transient 502/503/504 responses twice for GET, HEAD, OPTIONS, PUT and DELETE. POST is excluded from those retries; token refresh may retry once after authentication failure. MCP tool calls are not automatically replayed on transport failure or HTTP 429.
+
+Host authentication, authorization of direct Ruby calls, encryption-key management, queue operations and provider permissions remain application responsibilities. [Architecture and contracts](docs/architecture.md) explains the boundaries and stored data.
+
+## Documentation
+
+- [Framework and DSL reference](CONNECTORS_FRAMEWORK.md)
+- [Architecture and execution flows](docs/architecture.md)
+- [Adding a connector with tests](docs/adding-connectors.md)
+- [Remote MCP and ClickUp](MCP_CLIENT.md)
+- [HTTP API contract](openapi.yaml) — paths are relative to the engine mount
+- [Development and contributing](CONTRIBUTING.md)
+- [Release requirements and verification](docs/releasing.md)
+- [Changelog and upgrade notes](CHANGELOG.md)
+
+## License
+
+[MIT](MIT-LICENSE). The vendored MCP schema has its [upstream license](lib/connectors/mcp/protocol/LICENSE) and [source attribution](lib/connectors/mcp/protocol/README.md) included in the gem.

data/app/connectors/clickup/connector.rb

@@ -0,0 +1,13 @@
+module Clickup
+  class Connector < Connectors::Connector
+    connector key: :clickup, auth: :api_key, base_url: nil, display_name: "ClickUp",
+      documentation_url: "https://developer.clickup.com/docs/connect-an-ai-assistant-to-clickups-mcp-server",
+      instructions: "Create the connection, then authorize your ClickUp account and select your Workspaces. ClickUp MCP requires OAuth; personal API tokens are not supported."
+
+    mcp server_url: "https://mcp.clickup.com/mcp", auth_mode: "oauth"
+
+    credentials do
+      field :client_information, type: "json", secret: true, display_name: "Pre-registered OAuth client (optional)"
+    end
+  end
+end

data/app/connectors/gmail/api.rb

@@ -0,0 +1,114 @@
+module Gmail
+  # Shared HTTP layer for every Gmail action. Mirrors n8n's
+  # `googleApiRequest` / `googleApiRequestAllItems` in
+  # `packages/nodes-base/nodes/Google/Gmail/GenericFunctions.ts` —
+  # one entry point that normalizes Google-specific errors into our
+  # `Connectors::ApiError` hierarchy with user-friendly messages,
+  # plus an auto-paginating variant for `*.list` endpoints.
+  module Api
+    module_function
+
+    # @param resource [String, Symbol] — "message" / "label" / "thread" / "draft".
+    #   Used to compose human-readable error messages ("Message not found",
+    #   "Label name already exists", "Invalid thread ID").
+    def request(client, method, path, body: nil, query: nil, resource: "resource")
+      response =
+        case method.to_sym
+        when :get, :delete
+          client.public_send(method, path, query)
+        when :post, :patch, :put
+          client.public_send(method, path, body || {}) do |req|
+            req.params.update(query) if query && !query.empty?
+          end
+        else
+          raise ArgumentError, "unsupported HTTP method: #{method.inspect}"
+        end
+
+      response.body
+    rescue Connectors::ApiError => e
+      raise translate(e, resource: resource)
+    end
+
+    # Walks `nextPageToken` until exhausted; concatenates the array at
+    # `property_name`. Matches n8n's signature so the porting is mechanical.
+    def request_all(client, property_name, method, path, body: nil, query: nil, resource: "resource", page_size: 100)
+      items = []
+      q     = (query || {}).dup
+      q[:maxResults] = page_size
+
+      loop do
+        page = request(client, method, path, body: body, query: q, resource: resource)
+        Array(page[property_name.to_s]).each { |it| items << it }
+        token = page["nextPageToken"]
+        break if token.to_s.empty?
+        q[:pageToken] = token
+      end
+
+      items
+    end
+
+    # n8n's `googleApiRequest` rescue ladder — translated to our types.
+    # When a translation matches, we raise a new ApiError with the
+    # user-meaningful message; otherwise the original passes through.
+    def translate(error, resource:)
+      status  = error.respond_to?(:status) ? error.status.to_i : 0
+      body    = error.respond_to?(:body) ? error.body : nil
+      message = error.message.to_s
+      details = google_error_details(body)
+      reason  = details[:message].to_s
+
+      case status
+      when 400
+        if reason.include?("Invalid id value")
+          raise Connectors::ApiError.new(
+            "Invalid #{resource} ID — Gmail IDs should look something like `182b676d244938bd`",
+            status: status, body: body
+          )
+        end
+      when 401
+        raise Connectors::AuthenticationFailed.new(reason.presence || message, status: status, body: body)
+      when 404
+        raise Connectors::ApiError.new(
+          "#{titlecase(resource)} not found",
+          status: status, body: body
+        )
+      when 409
+        # n8n parity: any 409 on the label resource is treated as a
+        # name collision — Gmail's API doesn't return 409 for any other
+        # reason on /users/me/labels.
+        if resource.to_s == "label"
+          raise Connectors::ApiError.new("Label name already exists", status: status, body: body)
+        end
+      when 429
+        raise Connectors::RateLimited.new(reason.presence || "Gmail rate-limit hit", status: status, body: body)
+      end
+
+      error
+    end
+
+    # ErrorNormalization supplies parsed JSON. Also accept raw strings from
+    # custom clients using the same translation helper.
+    def google_error_details(body)
+      hash =
+        case body
+        when Hash    then body
+        when String  then (JSON.parse(body) rescue {})
+        else              {}
+        end
+
+      err = hash["error"]
+      case err
+      when Hash
+        { message: err["message"], status: err["status"], errors: Array(err["errors"]) }
+      when String
+        { message: err }
+      else
+        {}
+      end
+    end
+
+    def titlecase(s)
+      s.to_s.tr("_", " ").split(" ").map(&:capitalize).join(" ")
+    end
+  end
+end