mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-06 10:48:12 +02:00
feat(connections): one-screen connector setup with stated defaults (#14811)
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - Agents use Connections (the Apps catalog) to act in services like
Notion, GitHub, Google Workspace and Railway
> - Each connector asked the user to answer setup questions before it
went to the provider. Most of the questions already had the correct
answer selected
> - ROADMAP.md lists "simpler setup" for Apps and Connections as ongoing
work. This change continues that work
> - This pull request removes the questions that Paperclip can answer
itself. It states the defaults in one line and moves the choices behind
"Change" and onto the Permissions tab
> - The benefit is that most connectors take one click in Paperclip and
then the provider's own consent screen
## Linked Issues or Issue Description
No public issue exists. This is the description, from the enhancement
template.
**What existing behavior does this improve?**
The setup flow for tool connectors in the Apps catalog.
**Subsystem affected**
Apps and Connections: `ui/src/features/connections`,
`ui/src/pages/apps`, the `packages/shared` app definitions, and the
OAuth routes in `server/src/routes/tool-access.ts`.
**Current behavior**
Every connector opened with an Access step. The step asked who can use
the connection and which agents get it, and both answers were already
selected. 18 connectors also asked "How do you want to connect?" when
Paperclip could rank the methods. The Google apps and Postman also asked
"What should Paperclip be able to do?" before sign-in. The four gateway
connectors (Zapier, Arcade, Composio, Executor) used a separate two-step
wizard. Asana was pinned to a customer-owned OAuth app, so the user had
to register an app in Asana's developer console. The "Set all" control
on the Permissions tab changed only one action. After the user approved
access, Railway's consent page showed "you can close this window" and
did not return to Paperclip.
**Proposed behavior**
One screen per connector, with one primary button. The screen states the
defaults in one sentence, for example "Connects for everyone in your
organization, available to all agents". A "Change" link opens one
Advanced panel. When the provider's metadata allows dynamic client
registration, Paperclip registers a client itself. Connecting lands on
the Permissions tab. On that tab, "Set all" changes every action in the
group.
**Reason and benefit**
The user makes fewer decisions before the connection exists. Most
choices are easier to make after the connection, on the Permissions tab,
where a change has an immediate effect.
**Breaking changes**
None. No schema or API change. Existing connections keep their settings.
## What Changed
- **No Access step.** `ConnectionSetupFlow` no longer has the Access
step. The flow shows the resolved default above the primary button and
on the completion screen. The access controls moved into one Advanced
panel. The panel opens automatically only when a setting in it is
required.
- **A default method for every app.** The flow always picks the ranked
default method. Alternate methods are in the Advanced panel. The Google
and Postman capability choice is not asked before sign-in. The
write-capable method is the default.
- **Gateway connectors.** `RemoteMcpProductionSetup` (Zapier, Arcade,
Composio, Executor) no longer has its own Access step. Its commit path
and the main commit path use one helper, `askFirstCatalogEntryIdsFor`,
for server-suggested defaults.
- **Dynamic registration from live metadata.**
`canRegisterOAuthClientDynamically` now allows registration when the
provider advertises a registration endpoint, even if the catalog entry
lists only customer-owned clients. The Asana and Linear definitions and
catalog text match live probes. Asana issues clients for loopback
callbacks only, so a hosted deployment still needs an Asana app.
- **Connection setup states.** New
`packages/shared/src/connection-setup-state.ts` sorts each method into
`instant`, `authorize`, `paste` or `register`. The gallery card verb
("Connect" or "Add key") comes from this resolver and the instance's
ownership availability.
- **Generic MCP.** The generic path no longer asks "Does it need a key?"
first. A credential challenge from the server shows the key field.
- **Permissions tab.** Each action row shows its risk level. Each group
has a "Set all" control. The control sends one change for the whole
group. Before, each row's save started from the same render, so the
saves overwrote each other. The Zapier/Arcade/Composio/Executor setup
screen had the same defect.
- **OAuth callback interstitial.** A cross-site browser navigation to
`/api/tools/oauth/callback` gets a small same-origin "Finishing your
connection…" page. That page repeats the request, and the repeat does
the code exchange. Railway's consent page replaces itself after about
two seconds, and the code exchange plus tool discovery takes longer than
that. The interstitial uses only a meta refresh, because the OAuth code
is single-use. Requests without `Sec-Fetch-Site: cross-site` take the
old path.
- **Linear registers through its MCP server.** Linear pins the console
endpoints at `linear.app`. Pinned endpoints now replace discovery only
when the method cannot register, or when the connection has an
operator-entered client. So a Linear connection now finds the
registration endpoint at `mcp.linear.app`.
- **Own-OAuth-app recovery stays on the one-click screen.** When the
method also accepts a customer-owned client, the client fields are in
the Advanced panel. The panel opens after a failed sign-in. "Try again"
resumes the draft with the operator's client.
- **E2E specs** follow the one-screen flow. The Access-step clicks are
removed, the specs open **Change** before they pick agents, and they
expect GitHub's **Add key** verb.
- **Default permissions do not change.** New connections still allow
every action. The user can set actions to Ask first or Off on the
Permissions tab.
## Verification
- `cd ui && npx vitest run src/pages/apps src/features/connections
--no-file-parallelism`
- `cd packages/shared && npx vitest run src/app-definitions.test.ts
src/connection-setup-state.test.ts`
- `cd server && npx vitest run src/__tests__/tool-access-service.test.ts
src/__tests__/remote-mcp-connectors.test.ts`
- `pnpm check:token-gates`
- New tests:
- `PermissionsPanel.group.test.tsx` checks that "Set all" sends one
change for the whole group. It fails on the old code.
- `action-permissions.test.ts` checks the group update.
- `connection-setup-state.test.ts` checks the four setup states.
- A server test checks that a cross-site callback gets the interstitial
and does not use the OAuth state, and that the same-origin repeat
completes the connection.
- Manual check on a hosted staging deployment. GitHub, Google Drive,
Composio, Notion, PostHog and Railway each connected from one screen and
returned to the Permissions tab. On Railway, "Set all" changed all 65
write actions, and the change remained after a reload.
- Visual changes: snapshot baselines are intentionally not updated. See
the `doc/design/DECISION-SHEET.md` entry "Per-change snapshot
verification demoted to dormant (Jul 13 2026)".
## Risks
- **Fewer confirmation clicks.** Organization-wide access is the
default, and the user does not confirm it on a separate step. This was
already the preselected answer. The flow shows the default before the
user clicks and again after the connection.
- **Google write scope.** Google apps now request the write-capable
scope by default. A narrower scope needs a new sign-in.
- **Dynamic registration from live metadata.** A provider can advertise
registration and then reject a redirect URI. Asana rejects hosted
callbacks, for example. In that case registration fails, and the
customer-owned client path remains available for recovery.
- **Callback interstitial.** The OAuth callback adds one same-origin
step for cross-site browser navigations. Browsers without `Sec-Fetch-*`
headers use the old direct path.
- Chat and bot connectors (Discord, Telegram, Microsoft Teams, iMessage)
do not change.
> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.
## Model Used
- Claude Opus 5.5 (Anthropic), model ID `claude-opus-5-5`, used through
Claude Code with tool use (shell, file editing, browser automation) and
extended thinking. It wrote the code, the tests and this description. A
human product owner directed the work and tested it by hand.
## Checklist
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: scotttong <squadbot000@gmail.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
39 files changed
+1550
-543
No files matched your search
@@ -262,7 +262,7 @@ describe("AppDefinition catalog", () => {
|
||||
"google-workspace-search",
|
||||
]),
|
||||
);
|
||||
expect(SELF_SERVE_MCP_CANDIDATES).toHaveLength(48);
|
||||
expect(SELF_SERVE_MCP_CANDIDATES).toHaveLength(49);
|
||||
expect(BLOCKED_MCP_PROVIDERS.map((entry) => entry.slug)).toEqual([
|
||||
"g2",
|
||||
"vercel",
|
||||
@@ -426,15 +426,15 @@ describe("AppDefinition catalog", () => {
|
||||
expect(channel("slack")?.guidanceMd).toContain("reactions");
|
||||
expect(channel("slack")?.guidanceMd).toContain("direct messages");
|
||||
});
|
||||
it("keeps a complete, unique, dated evidence ledger for all 51 researched MCP providers", () => {
|
||||
it("keeps a complete, unique, dated evidence ledger for all 52 researched MCP providers", () => {
|
||||
// Ledger-wide date reflects the last full re-verification (2026-08-26);
|
||||
// later provider additions carry their own research evidence, but
|
||||
// bumping the shared date would overstate freshness for the other providers.
|
||||
expect(SELF_SERVE_MCP_RESEARCH.verifiedAt).toBe("2026-08-26");
|
||||
expect(SELF_SERVE_MCP_RESEARCH.entries).toHaveLength(51);
|
||||
expect(SELF_SERVE_MCP_RESEARCH.entries).toHaveLength(52);
|
||||
expect(
|
||||
new Set(SELF_SERVE_MCP_RESEARCH.entries.map((entry) => entry.slug)),
|
||||
).toHaveProperty("size", 51);
|
||||
).toHaveProperty("size", 52);
|
||||
for (const entry of SELF_SERVE_MCP_RESEARCH.entries) {
|
||||
expect(new URL(entry.docsUrl).protocol).toBe("https:");
|
||||
expect(new URL(entry.serverUrl).protocol).toBe("https:");
|
||||
@@ -572,7 +572,11 @@ describe("AppDefinition catalog", () => {
|
||||
(field) => field.key === "readOnly",
|
||||
)?.defaultValue,
|
||||
).toBe(false);
|
||||
expect(method("asana")?.ownershipModes).toEqual(["customer"]);
|
||||
// Asana and Linear both advertise dynamic client registration and issue
|
||||
// clients on request (verified live 2026-09-28), so neither needs an
|
||||
// operator-registered OAuth app. "customer" stays as the manual fallback.
|
||||
expect(method("asana")?.ownershipModes).toEqual(["dcr", "customer"]);
|
||||
expect(method("linear")?.ownershipModes).toEqual(["dcr", "customer"]);
|
||||
expect(method("zapier")).toMatchObject({
|
||||
key: "generated-url",
|
||||
auth: "none",
|
||||
@@ -617,7 +621,7 @@ describe("AppDefinition catalog", () => {
|
||||
APP_DEFINITIONS.find((app) => app.slug === "hugging-face")?.methods[0]
|
||||
?.defaults?.scopesHint,
|
||||
).toEqual(["read-mcp", "read-repos", "contribute-repos", "jobs"]));
|
||||
it("defaults every new connection action to allowed", () => {
|
||||
it("defaults every action, reads and writes, to allowed", () => {
|
||||
for (const app of APP_DEFINITIONS)
|
||||
for (const method of app.methods)
|
||||
expect(recommendedDefaultsForApp(app, method.key)).toEqual({
|
||||
|
||||
@@ -255,10 +255,12 @@ export function resolveConnectionMethodServerUrl(
|
||||
|
||||
export function recommendedDefaultsForApp(app: AppDefinition, methodKey?: string | null): Record<string, unknown> {
|
||||
// Keep the parameters in the public contract: callers resolve defaults for a
|
||||
// concrete app/method even though the initial policy is now uniform. This is
|
||||
// concrete app/method even though the initial policy is uniform. This is
|
||||
// an open default, not an approval bypass: connection finalization remains a
|
||||
// configure-authorized, audited operation, and Ask first stays available as
|
||||
// an operator-selected policy for any action after the connection is made.
|
||||
// The connect flow lands on the Permissions tab so that choice is the very
|
||||
// next screen (PAP-659: agents get full permissions unless someone narrows them).
|
||||
void app;
|
||||
void methodKey;
|
||||
return {
|
||||
|
||||
@@ -21,25 +21,23 @@
|
||||
"transport": "mcp_remote",
|
||||
"auth": "oauth",
|
||||
"ownershipModes": [
|
||||
"dcr",
|
||||
"customer"
|
||||
],
|
||||
"whenToUse": "Register an OAuth app with Asana, then enter its client ID and secret.",
|
||||
"whenToUse": "Sign in with Asana. Paperclip registers its own OAuth client automatically.",
|
||||
"defaults": {
|
||||
"serverUrl": "https://mcp.asana.com/v2/mcp",
|
||||
"scopesHint": [
|
||||
"default"
|
||||
]
|
||||
},
|
||||
"guidanceMd": "Connect Asana in the browser. Create an Asana MCP OAuth app and register Paperclip's callback URI; DCR is not supported.",
|
||||
"guidanceMd": "Connect Asana in the browser. Paperclip registers its own OAuth client with Asana's MCP server, so a local Paperclip needs no developer-console setup. Asana only accepts localhost callbacks, so a hosted deployment falls back to entering your own OAuth app.",
|
||||
"riskTier": "S3",
|
||||
"label": "Use your own OAuth app",
|
||||
"label": "Sign in with Asana",
|
||||
"consoleLinks": {
|
||||
"register": "https://developers.asana.com/docs/integrating-with-asanas-mcp-server",
|
||||
"docs": "https://developers.asana.com/docs/integrating-with-asanas-mcp-server"
|
||||
},
|
||||
"warnings": [
|
||||
"Create an Asana MCP OAuth app and register Paperclip's callback URI; DCR is not supported."
|
||||
]
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -20,6 +20,7 @@
|
||||
"transport": "mcp_remote",
|
||||
"auth": "oauth",
|
||||
"ownershipModes": [
|
||||
"dcr",
|
||||
"customer"
|
||||
],
|
||||
"whenToUse": "Use the provider-hosted connection for the quickest setup.",
|
||||
@@ -32,7 +33,7 @@
|
||||
"write"
|
||||
]
|
||||
},
|
||||
"guidanceMd": "Register a Linear OAuth app and add Paperclip's redirect URI before connecting.",
|
||||
"guidanceMd": "Connect Linear for issues and projects. Paperclip registers its own OAuth client with Linear's MCP server, so no developer-console setup is needed.",
|
||||
"riskTier": "S2",
|
||||
"requiredResourceFilters": [
|
||||
"workspace",
|
||||
|
||||
@@ -0,0 +1,111 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
import {
|
||||
CONNECTABLE_APP_DEFINITIONS,
|
||||
getAvailableConnectionMethods,
|
||||
getConnectableAppDefinition,
|
||||
} from "./app-definitions.js";
|
||||
import {
|
||||
connectionSetupStateForApp,
|
||||
connectionSetupVerbForApp,
|
||||
type ConnectionSetupState,
|
||||
} from "./connection-setup-state.js";
|
||||
|
||||
/**
|
||||
* These assert against the shipped catalog rather than fixtures, because the
|
||||
* claim being protected is about real connectors: the gallery card's verb has
|
||||
* to match what the connect screen then asks for.
|
||||
*/
|
||||
describe("connectionSetupStateForApp", () => {
|
||||
it("puts one-click OAuth connectors in the authorize state", () => {
|
||||
for (const slug of ["notion", "linear", "sentry", "stripe", "jira", "asana"]) {
|
||||
expect(connectionSetupStateForApp(getConnectableAppDefinition(slug)), slug).toBe("authorize");
|
||||
}
|
||||
});
|
||||
|
||||
it("follows the instance's ownership availability rather than the catalog order", () => {
|
||||
// Google and GitHub publish a Paperclip-managed method, but it is
|
||||
// `platform_shared` and therefore unavailable until an operator configures
|
||||
// the cloud connector. The state has to reflect what this instance can
|
||||
// actually do, or the card promises one click and the screen shows a form.
|
||||
const gmail = getConnectableAppDefinition("gmail")!;
|
||||
expect(connectionSetupStateForApp(gmail)).toBe("register");
|
||||
expect(
|
||||
connectionSetupStateForApp({
|
||||
...gmail,
|
||||
ownershipAvailability: { ...gmail.ownershipAvailability, platform_shared: true },
|
||||
}),
|
||||
).toBe("authorize");
|
||||
});
|
||||
|
||||
it("reserves register for providers that genuinely cannot issue a client", () => {
|
||||
for (const slug of ["box", "xero"]) {
|
||||
expect(connectionSetupStateForApp(getConnectableAppDefinition(slug)), slug).toBe("register");
|
||||
}
|
||||
});
|
||||
|
||||
it("treats an API key as a paste, and says so on the card", () => {
|
||||
for (const slug of ["honcho", "mem0", "openrouter"]) {
|
||||
expect(connectionSetupStateForApp(getConnectableAppDefinition(slug)), slug).toBe("paste");
|
||||
expect(connectionSetupVerbForApp(getConnectableAppDefinition(slug)), slug).toBe("Add key");
|
||||
}
|
||||
});
|
||||
|
||||
it("reaches instant only when the catalog already knows the endpoint", () => {
|
||||
// Composio and Context7 ship a fixed server URL and ask for nothing.
|
||||
expect(connectionSetupStateForApp(getConnectableAppDefinition("composio"))).toBe("instant");
|
||||
expect(connectionSetupStateForApp(getConnectableAppDefinition("context7"))).toBe("instant");
|
||||
});
|
||||
|
||||
it("does not promise instant for a provider-generated URL", () => {
|
||||
// Zapier, Arcade and Executor declare no server URL: the operator brings
|
||||
// one. Calling these instant is the mistake this helper exists to prevent.
|
||||
for (const slug of ["zapier", "arcade", "executor"]) {
|
||||
expect(connectionSetupStateForApp(getConnectableAppDefinition(slug)), slug).toBe("paste");
|
||||
}
|
||||
});
|
||||
|
||||
it("does not promise instant for a templated endpoint", () => {
|
||||
// Shopify's URL has a {storeDomain} placeholder the operator fills in.
|
||||
expect(connectionSetupStateForApp(getConnectableAppDefinition("shopify"))).toBe("paste");
|
||||
});
|
||||
|
||||
it("defaults the AI providers to their subscription sign-in", () => {
|
||||
for (const slug of ["anthropic", "openai", "xai"]) {
|
||||
expect(connectionSetupStateForApp(getConnectableAppDefinition(slug)), slug).toBe("authorize");
|
||||
expect(connectionSetupVerbForApp(getConnectableAppDefinition(slug)), slug).toBe("Connect");
|
||||
}
|
||||
});
|
||||
|
||||
it("never says Add key for something that does not want a secret", () => {
|
||||
for (const app of CONNECTABLE_APP_DEFINITIONS) {
|
||||
if (connectionSetupVerbForApp(app) !== "Add key") continue;
|
||||
const wantsSecret = getAvailableConnectionMethods(app)
|
||||
.filter((method) => (method.purpose ?? "tool") !== "channel")
|
||||
.some((method) => (method.credentialFields?.length ?? 0) > 0);
|
||||
expect(wantsSecret, app.slug).toBe(true);
|
||||
}
|
||||
});
|
||||
|
||||
it("resolves a state for every connectable tool connector", () => {
|
||||
const states = new Map<string, ConnectionSetupState | null>();
|
||||
for (const app of CONNECTABLE_APP_DEFINITIONS) {
|
||||
const hasToolMethod = app.methods.some((method) => (method.purpose ?? "tool") !== "channel");
|
||||
if (!hasToolMethod) continue;
|
||||
states.set(app.slug, connectionSetupStateForApp(app));
|
||||
}
|
||||
expect([...states].filter(([, state]) => state === null)).toEqual([]);
|
||||
});
|
||||
|
||||
it("returns null rather than guessing for an unknown app", () => {
|
||||
expect(connectionSetupStateForApp(null)).toBeNull();
|
||||
});
|
||||
|
||||
it("survives a gallery row that carries no method list", () => {
|
||||
// Rows are assembled from the gallery, live connections and custom
|
||||
// endpoints, so a row can reach a card without methods. Throwing here would
|
||||
// take the whole connectors page down with it.
|
||||
const partial = { slug: "mystery", name: "Mystery" } as never;
|
||||
expect(connectionSetupStateForApp(partial)).toBeNull();
|
||||
expect(connectionSetupVerbForApp(partial)).toBe("Connect");
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,112 @@
|
||||
import {
|
||||
connectionMethodAcceptsCustomerOAuthClient,
|
||||
connectionMethodRequiresConfiguration,
|
||||
connectionMethodSupportsAutomaticOAuth,
|
||||
getAvailableConnectionMethods,
|
||||
getRecommendedConnectionMethod,
|
||||
} from "./app-definitions.js";
|
||||
import type { AppDefinition, ConnectionMethodDef } from "./types/app-definition.js";
|
||||
|
||||
/**
|
||||
* The four states every connect screen lands in (PAP-659, "one shell, four
|
||||
* states").
|
||||
*
|
||||
* The point of naming them here rather than in the wizard is that two surfaces
|
||||
* have to agree: the gallery card decides its verb from the state, and the
|
||||
* connect screen decides its body from the same state. When each re-derived it
|
||||
* from raw method flags they drifted — a card offering "Connect" for something
|
||||
* that then demanded a pasted URL is exactly the inconsistency the ticket is
|
||||
* about.
|
||||
*
|
||||
* - `instant` nothing to supply: connect resolves entirely from the catalog.
|
||||
* - `authorize` one click, then the provider's own consent screen.
|
||||
* - `paste` one thing the operator has to bring: a key, a URL, a tenant.
|
||||
* - `register` the provider cannot issue a client, so one must be registered
|
||||
* in its console first. A recovery state, never a normal step.
|
||||
*/
|
||||
export type ConnectionSetupState = "instant" | "authorize" | "paste" | "register";
|
||||
|
||||
/**
|
||||
* True when the catalog already knows the endpoint. A `serverUrlTemplate` does
|
||||
* not count: its placeholders are the operator's to fill, which is a paste.
|
||||
*/
|
||||
function hasResolvedEndpoint(method: ConnectionMethodDef): boolean {
|
||||
if (method.transport !== "mcp_remote") return true;
|
||||
if (method.defaults?.serverUrlTemplate) return false;
|
||||
return Boolean(method.defaults?.serverUrl);
|
||||
}
|
||||
|
||||
export function connectionSetupStateForMethod(
|
||||
method: ConnectionMethodDef | null | undefined,
|
||||
): ConnectionSetupState | null {
|
||||
if (!method) return null;
|
||||
if (method.auth === "oauth") {
|
||||
// An AI subscription signs in through the adapter's own device/OAuth flow.
|
||||
// No client is ever registered, so `register` would be a false detour.
|
||||
if (method.transport === "runtime_auth") return "authorize";
|
||||
if (connectionMethodSupportsAutomaticOAuth(method)) return "authorize";
|
||||
// A customer-owned client is only a *register* state when the provider
|
||||
// offers nothing better. Live discovery can still overrule the catalog at
|
||||
// connect time, which is why the flow re-resolves rather than trusting this.
|
||||
if (connectionMethodAcceptsCustomerOAuthClient(method)) return "register";
|
||||
return "authorize";
|
||||
}
|
||||
if (method.auth === "none") {
|
||||
return connectionMethodRequiresConfiguration(method) || !hasResolvedEndpoint(method)
|
||||
? "paste"
|
||||
: "instant";
|
||||
}
|
||||
return "paste";
|
||||
}
|
||||
|
||||
/**
|
||||
* The default tool method for an app, or null.
|
||||
*
|
||||
* Gallery rows are not guaranteed to carry a method list: the display entry is
|
||||
* assembled from several sources, and a row can stand for a connection whose
|
||||
* catalog entry has since been withdrawn. Resolving that to null — rather than
|
||||
* throwing inside a card render — is the difference between a missing verb and
|
||||
* a blank connectors page.
|
||||
*/
|
||||
function defaultToolMethod(
|
||||
app: AppDefinition | null | undefined,
|
||||
methodKey?: string | null,
|
||||
): ConnectionMethodDef | null {
|
||||
if (!app || !Array.isArray(app.methods)) return null;
|
||||
const methods = getAvailableConnectionMethods(app).filter(
|
||||
(method) => (method.purpose ?? "tool") !== "channel",
|
||||
);
|
||||
return methodKey
|
||||
? methods.find((candidate) => candidate.key === methodKey) ?? null
|
||||
: getRecommendedConnectionMethod(methods);
|
||||
}
|
||||
|
||||
export function connectionSetupStateForApp(
|
||||
app: AppDefinition | null | undefined,
|
||||
methodKey?: string | null,
|
||||
): ConnectionSetupState | null {
|
||||
return connectionSetupStateForMethod(defaultToolMethod(app, methodKey));
|
||||
}
|
||||
|
||||
/**
|
||||
* The gallery card's verb (PAP-659 C4).
|
||||
*
|
||||
* Only a method that genuinely wants a secret says so. "Add key" on a connector
|
||||
* that actually wants a pasted URL would be worse than the generic verb, so a
|
||||
* paste state without credential fields keeps "Connect" — the operator still
|
||||
* lands on one screen with one field, which the verb does not need to restate.
|
||||
*/
|
||||
export function connectionSetupVerbForMethod(
|
||||
method: ConnectionMethodDef | null | undefined,
|
||||
): "Connect" | "Add key" {
|
||||
if (!method) return "Connect";
|
||||
const wantsSecret = (method.credentialFields?.length ?? 0) > 0;
|
||||
return connectionSetupStateForMethod(method) === "paste" && wantsSecret ? "Add key" : "Connect";
|
||||
}
|
||||
|
||||
export function connectionSetupVerbForApp(
|
||||
app: AppDefinition | null | undefined,
|
||||
methodKey?: string | null,
|
||||
): "Connect" | "Add key" {
|
||||
return connectionSetupVerbForMethod(defaultToolMethod(app, methodKey));
|
||||
}
|
||||
@@ -333,6 +333,13 @@ export {
|
||||
recommendedDefaultsForApp,
|
||||
resolveConnectionMethodServerUrl,
|
||||
} from "./app-definitions.js";
|
||||
export {
|
||||
connectionSetupStateForApp,
|
||||
connectionSetupStateForMethod,
|
||||
connectionSetupVerbForApp,
|
||||
connectionSetupVerbForMethod,
|
||||
type ConnectionSetupState,
|
||||
} from "./connection-setup-state.js";
|
||||
export { APP_DEFINITIONS } from "./app-definitions.generated.js";
|
||||
export * from "./google-workspace-connectors.js";
|
||||
export * from "./github-connectors.js";
|
||||
|
||||
@@ -40,7 +40,8 @@
|
||||
{ "slug": "supabase", "name": "Supabase", "wave": 2, "status": "self_serve", "docsUrl": "https://supabase.com/docs/guides/ai-tools/mcp", "serverUrl": "https://mcp.supabase.com/mcp", "authMode": "dcr_or_api_key", "prerequisite": "A Supabase account; use a development project and review write actions before connecting production data.", "riskTier": "S4" },
|
||||
{ "slug": "ticket-tailor", "name": "Ticket Tailor", "wave": 2, "status": "self_serve", "docsUrl": "https://developers.tickettailor.com/docs/mcp/authentication/", "serverUrl": "https://mcp.tickettailor.ai/mcp", "authMode": "dcr", "prerequisite": "A Ticket Tailor account; the provider may request an API key during its hosted authorization prompt.", "riskTier": "S3" },
|
||||
|
||||
{ "slug": "asana", "name": "Asana", "wave": 3, "status": "self_serve", "docsUrl": "https://developers.asana.com/docs/integrating-with-asanas-mcp-server", "serverUrl": "https://mcp.asana.com/v2/mcp", "authMode": "customer_oauth", "prerequisite": "Create an Asana MCP OAuth app and register Paperclip's callback URI; DCR is not supported.", "riskTier": "S3" },
|
||||
{ "slug": "asana", "name": "Asana", "wave": 3, "status": "self_serve", "docsUrl": "https://developers.asana.com/docs/integrating-with-asanas-mcp-server", "serverUrl": "https://mcp.asana.com/v2/mcp", "authMode": "dcr", "prerequisite": "An active Asana account. Re-verified 2026-09-28: mcp.asana.com advertises a registration endpoint and issues clients for http://localhost callbacks, so a local Paperclip registers its own OAuth client. Asana refuses non-localhost redirect URIs, so a hosted deployment still registers an app in Asana's developer console.", "riskTier": "S3" },
|
||||
{ "slug": "linear", "name": "Linear", "wave": 3, "status": "self_serve", "docsUrl": "https://linear.app/docs/mcp", "serverUrl": "https://mcp.linear.app/mcp", "authMode": "dcr_cimd", "prerequisite": "An active Linear workspace. Verified 2026-09-28: mcp.linear.app advertises a registration endpoint and client-ID metadata documents, so Paperclip registers its own OAuth client.", "riskTier": "S2" },
|
||||
{ "slug": "box", "name": "Box", "wave": 3, "status": "self_serve", "docsUrl": "https://support.box.com/hc/en-us/articles/43847256139923-Managing-Box-MCP-Servers", "serverUrl": "https://mcp.box.com", "authMode": "customer_oauth", "prerequisite": "A Box administrator creates the OAuth integration and enables AI access.", "riskTier": "S3" },
|
||||
{ "slug": "mem0", "name": "Mem0", "wave": 3, "status": "self_serve", "docsUrl": "https://docs.mem0.ai/platform/mem0-mcp", "serverUrl": "https://mcp.mem0.ai/mcp/", "authMode": "api_key", "prerequisite": "A Mem0 API key; the live server currently requires the slash-normalized endpoint.", "riskTier": "S3" },
|
||||
{ "slug": "pagerduty", "name": "PagerDuty", "wave": 3, "status": "self_serve", "docsUrl": "https://support.pagerduty.com/main/docs/pagerduty-mcp-server", "serverUrl": "https://mcp.pagerduty.com/mcp", "authMode": "api_key", "prerequisite": "A PagerDuty API token; choose the regional endpoint that hosts the account.", "riskTier": "S4" },
|
||||
|
||||
Reference in new issue
Block a user