RAG-chunk – A CLI to test RAG chunking strategies vs Supabase

Implements and executes multiple text chunking strategies (fixed-size, semantic, recursive, sliding-window) against the same input document, allowing side-by-side comparison of how different chunking approaches segment content. The CLI loads documents, applies each strategy with configurable parameters, and outputs the resulting chunks for analysis. This enables developers to empirically evaluate which chunking strategy produces optimal retrieval performance for their specific RAG use case before deploying to production.

Unique: Provides a dedicated CLI tool specifically for iterative chunking strategy testing rather than embedding chunking as a library function, enabling rapid experimentation with visual output and parameter tuning without code changes

vs alternatives: Faster experimentation cycle than implementing chunking strategies directly in Python/Node.js code, and more focused than general RAG frameworks that treat chunking as a single configuration option

Exposes chunking algorithm parameters (chunk size, overlap percentage, separator patterns, semantic similarity thresholds) as CLI flags or configuration files, allowing users to adjust strategy behavior without modifying source code. The tool parses configuration inputs, validates parameter ranges, and applies them to each chunking strategy execution. This enables rapid iteration on parameter values to optimize for specific document types, languages, or retrieval objectives.

Unique: Provides CLI-first parameter configuration with real-time feedback on chunking results, enabling non-engineers to experiment with parameters through simple flag-based interfaces rather than code modification

vs alternatives: More accessible than Python notebooks for parameter tuning, and faster iteration than modifying configuration in application code

Retains and propagates document metadata (source file, line numbers, section headers, document structure) through the chunking process, attaching this context to each output chunk. The implementation tracks chunk origins and relationships, enabling downstream retrieval systems to maintain document context and enable features like source attribution and hierarchical retrieval. Metadata is output alongside chunks in structured formats (JSON with metadata fields).

Unique: Explicitly preserves and outputs metadata alongside chunks rather than discarding it, enabling full traceability from retrieved chunks back to source documents and enabling hierarchical retrieval patterns

vs alternatives: More transparent than black-box chunking that loses source context, and enables better user experience through source attribution compared to chunking strategies that discard metadata

Processes multiple documents in a single CLI invocation, applying selected chunking strategies to each document and exporting results in bulk to files or structured formats. The tool handles directory traversal, file format detection, and batch output organization (e.g., one output file per input document, or consolidated output). This enables efficient processing of document collections without manual iteration or scripting.

Unique: Provides dedicated batch processing mode with directory-aware input/output handling, enabling RAG practitioners to process document collections without writing custom scripts or orchestration code

vs alternatives: Faster than writing Python scripts for batch chunking, and more ergonomic than invoking the tool repeatedly for each document

Displays chunking results in a human-readable format (CLI output, formatted tables, or interactive preview) showing how each strategy segments the input document, with visual indicators for chunk boundaries, overlap regions, and metadata. The implementation formats chunks with context (surrounding text, chunk indices) and may support interactive navigation through large chunk sets. This enables developers to visually inspect chunking quality and understand strategy behavior without parsing raw output.

Unique: Provides built-in visualization of chunking results directly in the CLI rather than requiring external tools or manual inspection of raw output, making chunking behavior immediately transparent

vs alternatives: More accessible than parsing JSON output manually, and faster feedback loop than exporting to external visualization tools

Implements semantic chunking by computing embeddings for text segments and grouping segments with high semantic similarity into chunks, rather than relying on fixed sizes or delimiters. The tool integrates with embedding models (local or API-based) to compute similarity scores and uses threshold-based or clustering algorithms to determine chunk boundaries. This produces chunks that are semantically coherent rather than arbitrary size-based splits, improving retrieval quality for RAG systems.

Unique: Provides semantic chunking as a first-class strategy alongside fixed-size and recursive approaches, with configurable embedding models and similarity thresholds, enabling empirical comparison of semantic vs. structural chunking

vs alternatives: Produces more semantically coherent chunks than fixed-size strategies, improving retrieval quality for embedding-based RAG systems

Implements recursive chunking that attempts to split documents using a hierarchy of delimiters (e.g., paragraphs → sentences → words) and falls back to smaller units if chunks exceed size limits. The algorithm respects document structure by preferring semantic boundaries (paragraph breaks) over arbitrary splits, and recursively applies the strategy until all chunks meet size constraints. This balances semantic coherence with size requirements, producing chunks that preserve document structure while meeting retrieval constraints.

Unique: Implements recursive chunking with explicit fallback hierarchy and structure preservation, enabling intelligent splitting that respects document semantics while enforcing size constraints

vs alternatives: Better than fixed-size chunking for structured documents, and more predictable than pure semantic chunking while maintaining semantic coherence

Implements sliding-window chunking where a fixed-size window moves across the document with a configurable stride (step size), creating overlapping chunks. The tool allows tuning of window size and stride independently, enabling control over chunk overlap percentage and granularity. This produces dense, overlapping chunks useful for retrieval systems where context around query terms is important, and enables fine-grained control over coverage and redundancy.

Unique: Provides explicit sliding-window implementation with independent control of window size and stride, enabling fine-grained tuning of chunk overlap and coverage without code modification

vs alternatives: More flexible than fixed-size chunking for controlling overlap, and simpler to tune than semantic chunking while providing predictable chunk sizes

Executes SQL queries against Supabase PostgreSQL instances through the Model Context Protocol, translating natural language or structured query requests into parameterized SQL statements. Uses MCP's tool-calling interface to expose database operations as callable functions with schema validation, enabling LLM agents to perform CRUD operations, joins, and aggregations with automatic connection pooling and credential management through Supabase client SDK.

Unique: Exposes Supabase PostgreSQL as MCP tools with automatic credential injection from Supabase client SDK, eliminating manual connection string management and enabling seamless LLM-to-database queries within Claude or compatible agents

vs alternatives: Tighter integration than generic SQL MCP servers because it leverages Supabase's built-in authentication and connection pooling rather than requiring separate database credential configuration

Exposes Supabase Auth session state and user metadata through MCP tools, allowing agents to inspect current authentication context, retrieve user profiles, and trigger auth-related operations. Integrates with Supabase's JWT-based auth system to validate sessions and access user claims without re-authenticating, using the Supabase client's built-in session management.

Unique: Integrates Supabase's JWT-based auth system directly into MCP tool interface, allowing agents to inspect and act on auth state without managing separate credential stores or re-authentication flows

vs alternatives: More seamless than generic auth MCP servers because it leverages Supabase's built-in session management and avoids redundant credential passing between agent and auth system

Invokes Supabase Edge Functions (serverless TypeScript/JavaScript functions) through MCP tools, passing parameters and receiving results with optional streaming support. Uses Supabase's edge function HTTP API to trigger functions with automatic authentication headers and response parsing, enabling agents to execute custom business logic without embedding it in the agent itself.

Unique: Exposes Supabase Edge Functions as MCP tools with automatic authentication and response parsing, allowing agents to invoke custom serverless logic without managing HTTP clients or credential injection

vs alternatives: More integrated than generic HTTP MCP tools because it handles Supabase-specific authentication, error handling, and response formatting automatically

Subscribes to real-time changes on Supabase tables through MCP's event streaming interface, using Supabase's PostgreSQL LISTEN/NOTIFY mechanism to push INSERT, UPDATE, and DELETE events to agents. Maintains persistent WebSocket connections and filters events by table and row-level policies, enabling agents to react to database changes without polling.

Unique: Bridges Supabase's PostgreSQL LISTEN/NOTIFY real-time system with MCP's tool interface, enabling agents to subscribe to database changes without managing WebSocket connections or event serialization

vs alternatives: More efficient than polling-based approaches because it uses Supabase's native real-time infrastructure rather than repeated database queries

Manages files in Supabase Storage buckets through MCP tools, supporting upload, download, list, and delete operations with automatic authentication and path-based access control. Uses Supabase's S3-compatible storage API with built-in support for public/private buckets and signed URLs for temporary access, enabling agents to handle file I/O without managing cloud storage credentials.

Unique: Exposes Supabase Storage's S3-compatible API as MCP tools with automatic authentication and signed URL generation, eliminating the need for agents to manage cloud storage credentials or generate temporary access tokens

vs alternatives: More integrated than generic S3 MCP tools because it leverages Supabase's built-in bucket policies and authentication rather than requiring separate AWS credentials

Performs semantic similarity searches on vector embeddings stored in Supabase PostgreSQL using pgvector extension, translating natural language queries into embedding vectors and executing cosine/L2 distance searches. Integrates with embedding providers (OpenAI, Cohere) or uses pre-computed embeddings, enabling agents to retrieve semantically similar documents or records without full-text search limitations.

Unique: Integrates pgvector directly into MCP tools with automatic embedding generation and distance calculation, enabling agents to perform semantic search without managing separate vector database infrastructure

vs alternatives: More efficient than external vector databases (Pinecone, Weaviate) for Supabase users because it colocates embeddings with relational data, reducing network latency and simplifying data synchronization

Exposes Supabase database schema information through MCP tools, allowing agents to discover table structures, column types, constraints, and relationships without manual schema documentation. Queries PostgreSQL information_schema and Supabase metadata tables to dynamically generate schema descriptions, enabling agents to construct valid queries and understand data relationships.

Unique: Queries Supabase's PostgreSQL information_schema directly through MCP tools, enabling agents to dynamically discover and adapt to database schemas without pre-configured schema definitions

vs alternatives: More flexible than static schema definitions because it reflects live database state, including recent migrations or schema changes

Enforces Supabase Row-Level Security policies within agent queries, ensuring that agents can only access rows permitted by RLS rules defined in the database. Evaluates policies based on authenticated user context (JWT claims, user ID) and applies WHERE clause filters automatically, preventing unauthorized data access at the database layer rather than application layer.

Unique: Delegates authorization enforcement to PostgreSQL RLS policies rather than implementing authorization in agent code, ensuring that data access rules are centralized and cannot be bypassed by agent logic

vs alternatives: More secure than application-level authorization because RLS is enforced at the database layer, preventing accidental data leaks even if agent code has bugs