MCP Vector Sync

🚀 MCP Vector Synchronization Service

This is an event-based, multi-tenant real-time vector search automatic synchronization service. It uses Supabase for data storage and leverages OpenAI to provide vector generation capabilities.

🚀 Quick Start

Prerequisites

• Node.js >= 18
• A Supabase database with proyectos and proyecto_vector tables
• An OpenAI API Key
• Docker installed (for deployment)

Local Development

1. Install dependencies:

npm install

2. Create and edit the .env file, including all necessary environment variables.
3. Start the development mode:

npm run dev

Docker Deployment

Build and run the service using Docker:

# Build the image
docker build -t mcp-vector-sync .

# Start the container
docker run -p 3000:3000 --env-file .env mcp-vector-sync

Or use Docker Compose:

docker-compose up

Railway Deployment

1. Push the code to a GitHub repository.
2. Configure the project, selecting the appropriate runtime environment and dependency management tool (e.g., Yarn).
3. Set the necessary environment variables as prompted.

✨ Features

• Fully Event-Driven: Receives real-time webhook notifications directly from Supabase.
• OpenAI Vector Generation: Utilizes the OpenAI API to generate text embeddings.
• Real-Time Project Change Handling: Responds immediately to project creation or update operations.
• Automatic Retry Mechanism: Employs an exponential backoff algorithm with a maximum of 3 retries.
• Audit Logging: Records all operations in detail for troubleshooting and monitoring.
• Multi-Tenant Support: Ensures complete data isolation.
• MCP Protocol Support: Provides access to synchronization tools and resources via the MCP protocol.
• Health Check Server Endpoint: Used for service status monitoring.
• Docker Containerization: Facilitates rapid deployment.
• Railway Compatibility: Supports deployment on the Railway platform.

🔧 Technical Details

Event Architecture

The system is designed with an event-based architecture:

1. Supabase Triggers: When a project is created or updated, the trigger sends webhooks to the server.
2. Insertion Delay Control: Applies a 20-second delay after a new record is inserted to avoid race conditions.
3. Automatic Retry Mechanism: Automatically retries on errors, with a maximum of 3 retries using an exponential backoff strategy (2, 4, 8 seconds).
4. Audit Logs: All operations are recorded in the webhook_logs table for easy debugging and monitoring.

Configuration Parameters

The service is configured through environment variables:

# Supabase Configuration
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key

# OpenAI Configuration
OPENAI_API_KEY=Your OpenAI API Key
OPENAI_MODEL=text-embedding-ada-002

# Rate Limiting Configuration
RATE_LIMIT_PER_TENANT=100
CONCURRENT_REQUESTS=5

# Logging
LOG_LEVEL=info

💻 Usage Examples

Webhook Data Format

{
  "event": "sync_project",
  "data": {
    "tenant_id": "string",
    "project_id": "string",
    "timestamp": "2025-03-22T17:45:00Z"
  }
}

MCP Tools

The service provides the following MCP tools:

• sync-tenant: Forces data synchronization for a specified tenant.
• get-sync-status: Retrieves the synchronization status of a tenant.
• control-monitor: Starts or stops the synchronization monitoring service.

📚 Documentation

Troubleshooting

• OpenAI Errors: Check if the OpenAI API Key is valid.
• Supabase Connection Issues: Confirm the correctness of the URL and service key.
• Webhook Issues: Check the logs in the webhook_logs table.
• Detailed Logs: Set LOG_LEVEL=debug to get more information.

Maintenance and Updates

1. Submit changes in the code repository.
2. Update the version number in package.json.
3. Push the changes to the GitHub repository, and the Railway platform will automatically detect and redeploy.

Security Considerations

• Avoid embedding sensitive information such as API keys directly in the code.
• Use environment variables to manage all configuration information.
• Ensure that the Supabase service key has minimal permissions.
• It is recommended to add authentication to the Webhook interface in a production environment.
• Enable rate limiting to prevent denial-of-service attacks.