feat: automate MCP client documentation by Rodriguespn · Pull Request #179 · supabase/mcp

Rodriguespn · 2025-11-13T13:33:19Z

Automate MCP Client Documentation

This PR implements an automated system for managing MCP client documentation in the README.

Linear Issue: https://linear.app/supabase/issue/AI-274/automate-mcp-client-documentation-in-readmemd

Overview

The system uses TypeScript constants and a template-based approach to generate consistent client documentation, eliminating manual markdown editing and ensuring the README stays in sync with client metadata.

Changes

Documentation System:

Added packages/mcp-server-supabase/docs/clients.ts - TypeScript constants with client metadata (exported from package for external use)
Added docs/clients/_template.md - Handlebars-style template for generating docs
Added support for custom manual configuration snippets (YAML) via manualSnippet
No runtime validation needed - TypeScript provides compile-time safety
Client metadata is exported from @supabase/mcp-server-supabase package for use in external projects

Scripts:

npm run docs:generate-clients - Generates client docs from TypeScript constants + template

Existing Client Configs

Cursor - AI-powered code editor with deeplink installation
VS Code - Visual Studio Code with GitHub Copilot (stable + insiders)
Factory - AI-powered code assistant with CLI installation

New Client Configs

Claude Code - Claude's code editor with CLI installation
Goose - Desktop & CLI, supports streamable_http extension with deeplink, CLI command, and YAML manual configuration

Testing

# Generate client documentation
npm run docs:generate-clients

# Type check the constants file
pnpm exec tsc --noEmit packages/mcp-server-supabase/docs/clients.ts

github-actions · 2025-11-13T13:33:41Z

✅ Client documentation validated. No changes needed.

github-actions · 2025-11-13T13:38:47Z

✅ Client documentation validated. No changes needed.

Use configFilePath directly in template to generate consistent instructions

github-actions · 2025-11-13T13:42:29Z

✅ Client documentation validated. No changes needed.

…stants Per Matt's feedback, removed over-engineered validation system in favor of compile-time TypeScript validation similar to the main Supabase docs. Changes: - Replace clients.json with constants.ts (TypeScript data file) - Remove Zod validation and types.ts - Remove interactive CLI tool (add-client.ts) - Update generate-clients.ts to use imported constants directly - Update GitHub workflow to use tsc for type checking - Remove Zod dependency from package.json - Update documentation to reflect TypeScript-only approach Benefits: - Simpler mental model (just TypeScript) - Compile-time validation instead of runtime - No additional dependencies beyond TypeScript - Easier to maintain and contribute to

github-actions · 2025-11-13T15:08:19Z

✅ Client documentation validated. No changes needed.

…aring Moved client metadata from docs/clients/constants.ts to packages/mcp-server-supabase/src/clients.ts and exported from the package. This allows: - Documentation scripts to import client data - External Node.js projects to import from the published npm package - Single source of truth for client configurations Changes: - Created packages/mcp-server-supabase/src/clients.ts with client data - Export clients and types from package index - Updated docs/clients/constants.ts to re-export from package - Updated GitHub workflow to check the new path - Updated documentation to reflect the new architecture - Built package to verify exports work correctly

github-actions · 2025-11-13T15:29:56Z

✅ Client documentation validated. No changes needed.

Added Claude Code as a supported MCP client with: - CLI installation command - Manual configuration instructions - OAuth authentication flow guidance

… custom config format - Added Goose with deeplink and CLI install command - Manual config path set to ~/.config/goose/config.yaml (custom format) - Updated types to allow 'custom' configFormat - Regenerated docs and README

…ded manualSnippet to ManualConfig\n- Updated Goose client with YAML configuration snippet and new button image\n- Updated template to render YAML when custom format used\n- Regenerated client docs

The template uses {{#each installation.deeplink}} which requires an array. Changed Cursor and Goose deeplink objects to single-element arrays to match VS Code's structure and enable button rendering.

Per Greg's code review feedback on PR #179: - Move packages/mcp-server-supabase/docs/clients.ts to src/clients.ts - Add export path './clients' in package.json - Add src/clients.ts to tsup entry points for building - Update imports to use @supabase/mcp-server-supabase/clients - Remove empty docs/ directory from package This creates a clean package subpath export that external consumers can use to import client definitions without reaching into internals.

Per Greg's code review feedback on PR #179: - Move clients.ts to src/integrations/ directory - Create integrations/index.ts as the export entry point - Add package.json subpath export: @supabase/mcp-server-supabase/integrations - Update tsup config to build integrations/index.ts - Update imports throughout to use the new integrations path - Remove old docs/ directory from package This mirrors the pattern used for platform exports and provides a clean, documented way for external projects to import client metadata.

Fix workflow to reference packages/mcp-server-supabase/src/integrations/clients.ts instead of the old docs/clients.ts path

- Add build step before type checking so dist/ types are available - Change Handlebars import to namespace import for better TS compatibility

- Change docs/clients/constants.ts to use relative path import - Remove build step from workflow since we don't need dist/ types - This avoids circular dependency issues during development

github-actions · 2025-11-13T19:48:38Z

✅ Client documentation validated. No changes needed.

gregnr · 2025-11-13T20:30:43Z

+The client metadata is defined in `packages/mcp-server-supabase/src/integrations/clients.ts` and exported from the `@supabase/mcp-server-supabase/integrations` subpath. This allows:
+
+- **Documentation generation**: This repo's scripts import the data to generate docs
+- **External integrations**: Other Node.js projects can import client metadata from the published package using `import { clients } from '@supabase/mcp-server-supabase/integrations'`


Suggested change

- **External integrations**: Other Node.js projects can import client metadata from the published package using `import { clients } from '@supabase/mcp-server-supabase/integrations'`

- **External integrations**: Other JS projects can import client metadata from the published package using `import { clients } from '@supabase/mcp-server-supabase/integrations'`

gregnr · 2025-11-13T20:31:34Z

+
+1. Open `packages/mcp-server-supabase/src/integrations/clients.ts`
+2. Add a new client object to the `clients` array following the `Client` interface
+3. Run `npm run docs:generate-clients` to generate documentation


Suggested change

3. Run `npm run docs:generate-clients` to generate documentation

3. Run `pnpm docs:generate-clients` to generate documentation

gregnr

I assume you have reviewed these already, but this is where this logic lives in the current URL builder. Worth double checking that our schema supports everything they will need there if the goal is for URL builder to import client info from this.

gregnr · 2025-11-13T20:33:06Z

+## Future Enhancements
+
+This data structure can be published as an npm package (e.g., `@supabase/mcp-clients-registry`) to share client metadata with the Supabase documentation website and other tools.


No longer relevant?

gregnr · 2025-11-13T20:33:35Z

+The `_template.md` file uses Handlebars-style syntax:
+
+- `{{variable}}` - Variable substitution
+- `{{#if condition}}...{{/if}}` - Conditional blocks
+- `{{#if condition}}...{{else if condition2}}...{{else}}...{{/if}}` - Else-if chains
+- `{{#each array}}...{{/each}}` - Loop over arrays
+- `{{#unless condition}}...{{/unless}}` - Negative conditional
+- `{{@last}}` - Special variable in loops (true for last item)
+- `(eq a b)` - Helper function for equality comparison


Out of date? Reference handlebars docs?

gregnr · 2025-11-13T20:37:00Z

@@ -0,0 +1,111 @@
+import { readFileSync, writeFileSync } from 'node:fs';


nit: use node:fs/promises import and make these async

gregnr · 2025-11-13T20:38:07Z

+    // Optionally write individual client markdown files
+    const clientDocPath = join(
+      process.cwd(),
+      'docs/clients',
+      `${client.id}.md`
+    );
+    writeFileSync(clientDocPath, content, 'utf-8');
+    console.log(`   Wrote ${client.id}.md`);


What is the benefit to this?

gregnr · 2025-11-13T20:39:36Z

+  }
+
+  // Update README.md
+  console.log('\nUpdating README.md...');


Are these \n prefixes intentional?

gregnr · 2025-11-13T20:41:29Z

+### Generating Documentation
+
+After adding or modifying a client, regenerate the documentation:
+
+```bash
+npm run docs:generate-clients
+```
+
+This will:
+1. Read `constants.ts`
+2. Type-check the TypeScript file
+3. Generate individual `{client-id}.md` files from the template
+4. Update the client documentation section in `README.md`
+5. Format all files with Biome
+
+## Client Data Schema
+
+The schema is defined as TypeScript interfaces in `constants.ts`:
+
+```typescript
+interface Client {
+  id: string;                    // Unique identifier (lowercase-kebab-case)
+  name: string;                  // Display name
+  description?: string;          // Short description
+  officialDocs?: string;         // URL to official MCP documentation
+  installation: {
+    deeplink?: {                 // One-click installation button
+      url: string;
+      buttonImage: string;
+      buttonAlt: string;
+    } | Array<...>;              // Can be single or array for multiple buttons
+    command?: {                  // CLI installation
+      command: string;
+      description?: string;
+    };
+    manual: {                    // Manual config (always required)
+      configFilePath: string;
+      configFormat: "mcpServers" | "servers";
+    };
+  };
+  registry?: {                   // Registry listing info
+    listed: boolean;
+    listingUrl?: string;
+  };
+}
+```
+
+TypeScript provides compile-time validation, so any schema errors will be caught before generating documentation.


Might be just me but a lot of these docs feel duplicated and verbose. Embedding the schema makes it harder to maintain later if we need to update it. Worth keeping this doc minimal?

gregnr · 2025-11-13T20:44:06Z

+# Generated client documentation (keep _template.md and clients.json)
+docs/clients/*.md


If this already lives in the main README is there much benefit to including these?

gregnr · 2025-11-13T20:46:42Z

+ * Update README.md with generated client documentation
+ */
+function updateReadme(clients: Client[], generatedDocs: string[]): void {
+  const readmePath = join(process.cwd(), 'README.md');


nit: use import.meta.resolve to find the README.md relative to this file so that it doesn't matter which CWD the user is in

gregnr · 2025-11-13T20:48:23Z

+/**
+ * List of all MCP clients that support the Supabase MCP server
+ */
+export const clients: Client[] = [


Are we intentionally omitting Windsurf (which is currently listed in our docs)?

Not intentionally but I haven't yet tried Windsurf out. Mainly because on our documentation, we have that they don't support remote, which according with their documentation, seems to be outdated

I plan to add support for Windsurf and Codex on this PR and then we should be good to go

github-actions · 2025-11-14T12:17:18Z

✅ Client documentation validated. No changes needed.

Rodriguespn · 2025-11-17T15:45:55Z

After internal deliberation, we've decided to keep a single source of truth about how to configure the Supabase MCP server for different clients on our docs page. I've opened supabase/supabase#40525 with the client configurations there instead. Thanks for the discussion and exploration on this approach!

Rodriguespn added 2 commits November 13, 2025 13:19

first draft

8da5b87

add github workflows

dc4eef8

Rodriguespn requested a review from mattrossman November 13, 2025 13:33

Rodriguespn self-assigned this Nov 13, 2025

fix: update Cursor config file path to .cursor/mcp.json

0fb1c48

refactor: simplify schema by removing instructions property

14fe709

Use configFilePath directly in template to generate consistent instructions

test

a4a647c

Rodriguespn force-pushed the ai-274-automate-mcp-client-docs branch from a654128 to a4a647c Compare November 13, 2025 15:37

Rodriguespn added 3 commits November 13, 2025 15:43

Add Claude Code client installation instructions

6f87eac

Added Claude Code as a supported MCP client with: - CLI installation command - Manual configuration instructions - OAuth authentication flow guidance

fix types file path

0b48f44

gregnr reviewed Nov 13, 2025

View reviewed changes

Comment thread docs/scripts/generate-clients.ts Outdated

Comment thread docs/scripts/generate-clients.ts Outdated

Comment thread packages/mcp-server-supabase/tsconfig.json

Rodriguespn added 7 commits November 13, 2025 16:31

Support custom YAML manual config and add Goose manualSnippet\n\n- Ad…

f40f234

…ded manualSnippet to ManualConfig\n- Updated Goose client with YAML configuration snippet and new button image\n- Updated template to render YAML when custom format used\n- Regenerated client docs

Fix Cursor and Goose deeplink buttons by wrapping in arrays

ad3fc33

The template uses {{#each installation.deeplink}} which requires an array. Changed Cursor and Goose deeplink objects to single-element arrays to match VS Code's structure and enable button rendering.

Update GitHub workflow to use new integrations path

413dd04

Fix workflow to reference packages/mcp-server-supabase/src/integrations/clients.ts instead of the old docs/clients.ts path

Fix GitHub workflow: build package and fix Handlebars import

6fa47b6

- Add build step before type checking so dist/ types are available - Change Handlebars import to namespace import for better TS compatibility

Use relative imports instead of package imports in docs

a037245

- Change docs/clients/constants.ts to use relative path import - Remove build step from workflow since we don't need dist/ types - This avoids circular dependency issues during development

Rodriguespn requested a review from gregnr November 13, 2025 19:56

gregnr reviewed Nov 13, 2025

View reviewed changes

reusable way of generating clients on this repo

c3d08f3

Rodriguespn closed this Nov 17, 2025

	- External integrations: Other Node.js projects can import client metadata from the published package using `import { clients } from '@supabase/mcp-server-supabase/integrations'`
	- External integrations: Other JS projects can import client metadata from the published package using `import { clients } from '@supabase/mcp-server-supabase/integrations'`

	3. Run `npm run docs:generate-clients` to generate documentation
	3. Run `pnpm docs:generate-clients` to generate documentation

		## Future Enhancements

		This data structure can be published as an npm package (e.g., `@supabase/mcp-clients-registry`) to share client metadata with the Supabase documentation website and other tools.

		@@ -0,0 +1,111 @@
		import { readFileSync, writeFileSync } from 'node:fs';

		# Generated client documentation (keep _template.md and clients.json)
		docs/clients/*.md

Uh oh!

Conversation

Rodriguespn commented Nov 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Automate MCP Client Documentation

Overview

Changes

Existing Client Configs

New Client Configs

Testing

Uh oh!

github-actions Bot commented Nov 13, 2025

Uh oh!

github-actions Bot commented Nov 13, 2025

Uh oh!

github-actions Bot commented Nov 13, 2025

Uh oh!

github-actions Bot commented Nov 13, 2025

Uh oh!

github-actions Bot commented Nov 13, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Nov 13, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gregnr left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Nov 14, 2025

Uh oh!

Rodriguespn commented Nov 17, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Rodriguespn commented Nov 13, 2025 •

edited

Loading