# 🌌 STRATA — Universal Context Bridge

[![Model Context Protocol](https://img.shields.io/badge/MCP-v2.0-blue.svg)](https://modelcontextprotocol.io)
[![Python](https://img.shields.io/badge/Python-3.10%2B-green.svg)](https://python.org)
[![Supabase](https://img.shields.io/badge/Database-Supabase%20%2B%20pgvector-emerald.svg)](https://supabase.com)
[![License](https://img.shields.io/badge/License-MIT-purple.svg)](LICENSE)

**STRATA** is a high-performance [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that serves as a **Universal Context Bridge** for AI assistants and LLM agents (Claude Desktop, Cursor, Continue.dev, ChatGPT, etc.).

It gives AI models persistent memory across conversations and coding sessions, backed by **Supabase PostgreSQL**, full-text indexing, and **pgvector** semantic search.

---

## ⚡ Features

- 🧠 **Persistent Context Memory**: AI agents can save decisions, design systems, API contracts, preferences, and code snippets across sessions.
- 🔍 **Intelligent Memory Search**: Fast full-text and contextual search with automatic recency fallbacks.
- 🚀 **Modern MCP 2.0 SDK**: Built using the latest `MCPServer` decorator architecture with Server-Sent Events (SSE) streaming transport.
- 🗄️ **Supabase & PostgreSQL**: Battle-tested cloud database layer with pgvector support and Row-Level Security (RLS).
- 🔄 **Singleton Connection Pooling**: Cached client instances for high-throughput, low-latency tool execution.
- 🩺 **Built-in Health Checks**: REST endpoints for uptime monitoring and connectivity status (`/health`).

---

## 🛠️ Available MCP Tools

| Tool | Description | Parameters |
|---|---|---|
| `save_memory` | Save context, preferences, decisions, or code into long-term memory | `content` (str), `title` (opt), `tags` (opt) |
| `search_memory` | Search past context and discussions matching keywords or queries | `query` (str), `limit` (int, default: 5) |
| `list_memories` | List recent context entries stored in STRATA | `limit` (int, default: 10) |
| `delete_memory` | Remove a specific memory entry by UUID | `memory_id` (str) |
| `get_stats` | View database connection status, memory count, and metadata | *None* |

---

## 🚀 Quick Start

### 1. Prerequisites
- Python 3.10 or higher
- A [Supabase](https://supabase.com) account & project

### 2. Clone & Setup Environment

```bash
# Clone the repository
git clone https://github.com/your-username/STRATA.git
cd STRATA

# Copy environment file and configure your keys
cp .env.example .env
```

Edit `.env` with your Supabase credentials:
```env
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_KEY=your-supabase-service-role-key
DEFAULT_USER_ID=your-user-uuid (optional)
```

### 3. Install Dependencies

```bash
cd apps/api
python -m venv venv

# Activate virtual environment:
# Windows (PowerShell):
.\venv\Scripts\Activate.ps1
# macOS / Linux:
source venv/bin/activate

# Install requirements
pip install -r requirements.txt
```

### 4. Database Setup

Run the SQL schema located in [`supabase_schema.sql`](./supabase_schema.sql) in your **Supabase SQL Editor** to initialize the tables, vector extensions, and full-text indexes.

### 5. Start the Server

```bash
# From apps/api directory:
uvicorn main:app --reload --port 8000
```

The server starts on `http://localhost:8000` with the following endpoints:
- **SSE Endpoint**: `http://localhost:8000/sse`
- **Messages Endpoint**: `http://localhost:8000/messages/`
- **Health Check**: `http://localhost:8000/health`

---

## 🔌 Connecting to MCP Clients

### Claude Desktop
Add this to your `claude_desktop_config.json`:
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "strata": {
      "url": "http://localhost:8000/sse"
    }
  }
}
```

### Cursor IDE
In Cursor settings under **Features > MCP Servers**, add a new server:
- **Name**: `STRATA`
- **Type**: `sse`
- **URL**: `http://localhost:8000/sse`

---

## 📁 Project Structure

```
STRATA/
├── apps/
│   └── api/                   # Python MCP Server
│       ├── main.py            # Server logic, MCPServer instance & tools
│       ├── requirements.txt   # Python dependencies
│       └── venv/              # Python virtual environment
├── .env.example               # Template environment file
├── .gitignore                 # Version control ignores
├── package.json               # Root monorepo configuration
├── supabase_schema.sql        # Database schema, pgvector, and indexes
└── README.md                  # Documentation
```

---

## 🛡️ License

MIT License. See [LICENSE](LICENSE) for details.
# bounce-mcp