Skip to content

armgit / eve

Public Imported from GitHub
0

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.ts
index 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.ts
index 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): string
if (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.ts
index 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.ts
index 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}`,