The Open Framework for Building Agents
feat(docs) simplify integration connection setup generation (#2849)
vercel-gh-bot-4[bot]538722eac28e
diff --git a/apps/docs/lib/integrations/connection-setup.test.ts b/apps/docs/lib/integrations/connection-setup.test.tsindex c0ab28a1a..1f897bae9 100644--- a/apps/docs/lib/integrations/connection-setup.test.ts+++ b/apps/docs/lib/integrations/connection-setup.test.ts@@ -1,9 +1,9 @@import { describe, expect, it } from "vitest";import {- buildConnectionConfigure,buildConnectionInstall,buildConnectionSetup,+ renderConnectionVariants,} from "./connection-setup";import { getIntegration } from "./data";@@ -16,7 +16,9 @@ describe("Browser Use connection setup", () => {expect(quickStart).toContain('"x-browser-use-api-key": process.env.BROWSER_USE_API_KEY!');expect(quickStart).not.toContain("@vercel/connect");expect(buildConnectionInstall(integration)).toContain("eve add connection/browser-use");- expect(buildConnectionConfigure(integration)).toContain("BROWSER_USE_API_KEY=your_api_key");+ expect(renderConnectionVariants(setup, setup.configureVariants)).toContain(+ "BROWSER_USE_API_KEY=your_api_key",+ );});it("keeps Connect setup for OAuth connections", () => {@@ -42,6 +44,18 @@ describe("Agentcard connection setup", () => {});});+describe("Context connection setup", () => {+ it("keeps the connector UID separate from its creation arguments", () => {+ const integration = getIntegration("context")!;+ const setup = buildConnectionSetup(integration);++ expect(setup.variants["mcp:user"]).toContain('auth: connect("context")');+ expect(setup.configureVariants["mcp:user"]).toContain(+ "vercel connect create mcp.context.dev --name context",+ );+ });+});+describe("Neon connection setup", () => {it("generates the registry install and Vercel Connect configuration", () => {const integration = getIntegration("neon")!;@@ -113,7 +127,7 @@ describe("Vercel MCP connection setup", () => {expect(appConfigure).toContain("copy the returned connector UID into the App example");expect(appConfigure).toContain("token still belongs to the user who created it");- const configure = buildConnectionConfigure(integration);+ const configure = renderConnectionVariants(setup, setup.configureVariants);expect(configure).toContain("### MCP · User");expect(configure).toContain("### MCP · App");expect(configure).not.toContain("vercel connect attach");diff --git a/apps/docs/lib/integrations/connection-setup.ts b/apps/docs/lib/integrations/connection-setup.tsindex 1bb0d28e0..948077220 100644--- a/apps/docs/lib/integrations/connection-setup.ts+++ b/apps/docs/lib/integrations/connection-setup.ts@@ -23,8 +23,8 @@ export interface ConnectionSetup {export const setupKey = (protocol: ConnectionProtocol, auth: AuthMode): string =>`${protocol}:${auth}`;-const connectorOf = (slug: string, spec: ConnectionSpec, auth?: AuthMode): string =>- (auth === undefined ? undefined : spec.connectors?.[auth]) ?? spec.connector ?? slug;+const connectorOf = (slug: string, spec: ConnectionSpec, auth: AuthMode): string =>+ (auth === "apiKey" ? undefined : spec.connectors?.[auth]?.uid) ?? slug;/** The TypeScript connection file for one (protocol, auth) combination. */const buildSnippet = (@@ -138,11 +138,8 @@ const buildConfigureVariant = (integration: Integration, auth: AuthMode): stringif (auth !== "apiKey") {const connector = connectorOf(integration.slug, spec, auth);- const modeService = spec.connectorServices?.[auth];- const connectorService = modeService ?? spec.connectorService ?? connector;- const namedConnector =- !spec.defaultConnectorName &&- (modeService !== undefined || spec.connectorService !== undefined);+ const connectorSpec = spec.connectors?.[auth];+ const connectorService = connectorSpec?.service ?? connector;sections.push(["Link your project, create the connector, and pull OIDC locally:",@@ -150,7 +147,7 @@ const buildConfigureVariant = (integration: Integration, auth: AuthMode): string"```bash","vercel link",`vercel connect create ${connectorService}${- namedConnector ? ` --name ${integration.slug}` : ""+ connectorSpec?.name ? ` --name ${connectorSpec.name}` : ""}`,"vercel env pull","```",@@ -221,18 +218,16 @@ export const buildConnectionInstall = (integration: Integration): string => {].join("\n");};-/** Generated Configure markdown for a connection. */-export const buildConnectionConfigure = (integration: Integration): string => {- const setup = buildConnectionSetup(integration);- return setup.protocols+/** Render every protocol and auth variant as agent-readable markdown. */+export const renderConnectionVariants = (+ setup: ConnectionSetup,+ variants: Record<string, string>,+): string =>+ setup.protocols.flatMap((protocol) =>setup.authModes.map((auth) => {- const content = setup.configureVariants[setupKey(protocol, auth)] ?? "";+ const content = variants[setupKey(protocol, auth)] ?? "";return `### ${protocolLabel[protocol]} · ${authModeLabel[auth]}\n\n${content}`;}),).join("\n\n");-};--/** Human label for an auth-mode switcher button. */-export const authModeButtonLabel = (auth: AuthMode): string => authModeLabel[auth];diff --git a/apps/docs/lib/integrations/data.ts b/apps/docs/lib/integrations/data.tsindex 58c601aab..fb1a53843 100644--- a/apps/docs/lib/integrations/data.ts+++ b/apps/docs/lib/integrations/data.ts@@ -38,35 +38,39 @@ export interface ApiKeySpec {header: string;}+interface ConnectorSpec {+ /** Vercel Connect connector UID; defaults to the integration slug. */+ uid?: string;+ /** Service passed to `vercel connect create`; defaults to the connector UID. */+ service?: string;+ /** Optional `--name` value passed to `vercel connect create`. */+ name?: string;+}++interface ConnectionSetupSpec {+ /** Supported auth modes in display order; the first is the default. */+ authModes: AuthMode[];+ /** API-key wiring when `authModes` includes `apiKey`. */+ apiKey?: ApiKeySpec;+ /** Auth-mode-specific connector references and creation arguments. */+ connectors?: Partial<Record<Exclude<AuthMode, "apiKey">, ConnectorSpec>>;+ /** Optional provider-specific configure guidance, rendered as markdown. */+ configureNote?: string;+ /** Auth-mode-specific configure guidance, rendered as markdown. */+ configureNotes?: Partial<Record<AuthMode, string>>;+}+/*** Structured description of a connection consumed by the detail page to* generate Install, Quick start, and Configure content. Transport (`mcp`,* `openapi`) and `description` are filled from the shared catalog identity;* Auth modes, connectors, and configure notes are the docs-only overlay.*/-export interface ConnectionSpec {- /** Vercel Connect connector UID; defaults to the integration slug. */- connector?: string;- /** Auth-mode-specific connector UIDs when one service needs separate connectors. */- connectors?: Partial<Record<AuthMode, string>>;- /** Service passed to `vercel connect create` when it differs from the connector UID. */- connectorService?: string;- /** Auth-mode-specific services passed to `vercel connect create`. */- connectorServices?: Partial<Record<AuthMode, string>>;- /** Whether `vercel connect create` should use the service's default name. */- defaultConnectorName?: boolean;- /** Supported auth modes in display order; the first is the default. */- authModes: AuthMode[];- /** API-key wiring when `authModes` includes `apiKey`. */- apiKey?: ApiKeySpec;+export interface ConnectionSpec extends ConnectionSetupSpec {/** Model-facing description; defaults to the integration tagline. */description?: string;mcp?: ConnectionIdentity["mcp"];openapi?: ConnectionIdentity["openapi"];- /** Optional provider-specific configure guidance, rendered as markdown. */- configureNote?: string;- /** Auth-mode-specific configure guidance, rendered as markdown. */- configureNotes?: Partial<Record<AuthMode, string>>;}export interface Integration {@@ -124,18 +128,9 @@ type ExtensionPresentation = PackagePresentation;type MemoryPresentation = PackagePresentation;/** Connection overlay: presentation plus Connect auth/config details. */-interface ConnectionPresentation extends Presentation {- authModes: AuthMode[];+interface ConnectionPresentation extends Omit<Presentation, "badge">, ConnectionSetupSpec {quickStart?: string;configure?: string;- apiKey?: ApiKeySpec;- connector?: string;- connectors?: Partial<Record<AuthMode, string>>;- connectorService?: string;- connectorServices?: Partial<Record<AuthMode, string>>;- defaultConnectorName?: boolean;- configureNote?: string;- configureNotes?: Partial<Record<AuthMode, string>>;}const channelPresentations: Record<string, ChannelPresentation> = {@@ -1769,10 +1764,10 @@ const connectionPresentations: Record<string, ConnectionPresentation> = {docsHref: "https://vercel.com/docs/agent-resources/vercel-mcp",keywords: ["mcp", "projects", "deployments", "logs", "oauth", "connect"],authModes: ["user", "app"],- connector: "vercel",- connectors: { app: "vercel/your-connector" },- connectorService: "vercel",- connectorServices: { app: "api-key" },+ connectors: {+ user: { name: "vercel" },+ app: { uid: "vercel/your-connector", service: "api-key", name: "vercel" },+ },configureNotes: {user: "Select None when prompted for a token authentication method. Each user completes OAuth when needed.",app: "Enter a team-scoped [Vercel token](https://vercel.com/kb/guide/how-do-i-use-a-vercel-api-access-token) when prompted, then copy the returned connector UID into the App example. This avoids per-user OAuth, though the Vercel token still belongs to the user who created it.",@@ -1851,7 +1846,7 @@ const connectionPresentations: Record<string, ConnectionPresentation> = {context: {logo: "context",docsHref: "https://docs.context.dev/install-mcp",- connectorService: "mcp.context.dev",+ connectors: { user: { service: "mcp.context.dev", name: "context" } },keywords: ["mcp","web search",@@ -1934,9 +1929,7 @@ const connectionPresentations: Record<string, ConnectionPresentation> = {docsHref: "https://neon.com/docs/ai/neon-mcp-server",keywords: ["mcp", "postgres", "databases", "branches", "sql", "oauth", "connect"],authModes: ["app"],- connector: "neon/neon",- connectorService: "neon",- defaultConnectorName: true,+ connectors: { app: { uid: "neon/neon", service: "neon" } },configureNote:"Neon's MCP server can modify projects and databases. Use a development or test project, review tool calls, and append `?readonly=true` or `?projectId=<project-id>` to scope access.",},@@ -2432,37 +2425,24 @@ function buildConnection(entry: IntegrationEntry): Integration {throw new Error(`Catalog connection "${entry.slug}" is missing its connection identity.`);}const identity: ConnectionIdentity = entry.connection;+ const { logo, docsHref, keywords, quickStart, configure, ...setup } = presentation;const spec: ConnectionSpec = {- authModes: presentation.authModes,+ ...setup,description: identity.description,};- if (presentation.apiKey !== undefined) spec.apiKey = presentation.apiKey;- if (presentation.connector !== undefined) spec.connector = presentation.connector;- if (presentation.connectors !== undefined) spec.connectors = presentation.connectors;- if (presentation.connectorService !== undefined) {- spec.connectorService = presentation.connectorService;- }- if (presentation.connectorServices !== undefined) {- spec.connectorServices = presentation.connectorServices;- }- if (presentation.defaultConnectorName !== undefined) {- spec.defaultConnectorName = presentation.defaultConnectorName;- }if (identity.mcp !== undefined) spec.mcp = identity.mcp;if (identity.openapi !== undefined) spec.openapi = identity.openapi;- if (presentation.configureNote !== undefined) spec.configureNote = presentation.configureNote;- if (presentation.configureNotes !== undefined) spec.configureNotes = presentation.configureNotes;return {slug: entry.slug,name: entry.name,type: "connection",tagline: entry.tagline,protocols: protocolsForIdentity(identity),- logo: presentation.logo,- docsHref: presentation.docsHref,- keywords: presentation.keywords,- quickStart: presentation.quickStart,- configure: presentation.configure,+ logo,+ docsHref,+ keywords,+ quickStart,+ configure,connection: spec,};}diff --git a/apps/docs/lib/integrations/discovery.ts b/apps/docs/lib/integrations/discovery.tsindex 1ec8c65e7..ef4e86325 100644--- a/apps/docs/lib/integrations/discovery.ts+++ b/apps/docs/lib/integrations/discovery.ts@@ -1,9 +1,9 @@import {- buildConnectionConfigure,buildConnectionInstall,buildConnectionSetup,+ renderConnectionVariants,} from "./connection-setup";-import { type Integration, authModeLabel, integrations, protocolLabel } from "./data";+import { type Integration, integrations } from "./data";const typeLabel: Record<Integration["type"], string> = {channel: "Channel",@@ -15,19 +15,6 @@ const typeLabel: Record<Integration["type"], string> = {const section = (title: string, content: string): string => `## ${title}\n\n${content}`;-const connectionQuickStart = (integration: Integration): string => {- const setup = buildConnectionSetup(integration);-- return setup.protocols- .flatMap((protocol) =>- setup.authModes.map((authMode) => {- const content = setup.variants[`${protocol}:${authMode}`] ?? "";- return `### ${protocolLabel[protocol]} · ${authModeLabel[authMode]}\n\n${content}`;- }),- )- .join("\n\n");-};-/** Plain text used by the advanced search index for one integration. */export const integrationSearchText = (integration: Integration): string =>[@@ -40,11 +27,13 @@ export const integrationSearchText = (integration: Integration): string =>/** Markdown representation shared by integration discovery and agent-readable routes. */export const integrationMarkdown = (integration: Integration): string => {const isConnection = integration.connection !== undefined;+ const setup = isConnection ? buildConnectionSetup(integration) : undefined;const install = isConnection ? buildConnectionInstall(integration) : (integration.install ?? "");const quickStart =- integration.quickStart ?? (isConnection ? connectionQuickStart(integration) : "");+ integration.quickStart ?? (setup ? renderConnectionVariants(setup, setup.variants) : "");const configure =- integration.configure ?? (isConnection ? buildConnectionConfigure(integration) : "");+ integration.configure ??+ (setup ? renderConnectionVariants(setup, setup.configureVariants) : "");return [`${typeLabel[integration.type]} integration for eve. ${integration.tagline}`,