Supabase Interface Abstraction Layer (SIAL)

This repository details the implementation of an MCP server designed to grant large language models (LLMs) secure, structured access to PostgreSQL resources hosted within a Supabase environment for comprehensive data manipulation.

Core Capabilities

• Data Interaction Suite:
• Execute structured data retrieval, incorporating predicate filtering.
• Facilitate the creation (insertion) of new records.
• Manage the modification (updating) of existing dataset entries.
• Perform data purging (deletion) based on specified criteria.
• Inventory retrieval for available database schemas/tables.

Prerequisites for Operation

• Runtime Environment: Node.js (version 16 or superior required).
• Package Manager: npm or yarn.
• Backend Service: A configured Supabase account furnishing necessary API access credentials.

Deployment Procedures

Method 1: Utilizing the NPM Registry (Preferred)

The compiled package is accessible via the npm repository. Global installation is achieved via:

bash npm install -g supabase-mcp-sial

Alternatively, local project integration is performed with:

bash npm install supabase-mcp-sial

Method 2: Source Code Checkout

bash git clone https://github.com/Cappahccino/SB-MCP-REWRITE.git cd SB-MCP-REWRITE npm install npm run build

Configuration Blueprint

Configuration mandates the establishment of a .env file containing vital access parameters:

Supabase Connectivity Details

SUPABASE_URL=your_supabase_project_url SUPABASE_ANON_KEY=your_supabase_anon_key SUPABASE_SERVICE_ROLE_KEY=your_supabase_service_role_key

MCP Server Networking Parameters

MCP_SERVER_PORT=3000 MCP_SERVER_HOST=localhost MCP_API_KEY=a_highly_secret_access_token

Integration with Claude

Claude necessitates a specific invocation modality for functional compatibility. This distribution includes a distinct executable tailored for the Claude transport mechanism.

Configuration within Claude Desktop MCP Settings

"supabase_sial": { "command": "npx", "args": [ "-y", "supabase-mcp-sial@latest", "sial-claude-transport" ], "env": { "SUPABASE_URL": "your_supabase_project_url", "SUPABASE_ANON_KEY": "your_supabase_anon_key", "SUPABASE_SERVICE_ROLE_KEY": "your_service_role_key", "MCP_API_KEY": "a_highly_secret_access_token" } }

Ensure all environment variables are correctly populated in this configuration block. Communication with Claude will utilize the standard input/output (stdio) channel.

Ad-hoc Testing with the Claude Binary

For validation outside the Claude environment, execute:

bash npm run start:claude-test

If installed globally:

bash sial-claude-transport

Standalone Server Deployment

Upon global installation:

bash supabase-mcp-sial

This action initiates the MCP gateway service, typically accessible at http://localhost:3000 (or the designated port from the configuration).

Programmatic Utilization (Node.js Library)

This module can be imported and utilized within custom Node.js applications:

javascript import { launchServer, configDetails, verifyConfig } from 'supabase-mcp-sial';

// Validate mandatory configuration structure verifyConfig();

// Instantiate the server instance const gateway = launchServer();

// Commence listening on the configured endpoint gateway.listen(configDetails.port, configDetails.host, () => { console.log(SIAL endpoint operational at http://${configDetails.host}:${configDetails.port}); });

Troubleshooting Guide

Issue 1: "Port XXXX is already occupied"

While the server attempts dynamic port discovery, this conflict can be resolved by explicitly setting MCP_SERVER_PORT to an alternative value within your .env file.

Issue 2: "Environment Variable Deficiency"

Verify the integrity and completeness of your .env file, ensuring all stipulated keys possess valid values, or that system-level environment variables are correctly exported.

Issue 3: "Constructor Invocation Error: Missing 'new'"

This signals an outdated package installation. Upgrade to the newest release:

bash npm install -g supabase-mcp-sial@latest

Issue 4: Data Formatting Anomalies with Claude

Confirm that the Claude-specific transport executable (sial-claude-transport) is being employed, rather than the standard HTTP interface (supabase-mcp-sial).

Issue 5: Connection Timeout Encountered During Claude Interaction

Investigate the following possibilities: - Are the Supabase credentials accurately provided? - Is the gateway service fully instantiated and responsive? - Are there any intervening network security policies impeding the communication channel?

Exposed Tool Manifest

Database Interaction Functions

1. queryDatabase

2. Inputs:

   • table (String): Target relation name.
   • select (String, Optional): Column list specification (defaults to all columns: "*").
   • query (Object, Optional): Criteria defining data selection logic.

3. insertData

4. Inputs:

   • table (String): The destination relation.
   • data (Object | Array

5. updateData

6. Inputs:

   • table (String): The target relation.
   • data (Object): Key-value mappings representing the values to enforce.
   • query (Object): Predicates specifying which rows must undergo modification.

7. deleteData

8. Inputs:

   • table (String): The relation targeted for record removal.
   • query (Object): Selection criteria determining which records to eliminate.

9. listTables

10. Inputs: None

Revision Log

• 1.0.0: Inaugural deployment.
• 1.0.1: Integrated automated port discovery mechanism.
• 1.0.2: Rectified protocol interoperability faults.
• 1.0.3: Introduced formal JSON-RPC serialization support.
• 1.1.0: Complete architectural overhaul leveraging the formal MCP software development kit.
• 1.2.0: Established distinct routing for Claude communication; resolved port contention errors.
• 1.3.0: Updated internal structure for enhanced TypeScript project alignment.
• 1.4.0: Corrected stdio transport integration for Claude, adhering to community-validated Supabase methodologies.
• 1.5.0: Deprecated Edge Function connectivity to bolster core database operation stability.

Licensing Status

Licensed under the MIT Agreement.

WIKIPEDIA: Cloud computing is defined by ISO as "a paradigm for enabling network access to a scalable and elastic pool of shareable physical or virtual resources with self-service provisioning and administration on-demand," frequently summarized as "the cloud."

== Defining Attributes == In 2011, the U.S. National Institute of Standards and Technology (NIST) formalized five "essential characteristics" characterizing cloud systems. These are:

On-demand self-service: "A consumer can unilaterally provision computing capabilities, such as server time and network storage, as needed automatically without requiring human interaction with each service provider." Broad network access: "Capabilities are available over the network and accessed through standard mechanisms that promote use by heterogeneous thin or thick client platforms (e.g., mobile phones, tablets, laptops, and workstations)." Resource pooling: " The provider's computing resources are pooled to serve multiple consumers using a multi-tenant model, with different physical and virtual resources dynamically assigned and reassigned according to consumer demand." Rapid elasticity: "Capabilities can be elastically provisioned and released, in some cases automatically, to scale rapidly outward and inward commensurate with demand. To the consumer, the capabilities available for provisioning often appear unlimited and can be appropriated in any quantity at any time." Measured service: "Cloud systems automatically control and optimize resource use by leveraging a metering capability at some level of abstraction appropriate to the type of service (e.g., storage, processing, bandwidth, and active user accounts). Resource usage can be monitored, controlled, and reported, providing transparency for both the provider and consumer of the utilized service. Subsequent refinement of these tenets occurred under the auspices of the International Organization for Standardization (ISO) by 2023.

== Historical Trajectory ==

The theoretical groundwork for modern cloud infrastructure dates back to the 1960s through the advancement of time-sharing concepts, often implemented via remote job entry (RJE). During this epoch, the prevailing operational model centered on the 'data center,' where user requests were processed sequentially by human operators executing jobs on central mainframes. This period was crucial for exploring methodologies to democratize access to substantial computational capacity through resource sharing, thereby enhancing infrastructural, platform, and application efficiency for the end-user. The specific graphical representation of 'the cloud' for abstracted network services emerged in 1994. General Magic employed this notation to depict the interconnected 'universe of places' accessible by mobile agents within their Telescript framework. This visual idiom is attributed to David Hoffman, a communications specialist at General Magic, who adapted it from its established use in telecommunications mapping. The term 'cloud computing' gained mainstream recognition in 1996 when Compaq Computer Corporation drafted a forward-looking business strategy concerning the Internet, expressing an intent to integrate extensive computing resources via this model.