The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.
TypeScript aialternativeauthdatabasedenoembeddingsexamplefirebasenextjsoauth2pgvectorpostgispostgrespostgresqlpostgrestrealtimesupabasevectorswebsockets
refactor(studio): add remote tool contracts, starting with list_extensions (#52175)
Charis23a56b2e6007
diff --git a/apps/studio/lib/ai/README.md b/apps/studio/lib/ai/README.mdindex 4f8ec1f6e22..8eb8f9cfd4a 100644--- a/apps/studio/lib/ai/README.md+++ b/apps/studio/lib/ai/README.md@@ -62,23 +62,23 @@ Keep per-request context in `assistant-context.ts`. The shared system prompt is### Tools-| Change | Start here |-| ------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |-| Tool assembly and platform/self-hosted selection | [tools/index.ts](./tools/index.ts) |-| Allowlist, minimum opt-in levels, and blocked-tool responses | [tool-filter.ts](./tool-filter.ts) |-| Studio tool assembly and opt-in requests | [studio-tools.ts](./tools/studio-tools.ts) |-| Remote MCP connection and tool selection | [supabase-mcp.ts](./supabase-mcp.ts), [mcp-tools.ts](./tools/mcp-tools.ts) |-| Schema and policy tools | [schema-tools.ts](./tools/schema-tools.ts) |-| Reports, notebooks, incidents, and support | [report-tools.ts](./tools/report-tools.ts), [notebook-tools.ts](./tools/notebook-tools.ts), [incident-tools.ts](./tools/incident-tools.ts), [support-tools.ts](./tools/support-tools.ts) |-| Self-hosted tools | [fallback-tools.ts](./tools/fallback-tools.ts) |-| Contract-based tools (see [Tool contracts](#tool-contracts)) | [registry.ts](./tools/registry.ts) lists them in `TOOL_CONTRACTS`; [types.ts](./tools/types.ts), [tool-from-contract.ts](./tools/tool-from-contract.ts) |--Tools are moving to [contracts](#tool-contracts); the rest declare their schemas and output handling directly. [registry.ts](./tools/registry.ts) is the source of truth for which are which: a tool in `TOOL_CONTRACTS` is a contract tool.+| Change | Start here |+| ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| Tool assembly and platform/self-hosted selection | [tools/index.ts](./tools/index.ts) |+| Allowlist, minimum opt-in levels, and blocked-tool responses | [tool-filter.ts](./tool-filter.ts) |+| Studio tool assembly and opt-in requests | [studio-tools.ts](./tools/studio-tools.ts) |+| Remote MCP connection and tool selection | [supabase-mcp.ts](./supabase-mcp.ts), [mcp-tools.ts](./tools/mcp-tools.ts) |+| Schema and policy tools | [schema-tools.ts](./tools/schema-tools.ts) |+| Reports, notebooks, incidents, and support | [report-tools.ts](./tools/report-tools.ts), [notebook-tools.ts](./tools/notebook-tools.ts), [incident-tools.ts](./tools/incident-tools.ts), [support-tools.ts](./tools/support-tools.ts) |+| Self-hosted tools | [fallback-tools.ts](./tools/fallback-tools.ts) |+| Contract-based tools (see [Tool contracts](#tool-contracts)) | [registry.ts](./tools/registry.ts) lists them in `TOOL_CONTRACTS` (and remote MCP tools in `REMOTE_TOOL_CONTRACTS`); [types.ts](./tools/types.ts), [tool-from-contract.ts](./tools/tool-from-contract.ts) |++Tools are moving to [contracts](#tool-contracts); the rest declare their schemas and output handling directly. [registry.ts](./tools/registry.ts) is the source of truth for which are which: a tool in `TOOL_CONTRACTS` or `REMOTE_TOOL_CONTRACTS` is a contract tool.For a new or changed tool:1. Prefer a [contract](#tool-contracts) for a new tool. Otherwise implement it in the appropriate tool module.-2. Include it in `getTools` through the module's tool getter, and add its name to the allowlist in `tool-filter.ts`. A contract declares minimum access as `minOptInLevel`; other tools use `TOOL_CATEGORY_MAP`.+2. Include it in `getTools` through the module's tool getter, and add its name to the allowlist in `tool-filter.ts`. A contract, local or remote, declares minimum access as `minOptInLevel`; other tools use `TOOL_CATEGORY_MAP`.3. Decide whether execution needs user approval and what output may reach the model, including on history replay. Read the [SQL safety skill](../../../../.agents/skills/safe-sql-execution/SKILL.md) before changing SQL execution.4. Update `Message.Parts.tsx` and its helpers if the tool needs a UI renderer.5. Update relevant tests, mock tools, and evaluation cases. See [local development and validation](#local-development-and-validation).@@ -106,6 +106,10 @@ To migrate a tool to a contract:7. Test the contract's `toModelOutput` at every opt-in level and on history replay, in [registry.test.ts](./tools/registry.test.ts) and [tool-sanitizer.test.ts](./tools/tool-sanitizer.test.ts) as applicable.8. Call out any change to what the model sees or to the stored shape in the PR description.+#### Remote contracts++A tool the remote MCP server implements has a `RemoteToolContract`: only `name`, `minOptInLevel`, and `needsApproval`. The server owns the description, input schema, execution, and output, so there is no `.server.ts` file and its parts stay `dynamic-tool`, outside `StudioUIMessage`. Register it in `REMOTE_TOOL_CONTRACTS` and remove it from `TOOL_CATEGORY_MAP`; [mcp-tools.ts](./tools/mcp-tools.ts) applies `needsApproval`, since MCP tool definitions can't declare it. [list-extensions.ts](./tools/list-extensions.ts) is an example.+## Access and data sharingThese checks have different responsibilities:diff --git a/apps/studio/lib/ai/tool-filter.ts b/apps/studio/lib/ai/tool-filter.tsindex eb6a292afd1..b2b02c078fd 100644--- a/apps/studio/lib/ai/tool-filter.ts+++ b/apps/studio/lib/ai/tool-filter.ts@@ -2,7 +2,12 @@ import type { Tool, ToolSet } from 'ai'import { z } from 'zod'import { isOptInLevelAtLeast } from './opt-in-level'-import { getToolContract, type ContractToolName } from './tools/registry'+import {+ getRemoteToolContract,+ getToolContract,+ type ContractToolName,+ type RemoteContractToolName,+} from './tools/registry'import type { AiOptInLevel } from '@/hooks/misc/useOrgOptedIntoAi'// Add the DatabaseExtension type import@@ -79,15 +84,18 @@ type ToolCategory = (typeof TOOL_CATEGORIES)[keyof typeof TOOL_CATEGORIES]/*** Mapping of tool names to their categories. Tools that have migrated to a contract- * (`TOOL_CONTRACTS`) declare their own `minOptInLevel` instead and aren't listed here.+ * (`TOOL_CONTRACTS` or `REMOTE_TOOL_CONTRACTS`) declare their own `minOptInLevel` instead and+ * aren't listed here.*/-export const TOOL_CATEGORY_MAP: Record<Exclude<ToolName, ContractToolName>, ToolCategory> = {+export const TOOL_CATEGORY_MAP: Record<+ Exclude<ToolName, ContractToolName | RemoteContractToolName>,+ ToolCategory+> = {// UI tools - always availablesearch_docs: TOOL_CATEGORIES.UI,// Schema tools - MCPlist_tables: TOOL_CATEGORIES.SCHEMA,- list_extensions: TOOL_CATEGORIES.SCHEMA,list_edge_functions: TOOL_CATEGORIES.SCHEMA,list_branches: TOOL_CATEGORIES.SCHEMA,getSchemaTables: TOOL_CATEGORIES.SCHEMA,@@ -127,7 +135,7 @@ function isCategorizedTool(name: string): name is keyof typeof TOOL_CATEGORY_MAP* tool isn't on the allowlist. A contract's `minOptInLevel` wins over the category map.*/function getToolMinimumLevel(toolName: string): AiOptInLevel | null | undefined {- const contract = getToolContract(toolName)+ const contract = getToolContract(toolName) ?? getRemoteToolContract(toolName)if (contract) return contract.minOptInLevelif (isCategorizedTool(toolName)) return getMinimumOptInLevel(TOOL_CATEGORY_MAP[toolName])return undefineddiff --git a/apps/studio/lib/ai/tools/list-extensions.ts b/apps/studio/lib/ai/tools/list-extensions.tsnew file mode 100644index 00000000000..7abeceb8acd--- /dev/null+++ b/apps/studio/lib/ai/tools/list-extensions.ts@@ -0,0 +1,7 @@+import type { RemoteToolContract } from './types'++export const contract = {+ name: 'list_extensions',+ minOptInLevel: 'schema',+ needsApproval: false,+} as const satisfies RemoteToolContractdiff --git a/apps/studio/lib/ai/tools/mcp-tools.test.ts b/apps/studio/lib/ai/tools/mcp-tools.test.tsindex 349c642c71a..3cdc208cf7c 100644--- a/apps/studio/lib/ai/tools/mcp-tools.test.ts+++ b/apps/studio/lib/ai/tools/mcp-tools.test.ts@@ -53,6 +53,12 @@ describe('ai/tools/mcp-tools getMcpTools', () => {expect(result).not.toHaveProperty('deploy_edge_function')})+ it('takes needsApproval from the contract', async () => {+ const result = await getMcpTools(BASE_PARAMS)++ expect(result.list_extensions?.needsApproval).toBe(false)+ })+it('warns when the remote server is missing an expected tool (contract drift)', async () => {const { list_branches, ...withoutBranches } = FULL_REMOTE_TOOLStools.mockResolvedValueOnce(withoutBranches)diff --git a/apps/studio/lib/ai/tools/mcp-tools.ts b/apps/studio/lib/ai/tools/mcp-tools.tsindex d14043528a7..9d4ff58892b 100644--- a/apps/studio/lib/ai/tools/mcp-tools.ts+++ b/apps/studio/lib/ai/tools/mcp-tools.ts@@ -4,6 +4,7 @@ import type { ToolSet } from 'ai'import { createSupabaseMCPClient } from '../supabase-mcp'import { filterToolsByOptInLevel, toolSetValidationSchema } from '../tool-filter'+import { REMOTE_TOOL_CONTRACTS } from './registry'import type { AiOptInLevel } from '@/hooks/misc/useOrgOptedIntoAi'/**@@ -78,7 +79,15 @@ export const getMcpTools = async ({signal.addEventListener('abort', closeClient, { once: true })try {- const availableMcpTools = (await mcpClient.tools()) as ToolSet+ const remoteTools = (await mcpClient.tools()) as ToolSet++ const availableMcpTools: ToolSet = { ...remoteTools }+ for (const contract of Object.values(REMOTE_TOOL_CONTRACTS)) {+ const remoteTool = remoteTools[contract.name]+ if (remoteTool) {+ availableMcpTools[contract.name] = { ...remoteTool, needsApproval: contract.needsApproval }+ }+ }// Runtime drift detection: `EXPECTED_MCP_TOOLS` is compile-time-checked// against the pinned package (see its declaration), but the *deployed* remotediff --git a/apps/studio/lib/ai/tools/registry.ts b/apps/studio/lib/ai/tools/registry.tsindex a429a5e0588..384400e6a84 100644--- a/apps/studio/lib/ai/tools/registry.ts+++ b/apps/studio/lib/ai/tools/registry.ts@@ -10,6 +10,7 @@ import { contract as getActiveIncidents } from './get-active-incidents'import { contract as getNotebook } from './get-notebook'import { contract as getReport } from './get-report'import { contract as listDatabases } from './list-databases'+import { contract as listExtensions } from './list-extensions'import { contract as listNotebooks } from './list-notebooks'import { contract as listPolicies } from './list-policies'import { contract as listReports } from './list-reports'@@ -17,7 +18,12 @@ import { contract as loadKnowledge } from './load-knowledge'import { contract as renameChat } from './rename-chat'import { contract as resolveSupportConversation } from './resolve-support-conversation'import { contract as runNotebook } from './run-notebook'-import type { ToolContract, ToolContractInput, ToolContractOutput } from './types'+import type {+ RemoteToolContract,+ ToolContract,+ ToolContractInput,+ ToolContractOutput,+} from './types'import { contract as updateNotebook } from './update-notebook'import { contract as updateOptInLevel } from './update-opt-in-level'import type { AiOptInLevel } from '@/hooks/misc/useOrgOptedIntoAi'@@ -72,6 +78,22 @@ export function getToolContract(toolName: string): ToolContract | undefined {: undefined}+/**+ * Remote MCP tools whose access Studio declares. Their parts stay `dynamic-tool`, so they aren't+ * part of `StudioUIMessage`.+ */+export const REMOTE_TOOL_CONTRACTS = {+ list_extensions: listExtensions,+} as const satisfies Partial<Record<ToolName, RemoteToolContract>>++export type RemoteContractToolName = keyof typeof REMOTE_TOOL_CONTRACTS++/** The contract for a migrated remote tool, or `undefined` if the tool hasn't been migrated. */+export function getRemoteToolContract(toolName: string): RemoteToolContract | undefined {+ const contracts: Partial<Record<string, RemoteToolContract>> = REMOTE_TOOL_CONTRACTS+ return Object.hasOwn(contracts, toolName) ? contracts[toolName] : undefined+}+/*** Applies the contract's `toModelOutput` to a persisted tool part, for history replay (where* the SDK doesn't call it). Returns `undefined` when the tool has no contract. An output thatdiff --git a/apps/studio/lib/ai/tools/types.ts b/apps/studio/lib/ai/tools/types.tsindex 1afb6b2e9e9..9ba9258ba52 100644--- a/apps/studio/lib/ai/tools/types.ts+++ b/apps/studio/lib/ai/tools/types.ts@@ -42,6 +42,12 @@ export type ToolContract<TInput = unknown, TOutput = unknown> = {outputOnInvalid?: JSONValue}+/**+ * A tool the remote MCP server implements. The server owns the description, input schema,+ * execution and output; Studio decides only who may run it and whether it needs approval.+ */+export type RemoteToolContract = Pick<ToolContract, 'name' | 'minOptInLevel' | 'needsApproval'>+export type ToolContractInput<C extends ToolContract> = z.infer<C['inputSchema']>export type ToolContractOutput<C extends ToolContract> = z.infer<C['outputSchema']>