Feature Request: Consolidated Database Schema Documentation Tool

[hasithasandunlakshan]

Feature request: Consolidated Database Schema Documentation Tool

Is your feature request related to a problem? Please describe.

Currently, when an AI agent (or a new developer) wants to understand the structure of a Supabase project via MCP, it must call multiple tools like list_tables and list_extensions and then piece together the schema manually. This is inefficient in terms of token usage and context window consumption for LLMs. Furthermore, critical details like Row Level Security (RLS) policies, database triggers, and custom SQL functions are not easily accessible through a single high-level overview, making it difficult to extract a comprehensive snapshot for documentation or onboarding.

Describe the solution you'd like

I propose adding a new read-only tool called generate_schema_docs. This tool consolidates data from PostgreSQL system catalogs into a single, structured response.

Key capabilities:

• Consolidated Schema: Fetches Tables, Columns, Foreign Keys, RLS Policies, Triggers, and Functions in one request.
• Dual Format Output: Returns both a human-readable Markdown summary (perfect for generating DATABASE.md files) and structured JSON data (perfect for AI agent reasoning).
• Nested Visibility: In the Markdown output, RLS policies and Triggers are displayed directly under their respective tables for better context.
• Configurable: Allows filtering by specific schemas and toggling the inclusion of internal/system functions.

Describe alternatives you've considered

The current alternative is relying purely on list_tables (verbose: true). However, this captures only table structures and misses:

1. RLS Policies: Crucial for security auditing.
2. Triggers: Essential for understanding side-effects and business logic.
3. Custom Functions: Where complex database-level logic often resides.

Manual JSON-to-Markdown formatting by an LLM is token-expensive and often misses these deeper architectural details.

Additional context

Implementation Status:
I have successfully implemented this tool locally within the database feature group.

• Implemented in PR feat: add generate_schema_docs tool for database documentation #278
• Tool Name: generate_schema_docs
• Location: packages/mcp-server-supabase/src/tools/database-docs-tools.ts
• Tests: Full test coverage added to server.test.ts (including format variants and edge cases). All 172 unit tests are passing.
• Safety: This is a strictly read-only operation (readOnlyHint: true).

This tool acts as a practical bridge for "Self-Documenting Databases" and empowers developers to instantly generate project-specific schema documentation for onboarding or LLM context initialization.

[gregnr]

Thanks for the issue and PR @hasithasandunlakshan! We've had similar discussions about expanding the tools to support more than just list_tables and list_extensions. Some of the nuances to consider are:

1. Token usage. If we offer a single tool that fetches all Postgres objects (tables, columns, views, policies, triggers, functions, etc), we're very likely returning more information than the agent needs in that moment. Depending on the structure of the user's database, this could eat up a lot of tokens.
2. Tool count. Alternatively we could just add a bunch of tools like list_views, list_triggers, list_functions, etc. But many agents max out on number of tools they support. As a general principle, less tools is better.
3. It's already possible. Technically the agent can already gather exactly what it needs (views, triggers, functions, etc) using execute_sql via information_schema or pg_catalog. But since this is such a common task, it'd be better if this was presented as a first-class operation somehow vs assuming the agents knows what to fetch and how to fetch it.

Give us some time to review your PR and I'll follow up. From initial glances, the current approach may land under the first concern above, but I'll confirm. In an ideal world, the final solution is dynamic like the third point, but still feels first-class.

[hasithasandunlakshan]

• Thank you @gregnr for your feedback