Merge pull request #63 from supabase-community/feat/project-scoped

feat: project scoped server option

Author: gregnr

README.md

@@ -46,6 +46,11 @@ Next, configure your MCP client (such as Cursor) to use this server. Most MCP cl
 
 Replace `<personal-access-token>` with the token you created in step 1. Alternatively you can omit `--access-token` and instead set the `SUPABASE_ACCESS_TOKEN` environment variable to your personal access token (you will need to restart your MCP client after setting this). This allows you to keep your token out of version control if you plan on committing this configuration to a repository.
 
+The following additional options are available:
+
+- `--project-ref`: Used to scope the server to a specific project. See [project scoped mode](#project-scoped-mode).
+- `--read-only`: Used to restrict the server to read-only queries. See [read-only mode](#read-only-mode).
+
 If you are on Windows, you will need to [prefix the command](#windows). If your MCP client doesn't accept JSON, the direct CLI command is:
 
 ```shell
@@ -111,6 +116,18 @@ Make sure Node.js is available in your system `PATH` environment variable. If yo
 
 3. Restart your MCP client.
 
+### Project scoped mode
+
+By default, the MCP server will have access to all organizations and projects in your Supabase account. If you want to restrict the server to a specific project, you can set the `--project-ref` flag on the CLI command:
+
+```shell
+npx -y @supabase/mcp-server-supabase@latest --access-token=<personal-access-token> --project-ref=<project-ref>
+```
+
+Replace `<project-ref>` with the ID of your project. You can find this under **Project ID** in your Supabase [project settings](https://supabase.com/dashboard/project/_/settings/general).
+
+After scoping the server to a project, [account-level](#project-management) tools like `list_projects` and `list_organizations` will no longer be available. The server will only have access to the specified project and its resources.
+
 ### Read-only mode
 
 If you wish to restrict the Supabase MCP server to read-only queries, set the `--read-only` flag on the CLI command:
@@ -129,6 +146,8 @@ The following Supabase tools are available to the LLM:
 
 #### Project Management
 
+_**Note:** these tools will be unavailable if the server is [scoped to a project](#project-scoped-mode)._
+
 - `list_projects`: Lists all Supabase projects for the user.
 - `get_project`: Gets details for a project.
 - `create_project`: Creates a new Supabase project.

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

@@ -34,14 +34,15 @@ beforeEach(async () => {
 
 type SetupOptions = {
   accessToken?: string;
+  projectId?: string;
   readOnly?: boolean;
 };
 
 /**
  * Sets up an MCP client and server for testing.
  */
 async function setup(options: SetupOptions = {}) {
-  const { accessToken = ACCESS_TOKEN, readOnly } = options;
+  const { accessToken = ACCESS_TOKEN, projectId, readOnly } = options;
   const clientTransport = new StreamTransport();
   const serverTransport = new StreamTransport();
 
@@ -63,6 +64,7 @@ async function setup(options: SetupOptions = {}) {
       apiUrl: API_URL,
       accessToken,
     },
+    projectId,
     readOnly,
   });
 
@@ -348,7 +350,6 @@ describe('tools', () => {
       name: 'New Project',
       region: 'us-east-1',
       organization_id: freeOrg.id,
-      db_pass: 'dummy-password',
       confirm_cost_id,
     };
 
@@ -357,7 +358,7 @@ describe('tools', () => {
       arguments: newProject,
     });
 
-    const { db_pass, confirm_cost_id: _, ...projectInfo } = newProject;
+    const { confirm_cost_id: _, ...projectInfo } = newProject;
 
     expect(result).toEqual({
       ...projectInfo,
@@ -390,7 +391,6 @@ describe('tools', () => {
     const newProject = {
       name: 'New Project',
       organization_id: freeOrg.id,
-      db_pass: 'dummy-password',
       confirm_cost_id,
     };
 
@@ -399,7 +399,7 @@ describe('tools', () => {
       arguments: newProject,
     });
 
-    const { db_pass, confirm_cost_id: _, ...projectInfo } = newProject;
+    const { confirm_cost_id: _, ...projectInfo } = newProject;
 
     expect(result).toEqual({
       ...projectInfo,
@@ -425,7 +425,6 @@ describe('tools', () => {
       name: 'New Project',
       region: 'us-east-1',
       organization_id: org.id,
-      db_pass: 'dummy-password',
     };
 
     const createProjectPromise = callTool({
@@ -1911,3 +1910,154 @@ describe('tools', () => {
     }
   });
 });
+
+describe('project scoped tools', () => {
+  test('no account level tools should exist', async () => {
+    const org = await createOrganization({
+      name: 'My Org',
+      plan: 'free',
+      allowed_release_channels: ['ga'],
+    });
+
+    const project = await createProject({
+      name: 'Project 1',
+      region: 'us-east-1',
+      organization_id: org.id,
+    });
+
+    const { client } = await setup({ projectId: project.id });
+
+    const result = await client.listTools();
+
+    const accountLevelToolNames = [
+      'list_organizations',
+      'get_organization',
+      'list_projects',
+      'get_project',
+      'get_cost',
+      'confirm_cost',
+      'create_project',
+      'pause_project',
+      'restore_project',
+    ];
+
+    const toolNames = result.tools.map((tool) => tool.name);
+
+    for (const accountLevelToolName of accountLevelToolNames) {
+      expect(
+        toolNames,
+        `tool ${accountLevelToolName} should not be available in project scope`
+      ).not.toContain(accountLevelToolName);
+    }
+  });
+
+  test('no tool should accept a project_id', async () => {
+    const org = await createOrganization({
+      name: 'My Org',
+      plan: 'free',
+      allowed_release_channels: ['ga'],
+    });
+
+    const project = await createProject({
+      name: 'Project 1',
+      region: 'us-east-1',
+      organization_id: org.id,
+    });
+
+    const { client } = await setup({ projectId: project.id });
+
+    const result = await client.listTools();
+
+    expect(result.tools).toBeDefined();
+    expect(Array.isArray(result.tools)).toBe(true);
+
+    for (const tool of result.tools) {
+      const schemaProperties = tool.inputSchema.properties ?? {};
+      expect(
+        'project_id' in schemaProperties,
+        `tool ${tool.name} should not accept a project_id`
+      ).toBe(false);
+    }
+  });
+
+  test('invalid project ID should throw an error', async () => {
+    const { callTool } = await setup({ projectId: 'invalid-project-id' });
+
+    const listTablesPromise = callTool({
+      name: 'list_tables',
+      arguments: {
+        schemas: ['public'],
+      },
+    });
+
+    await expect(listTablesPromise).rejects.toThrow('Project not found');
+  });
+
+  test('passing project_id to a tool should throw an error', async () => {
+    const org = await createOrganization({
+      name: 'My Org',
+      plan: 'free',
+      allowed_release_channels: ['ga'],
+    });
+
+    const project = await createProject({
+      name: 'Project 1',
+      region: 'us-east-1',
+      organization_id: org.id,
+    });
+    project.status = 'ACTIVE_HEALTHY';
+
+    const { callTool } = await setup({ projectId: project.id });
+
+    const listTablesPromise = callTool({
+      name: 'list_tables',
+      arguments: {
+        project_id: 'my-project-id',
+        schemas: ['public'],
+      },
+    });
+
+    await expect(listTablesPromise).rejects.toThrow('Unrecognized key');
+  });
+
+  test('listing tables implicitly uses the scoped project_id', async () => {
+    const org = await createOrganization({
+      name: 'My Org',
+      plan: 'free',
+      allowed_release_channels: ['ga'],
+    });
+
+    const project = await createProject({
+      name: 'Project 1',
+      region: 'us-east-1',
+      organization_id: org.id,
+    });
+    project.status = 'ACTIVE_HEALTHY';
+
+    project.db
+      .sql`create table test (id integer generated always as identity primary key)`;
+
+    const { callTool } = await setup({ projectId: project.id });
+
+    const result = await callTool({
+      name: 'list_tables',
+      arguments: {
+        schemas: ['public'],
+      },
+    });
+
+    expect(result).toEqual([
+      expect.objectContaining({
+        name: 'test',
+        schema: 'public',
+        columns: [
+          expect.objectContaining({
+            name: 'id',
+            is_identity: true,
+            is_generated: false,
+          }),
+        ],
+      }),
+    ]);
+  });
+});