Skip to content

Commit 9145db0

Browse files
SferaDevSferaDev
committed
Support per-call server selection for OpenAPI tools
Resolve OpenAPI servers per tool call instead of baking a single base URL at add time. Operations can declare multiple servers (document, path, or operation level) and templated URLs with {variables}; each is now selectable when invoking the tool. - Each tool exposes an optional `server` input ({ url?, variables? }), shown only when there is something to choose: `url` becomes an enum when more than one server applies, and `variables` are drawn from the applicable servers. - Host resolution: a connection base URL override wins when set; otherwise the call's chosen server (server.url or the first applicable) is resolved with its {variables} (call values, else spec defaults); otherwise no host is prepended. - The connection base URL becomes an optional override (off by default), required only when the spec declares no servers. The form shows a combobox for multiple top-level servers and a plain input otherwise, with the first server's resolved URL as the placeholder. - Drop connection-level serverVariables in favor of per-call variables. - Bindings persisted before this change keep working: a missing `servers` field is treated as empty and falls back to the connection base URL.
1 parent dbb48ec commit 9145db0

12 files changed

Lines changed: 515 additions & 113 deletions

‎packages/plugins/openapi/src/react/AddOpenApiSource.tsx‎

Lines changed: 36 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -49,10 +49,9 @@ import {
4949
type GoogleOpenApiPreset,
5050
} from "../sdk/google-presets";
5151
import type { SpecPreview, HeaderPreset, OAuth2Preset } from "../sdk/preview";
52-
import { type APIKeyAuthentication, type Authentication, type ServerInfo } from "../sdk/types";
53-
import { expandServerUrlOptions } from "../sdk/openapi-utils";
52+
import { type APIKeyAuthentication, type Authentication } from "../sdk/types";
53+
import { resolveServerUrl } from "../sdk/openapi-utils";
5454

55-
const GOOGLE_BUNDLE_BASE_URL = "https://www.googleapis.com/";
5655
const GOOGLE_BUNDLE_FAVICON = "https://fonts.gstatic.com/s/i/productlogos/googleg/v6/192px.svg";
5756

5857
// The bundle picker opens with the featured Google APIs pre-checked.
@@ -197,14 +196,6 @@ const oauthTemplateFromPreset = (
197196
scopes: [...scopes],
198197
});
199198

200-
const expandServerOptions = (server: ServerInfo) =>
201-
expandServerUrlOptions(server).map((value) => ({ value, label: value }));
202-
203-
const firstBaseUrlForPreview = (preview: SpecPreview): string => {
204-
const firstServer = preview.servers[0];
205-
return firstServer ? (expandServerUrlOptions(firstServer)[0] ?? "") : "";
206-
};
207-
208199
// ---------------------------------------------------------------------------
209200
// All spec-detected auth methods → the union of stored `Authentication`
210201
// templates. Header presets become apiKey templates; each oauth2 preset becomes
@@ -270,7 +261,7 @@ export default function AddOpenApiSource(props: {
270261

271262
// After analysis
272263
const [preview, setPreview] = useState<SpecPreview | null>(null);
273-
const [baseUrl, setBaseUrl] = useState(isGoogleBundlePreset ? GOOGLE_BUNDLE_BASE_URL : "");
264+
const [baseUrl, setBaseUrl] = useState("");
274265
const identityFallbackName = isGoogleBundlePreset
275266
? "Google"
276267
: preview
@@ -332,10 +323,20 @@ export default function AddOpenApiSource(props: {
332323

333324
// ---- Derived state ----
334325

335-
const servers: readonly ServerInfo[] = preview?.servers ?? [];
336-
const baseUrlOptions = Array.from(
337-
new Map(servers.flatMap(expandServerOptions).map((option) => [option.value, option])).values(),
338-
);
326+
const previewHasNoServers = preview !== null && preview.servers.length === 0;
327+
// Offer the spec's servers (resolved with defaults) as base-URL choices when
328+
// there's more than one; a single/no server uses a plain input.
329+
const baseUrlOptions =
330+
preview && preview.servers.length > 1
331+
? preview.servers.map((server) => {
332+
const url = resolveServerUrl(server.url, Option.getOrUndefined(server.variables), {});
333+
return { value: url, label: url };
334+
})
335+
: undefined;
336+
const firstServer = preview?.servers[0];
337+
const firstServerUrl = firstServer
338+
? resolveServerUrl(firstServer.url, Option.getOrUndefined(firstServer.variables), {})
339+
: "";
339340
const previewPresetIcon =
340341
openApiPresets.find(
341342
(preset) => preset.url && normalizePresetUrl(preset.url) === normalizePresetUrl(specUrl),
@@ -409,7 +410,12 @@ export default function AddOpenApiSource(props: {
409410
const hasPreviewOrBundle = isGoogleBundlePreset
410411
? bundleDiscoveryUrls.length > 0
411412
: preview !== null;
412-
const canAdd = hasPreviewOrBundle && resolvedBaseUrl.length > 0 && !slugAlreadyExists;
413+
// The base URL is optional when the spec declares servers (resolved per call);
414+
// required only when it doesn't.
415+
const canAdd =
416+
hasPreviewOrBundle &&
417+
!slugAlreadyExists &&
418+
(!previewHasNoServers || resolvedBaseUrl.length > 0);
413419

414420
// ---- Handlers ----
415421

@@ -425,7 +431,7 @@ export default function AddOpenApiSource(props: {
425431
}
426432
const result = exit.value;
427433
setPreview(result);
428-
setBaseUrl(firstBaseUrlForPreview(result));
434+
setBaseUrl("");
429435
setAnalyzing(false);
430436
};
431437

@@ -551,9 +557,9 @@ export default function AddOpenApiSource(props: {
551557
identity={identity}
552558
baseUrl={resolvedBaseUrl}
553559
onBaseUrlChange={setBaseUrl}
560+
baseUrlLabel="Base URL override (optional)"
554561
faviconIcon={GOOGLE_BUNDLE_FAVICON}
555562
faviconUrl={resolvedBaseUrl}
556-
baseUrlMissingMessage="A base URL is required to make requests."
557563
/>
558564
) : preview ? (
559565
<OpenApiSourceDetailsFields
@@ -569,15 +575,24 @@ export default function AddOpenApiSource(props: {
569575
baseUrl={resolvedBaseUrl}
570576
onBaseUrlChange={setBaseUrl}
571577
baseUrlOptions={baseUrlOptions}
578+
baseUrlLabel={previewHasNoServers ? "Base URL" : "Base URL override (optional)"}
579+
baseUrlPlaceholder={firstServerUrl || "https://api.example.com"}
580+
baseUrlHint={
581+
previewHasNoServers
582+
? undefined
583+
: "Overrides the spec's servers; leave empty to choose the server (and variables) per tool call."
584+
}
585+
baseUrlMissingMessage={
586+
previewHasNoServers ? "This spec declares no servers — enter a base URL." : undefined
587+
}
572588
specUrl={specUrl}
573589
onSpecUrlChange={(value) => {
574590
setSpecUrl(value);
575591
setPreview(null);
576592
setBaseUrl("");
577593
}}
578594
faviconIcon={previewPresetIcon}
579-
faviconUrl={resolvedBaseUrl}
580-
baseUrlMissingMessage="A base URL is required to make requests."
595+
faviconUrl={resolvedBaseUrl || firstServerUrl}
581596
/>
582597
) : null}
583598

‎packages/plugins/openapi/src/react/OpenApiSourceDetailsFields.tsx‎

Lines changed: 11 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,9 @@ export function OpenApiSourceDetailsFields(props: {
2525
readonly baseUrl: string;
2626
readonly onBaseUrlChange: (value: string) => void;
2727
readonly baseUrlOptions?: readonly FreeformComboboxOption[];
28+
readonly baseUrlLabel?: string;
29+
readonly baseUrlPlaceholder?: string;
30+
readonly baseUrlHint?: string;
2831
readonly specUrl?: string;
2932
readonly onSpecUrlChange?: (value: string) => void;
3033
readonly faviconIcon?: string | null;
@@ -35,8 +38,6 @@ export function OpenApiSourceDetailsFields(props: {
3538
readonly baseUrlMissingMessage?: string;
3639
readonly footer?: string;
3740
}) {
38-
const baseUrlOptions = props.baseUrlOptions ?? [];
39-
4041
return (
4142
<CardStack>
4243
<CardStackContent className="border-t-0">
@@ -61,21 +62,21 @@ export function OpenApiSourceDetailsFields(props: {
6162
namespaceReadOnly={props.namespaceReadOnly}
6263
/>
6364
<div className="grid grid-cols-1 md:grid-cols-2">
64-
<CardStackEntryField label="Base URL">
65-
{baseUrlOptions.length > 0 ? (
65+
<CardStackEntryField label={props.baseUrlLabel ?? "Base URL"}>
66+
{props.baseUrlOptions && props.baseUrlOptions.length > 0 ? (
6667
<FreeformCombobox
6768
value={props.baseUrl}
6869
onValueChange={props.onBaseUrlChange}
69-
options={baseUrlOptions}
70-
placeholder="https://api.example.com"
70+
options={props.baseUrlOptions}
71+
placeholder={props.baseUrlPlaceholder ?? "https://api.example.com"}
7172
className="w-full"
7273
inputClassName="font-mono text-sm"
7374
/>
7475
) : (
7576
<Input
7677
value={props.baseUrl}
7778
onChange={(e) => props.onBaseUrlChange((e.target as HTMLInputElement).value)}
78-
placeholder="https://api.example.com"
79+
placeholder={props.baseUrlPlaceholder ?? "https://api.example.com"}
7980
className="font-mono text-sm"
8081
/>
8182
)}
@@ -85,6 +86,9 @@ export function OpenApiSourceDetailsFields(props: {
8586
{props.baseUrlMissingMessage}
8687
</p>
8788
)}
89+
{props.baseUrlHint && (
90+
<p className="text-[11px] text-muted-foreground">{props.baseUrlHint}</p>
91+
)}
8892
</CardStackEntryField>
8993
{props.specUrl !== undefined && props.onSpecUrlChange && (
9094
<CardStackEntryField label="Spec URL">

‎packages/plugins/openapi/src/sdk/config.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,7 @@ export const OpenApiIntegrationConfigSchema = Schema.Struct({
3737
sourceUrl: Schema.optional(Schema.String),
3838
/** Google Discovery bundle URLs, when the spec came from a Google bundle. */
3939
googleDiscoveryUrls: Schema.optional(Schema.Array(Schema.String)),
40-
/** Base URL override; falls back to the spec's first server. */
40+
/** Optional base URL override. */
4141
baseUrl: Schema.optional(Schema.String),
4242
/** Static headers applied to every request (no secret material). */
4343
headers: Schema.optional(Schema.Record(Schema.String, Schema.String)),

‎packages/plugins/openapi/src/sdk/extract.ts‎

Lines changed: 68 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,6 @@ import {
66
declaredContents,
77
DocResolver,
88
preferredResponseContent,
9-
resolveBaseUrl,
109
type OperationObject,
1110
type ParameterObject,
1211
type PathItemObject,
@@ -169,9 +168,60 @@ const extractOutputSchema = (operation: OperationObject, r: DocResolver): unknow
169168
// Input schema builder
170169
// ---------------------------------------------------------------------------
171170

171+
// Optional `server` input — host selection + server-URL variables. Undefined
172+
// when there's nothing to configure (a single server with no variables).
173+
const buildServerInputProperty = (
174+
servers: readonly ServerInfo[],
175+
): Record<string, unknown> | undefined => {
176+
const variableDefs: Record<string, ServerVariable> = {};
177+
for (const server of servers) {
178+
for (const [name, v] of Object.entries(Option.getOrUndefined(server.variables) ?? {})) {
179+
if (!(name in variableDefs)) variableDefs[name] = v;
180+
}
181+
}
182+
const hasMultiple = servers.length > 1;
183+
const variableNames = Object.keys(variableDefs);
184+
if (!hasMultiple && variableNames.length === 0) return undefined;
185+
186+
const properties: Record<string, unknown> = {};
187+
if (hasMultiple) {
188+
properties.url = {
189+
type: "string",
190+
enum: servers.map((server) => server.url),
191+
default: servers[0]!.url,
192+
description: "Which of the spec's servers to send the request to.",
193+
};
194+
}
195+
if (variableNames.length > 0) {
196+
properties.variables = {
197+
type: "object",
198+
additionalProperties: false,
199+
properties: Object.fromEntries(
200+
Object.entries(variableDefs).map(([name, v]) => [
201+
name,
202+
{
203+
type: "string",
204+
default: v.default,
205+
...(Option.isSome(v.enum) ? { enum: v.enum.value } : {}),
206+
...(Option.isSome(v.description) ? { description: v.description.value } : {}),
207+
},
208+
]),
209+
),
210+
description: "Values for the server URL `{variables}`; spec defaults apply when omitted.",
211+
};
212+
}
213+
return {
214+
type: "object",
215+
additionalProperties: false,
216+
properties,
217+
description: "Optional host selection and server-URL variables for this request.",
218+
};
219+
};
220+
172221
const buildInputSchema = (
173222
parameters: readonly OperationParameter[],
174223
requestBody: OperationRequestBody | undefined,
224+
servers: readonly ServerInfo[],
175225
): Record<string, unknown> | undefined => {
176226
const properties: Record<string, unknown> = {};
177227
const required: string[] = [];
@@ -181,6 +231,10 @@ const buildInputSchema = (
181231
if (param.required) required.push(param.name);
182232
}
183233

234+
// A path/query parameter named `server` takes precedence over the host input.
235+
const serverProperty = buildServerInputProperty(servers);
236+
if (serverProperty && !("server" in properties)) properties.server = serverProperty;
237+
184238
if (requestBody) {
185239
properties.body = Option.getOrElse(requestBody.schema, () => ({ type: "object" }));
186240
if (requestBody.required) required.push("body");
@@ -283,17 +337,16 @@ const extractServerList = (servers: readonly ServerObject[] | undefined): Server
283337

284338
const extractServers = (doc: ParsedDocument): ServerInfo[] => extractServerList(doc.servers);
285339

286-
const extractOperationBaseUrl = (
340+
const operationServers = (
287341
pathItem: PathItemObject,
288342
operation: OperationObject,
289-
): string | undefined => {
290-
const operationServers = extractServerList(operation.servers);
291-
if (operationServers.length > 0) return resolveBaseUrl(operationServers);
292-
293-
const pathServers = extractServerList(pathItem.servers);
294-
if (pathServers.length > 0) return resolveBaseUrl(pathServers);
295-
296-
return undefined;
343+
docServers: readonly ServerInfo[],
344+
): readonly ServerInfo[] => {
345+
const operationLevel = extractServerList(operation.servers);
346+
if (operationLevel.length > 0) return operationLevel;
347+
const pathLevel = extractServerList(pathItem.servers);
348+
if (pathLevel.length > 0) return pathLevel;
349+
return docServers;
297350
};
298351

299352
// ---------------------------------------------------------------------------
@@ -310,6 +363,7 @@ export const extract = Effect.fn("OpenApi.extract")(function* (doc: ParsedDocume
310363
}
311364

312365
const r = new DocResolver(doc);
366+
const docServers = extractServers(doc);
313367
const operations: ExtractedOperation[] = [];
314368

315369
for (const [pathTemplate, pathItem] of Object.entries(paths).sort(([a], [b]) =>
@@ -323,7 +377,8 @@ export const extract = Effect.fn("OpenApi.extract")(function* (doc: ParsedDocume
323377

324378
const parameters = extractParameters(pathItem, operation, r);
325379
const requestBody = extractRequestBody(operation, r);
326-
const inputSchema = buildInputSchema(parameters, requestBody);
380+
const servers = operationServers(pathItem, operation, docServers);
381+
const inputSchema = buildInputSchema(parameters, requestBody, servers);
327382
const outputSchema = extractOutputSchema(operation, r);
328383
const tags = (operation.tags ?? []).filter((t) => t.trim().length > 0);
329384
const operationPathTemplate = explicitPathTemplate(operation) ?? pathTemplate;
@@ -333,7 +388,7 @@ export const extract = Effect.fn("OpenApi.extract")(function* (doc: ParsedDocume
333388
operationId: OperationId.make(deriveOperationId(method, pathTemplate, operation)),
334389
toolPath: Option.fromNullishOr(explicitToolPath(operation)),
335390
method,
336-
baseUrl: extractOperationBaseUrl(pathItem, operation),
391+
servers,
337392
pathTemplate: operationPathTemplate,
338393
summary: Option.fromNullishOr(operation.summary),
339394
description: Option.fromNullishOr(operation.description),
@@ -351,7 +406,7 @@ export const extract = Effect.fn("OpenApi.extract")(function* (doc: ParsedDocume
351406
return ExtractionResult.make({
352407
title: Option.fromNullishOr(doc.info?.title),
353408
version: Option.fromNullishOr(doc.info?.version),
354-
servers: extractServers(doc),
409+
servers: docServers,
355410
operations,
356411
});
357412
});

‎packages/plugins/openapi/src/sdk/google-discovery.test.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -436,9 +436,9 @@ it.effect("bundles Google Discovery documents into one Google OpenAPI source", (
436436
const extractedChatMessage = extracted.operations.find(
437437
(candidate) => candidate.operationId === "chat.spaces.messages.get",
438438
);
439-
expect(extractedGmail?.baseUrl).toBe("https://gmail.googleapis.com/");
439+
expect(extractedGmail?.servers[0]?.url).toBe("https://gmail.googleapis.com/");
440440
expect(extractedChatMessage?.pathTemplate).toBe("/v1/{+name}");
441-
expect(extractedChatMessage?.baseUrl).toBe("https://chat.googleapis.com/");
441+
expect(extractedChatMessage?.servers[0]?.url).toBe("https://chat.googleapis.com/");
442442
// v2: the bundled oauth scopes are carried on the oauth auth template.
443443
const oauthTemplate = result.authenticationTemplate?.find((entry) => entry.kind === "oauth2");
444444
expect(oauthTemplate?.kind === "oauth2" ? oauthTemplate.scopes : undefined).toEqual([

‎packages/plugins/openapi/src/sdk/index.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,7 @@ export {
4040
} from "./preview";
4141
export {
4242
DocResolver,
43-
resolveBaseUrl,
43+
resolveServerUrl,
4444
substituteUrlVariables,
4545
preferredContent,
4646
} from "./openapi-utils";

0 commit comments

Comments
 (0)