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.