fix(server): hide mutating stdio tools in read-only mode fixes #281

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

@@ -136,6 +136,14 @@ export function createSupabaseMcpServer(options: SupabaseMcpServerOptions) {
     tools: async () => {
       const contentApiClient = await contentApiClientPromise;
       const tools: Record<string, Tool> = {};
+      const addTools = (next: Record<string, Tool>) =>
+        Object.entries(next).forEach(([name, tool]) => {
+          if (readOnly && tool.annotations?.readOnlyHint === false) {
+            return;
+          }
+
+          tools[name] = tool;
+        });
 
       const {
         account,
@@ -148,16 +156,15 @@ export function createSupabaseMcpServer(options: SupabaseMcpServerOptions) {
       } = platform;
 
       if (enabledFeatures.has('docs')) {
-        Object.assign(tools, getDocsTools({ contentApiClient }));
+        addTools(getDocsTools({ contentApiClient }));
       }
 
       if (!projectId && account && enabledFeatures.has('account')) {
-        Object.assign(tools, getAccountTools({ account, readOnly }));
+        addTools(getAccountTools({ account, readOnly }));
       }
 
       if (database && enabledFeatures.has('database')) {
-        Object.assign(
-          tools,
+        addTools(
           getDatabaseTools({
             database,
             projectId,
@@ -167,29 +174,41 @@ export function createSupabaseMcpServer(options: SupabaseMcpServerOptions) {
       }
 
       if (debugging && enabledFeatures.has('debugging')) {
-        Object.assign(tools, getDebuggingTools({ debugging, projectId }));
+        addTools(getDebuggingTools({ debugging, projectId }));
       }
 
       if (development && enabledFeatures.has('development')) {
-        Object.assign(tools, getDevelopmentTools({ development, projectId }));
+        addTools(getDevelopmentTools({ development, projectId }));
       }
 
       if (functions && enabledFeatures.has('functions')) {
-        Object.assign(
-          tools,
-          getEdgeFunctionTools({ functions, projectId, readOnly })
+        addTools(
+          getEdgeFunctionTools({
+            functions,
+            projectId,
+            readOnly,
+          })
         );
       }
 
       if (branching && enabledFeatures.has('branching')) {
-        Object.assign(
-          tools,
-          getBranchingTools({ branching, projectId, readOnly })
+        addTools(
+          getBranchingTools({
+            branching,
+            projectId,
+            readOnly,
+          })
         );
       }
 
       if (storage && enabledFeatures.has('storage')) {
-        Object.assign(tools, getStorageTools({ storage, projectId, readOnly }));
+        addTools(
+          getStorageTools({
+            storage,
+            projectId,
+            readOnly,
+          })
+        );
       }
 
       return tools;

packages/mcp-server-supabase/src/tools/tool-schemas.test.ts

@@ -51,6 +51,21 @@ describe('createToolSchemas', () => {
       expectTypeOf(schemas).toHaveProperty('search_docs');
       expectTypeOf(schemas).not.toHaveProperty('execute_sql');
     });
+
+    test('normalizes deprecated feature names', () => {
+      const deprecatedSchemas = createToolSchemas({
+        features: ['debug'] as any,
+      });
+      const currentSchemas = createToolSchemas({ features: ['debugging'] });
+
+      expect(Object.keys(deprecatedSchemas).sort()).toEqual(
+        Object.keys(currentSchemas).sort()
+      );
+      expect(Object.keys(deprecatedSchemas).sort()).toEqual([
+        'get_advisors',
+        'get_logs',
+      ]);
+    });
   });
 
   describe('PROJECT_SCOPED_OVERRIDES completeness', () => {

packages/mcp-server-supabase/src/tools/tool-schemas.ts

@@ -1,5 +1,9 @@
 import type { z } from 'zod/v4';
-import { CURRENT_FEATURE_GROUPS, type FeatureGroup } from '../types.js';
+import {
+  CURRENT_FEATURE_GROUPS,
+  featureGroupSchema,
+  type FeatureGroup,
+} from '../types.js';
 import { accountToolDefs } from './account-tools.js';
 import { branchingToolDefs } from './branching-tools.js';
 import { databaseToolDefs } from './database-operation-tools.js';
@@ -247,7 +251,9 @@ export function createToolSchemas<
   readOnly?: ReadOnly;
 }): ToolSchemasFor<Features[number], ProjectScoped, ReadOnly> {
   const enabledFeatures = new Set<string>(
-    options?.features ?? CURRENT_FEATURE_GROUPS
+    (options?.features ?? CURRENT_FEATURE_GROUPS).map((feature) =>
+      featureGroupSchema.parse(feature)
+    )
   );
   const projectScoped = options?.projectScoped ?? false;
   const readOnly = options?.readOnly ?? false;

packages/mcp-server-supabase/test/stdio.integration.ts

@@ -66,6 +66,21 @@ describe('stdio', () => {
     expect(tools.length).toBeGreaterThan(0);
   });
 
+  test('read-only mode filters mutating tools from tool list', async () => {
+    const { client } = await setup({ readOnly: true });
+
+    const { tools } = await client.listTools();
+    const toolNames = new Set(tools.map((tool) => tool.name));
+
+    expect(toolNames.has('apply_migration')).toBe(false);
+    expect(toolNames.has('deploy_edge_function')).toBe(false);
+    expect(toolNames.has('create_branch')).toBe(false);
+    expect(toolNames.has('delete_branch')).toBe(false);
+
+    expect(toolNames.has('list_tables')).toBe(true);
+    expect(toolNames.has('execute_sql')).toBe(true);
+  });
+
   test('missing access token fails', async () => {
     const setupPromise = setup({ accessToken: null as any });