feat: lazy graphql schema (#166)

* feat: support lazy tool definitions, disable client schema validation by
default

* feat: lazy tool descriptions

* chore: cleanup logs

* docs: restore comment

* feat: revert lazy tool definitions, just use lazy description

* chore: cleanup

* chore: unused imports

* test: schema is only loaded when listing tools

Author: mattrossman

packages/mcp-server-supabase/src/content-api/graphql.ts

@@ -121,7 +121,7 @@ export class GraphQLClient {
    */
   async query(
     request: GraphQLRequest,
-    options: QueryOptions = { validateSchema: true }
+    options: QueryOptions = { validateSchema: false }
   ) {
     try {
       // Check that this is a valid GraphQL query

packages/mcp-server-supabase/src/content-api/index.ts

@@ -6,7 +6,7 @@ const contentApiSchemaResponseSchema = z.object({
 });
 
 export type ContentApiClient = {
-  schema: string;
+  loadSchema: () => Promise<string>;
   query: QueryFn;
   setUserAgent: (userAgent: string) => void;
 };
@@ -18,18 +18,15 @@ export async function createContentApiClient(
   const graphqlClient = new GraphQLClient({
     url,
     headers,
+  });
+
+  return {
     // Content API provides schema string via `schema` query
-    loadSchema: async ({ query }) => {
-      const response = await query({ query: '{ schema }' });
+    loadSchema: async () => {
+      const response = await graphqlClient.query({ query: '{ schema }' });
       const { schema } = contentApiSchemaResponseSchema.parse(response);
       return schema;
     },
-  });
-
-  const { source } = await graphqlClient.schemaLoaded;
-
-  return {
-    schema: source,
     async query(request: GraphQLRequest) {
       return graphqlClient.query(request);
     },

packages/mcp-server-supabase/src/server.test.ts

@@ -11,6 +11,7 @@ import {
   ACCESS_TOKEN,
   API_URL,
   contentApiMockSchema,
+  mockContentApiSchemaLoadCount,
   createOrganization,
   createProject,
   createBranch,
@@ -31,6 +32,7 @@ beforeEach(async () => {
   mockOrgs.clear();
   mockProjects.clear();
   mockBranches.clear();
+  mockContentApiSchemaLoadCount.value = 0;
 
   const server = setupServer(...mockContentApi, ...mockManagementApi);
   server.listen({ onUnhandledRequest: 'error' });
@@ -2943,4 +2945,27 @@ describe('docs tools', () => {
 
     expect(tool.description.includes(contentApiMockSchema)).toBe(true);
   });
+
+  test('schema is only loaded when listing tools', async () => {
+    const { client, callTool } = await setup();
+
+    expect(mockContentApiSchemaLoadCount.value).toBe(0);
+
+    // "tools/list" requests fetch the schema
+    await client.listTools();
+    expect(mockContentApiSchemaLoadCount.value).toBe(1);
+
+    // "tools/call" should not fetch the schema again
+    await callTool({
+      name: 'search_docs',
+      arguments: {
+        graphql_query: '{ searchDocs(query: "test") { nodes { title } } }',
+      },
+    });
+    expect(mockContentApiSchemaLoadCount.value).toBe(1);
+
+    // Additional "tools/list" requests fetch the schema again
+    await client.listTools();
+    expect(mockContentApiSchemaLoadCount.value).toBe(2);
+  });
 });

packages/mcp-server-supabase/src/tools/docs-tools.ts

@@ -10,14 +10,16 @@ export type DocsToolsOptions = {
 export function getDocsTools({ contentApiClient }: DocsToolsOptions) {
   return {
     search_docs: tool({
-      description: source`
-        Search the Supabase documentation using GraphQL. Must be a valid GraphQL query.
+      description: async () => {
+        const schema = await contentApiClient.loadSchema();
 
-        You should default to calling this even if you think you already know the answer, since the documentation is always being updated.
-
-        Below is the GraphQL schema for the Supabase docs endpoint:
-        ${contentApiClient.schema}
-      `,
+        return source`
+          Search the Supabase documentation using GraphQL. Must be a valid GraphQL query.
+          You should default to calling this even if you think you already know the answer, since the documentation is always being updated.
+          Below is the GraphQL schema for the Supabase docs endpoint:
+          ${schema}
+        `;
+      },
       annotations: {
         title: 'Search docs',
         readOnlyHint: true,

packages/mcp-server-supabase/test/mocks.ts

@@ -84,6 +84,8 @@ export const mockOrgs = new Map<string, Organization>();
 export const mockProjects = new Map<string, MockProject>();
 export const mockBranches = new Map<string, MockBranch>();
 
+export const mockContentApiSchemaLoadCount = { value: 0 };
+
 export const mockContentApi = [
   http.post(CONTENT_API_URL, async ({ request }) => {
     const json = await request.json();
@@ -96,6 +98,7 @@ export const mockContentApi = [
     const [queryName] = getQueryFields(document);
 
     if (queryName === 'schema') {
+      mockContentApiSchemaLoadCount.value++;
       return HttpResponse.json({
         data: {
           schema: contentApiMockSchema,

packages/mcp-utils/src/server.ts

@@ -54,7 +54,7 @@ export type Tool<
   Params extends z.ZodObject<any> = z.ZodObject<any>,
   Result = unknown,
 > = {
-  description: string;
+  description: Prop<string>;
   annotations?: Annotations;
   parameters: Params;
   execute(params: z.infer<Params>): Promise<Result>;
@@ -436,24 +436,30 @@ export function createMcpServer(options: McpServerOptions) {
       ListToolsRequestSchema,
       async (): Promise<ListToolsResult> => {
         const tools = await getTools();
-        return {
-          tools: Object.entries(tools).map(
-            ([name, { description, annotations, parameters }]) => {
-              const inputSchema = zodToJsonSchema(parameters);
 
-              if (!('properties' in inputSchema)) {
-                throw new Error('tool parameters must be a ZodObject');
+        return {
+          tools: await Promise.all(
+            Object.entries(tools).map(
+              async ([name, { description, annotations, parameters }]) => {
+                const inputSchema = zodToJsonSchema(parameters);
+
+                if (!('properties' in inputSchema)) {
+                  throw new Error('tool parameters must be a ZodObject');
+                }
+
+                return {
+                  name,
+                  description:
+                    typeof description === 'function'
+                      ? await description()
+                      : description,
+                  annotations,
+                  inputSchema,
+                };
               }
-
-              return {
-                name,
-                description,
-                annotations,
-                inputSchema,
-              };
-            }
+            )
           ),
-        };
+        } satisfies ListToolsResult;
       }
     );
 
@@ -471,7 +477,6 @@ export function createMcpServer(options: McpServerOptions) {
         if (!tool) {
           throw new Error('tool not found');
         }
-
         const args = tool.parameters
           .strict()
           .parse(request.params.arguments ?? {});