theseedship/deposium_MCPs

Deposium MCPs

MCP (Model Context Protocol) server for DuckDB, Supabase and MinIO integration - RAG-optimized document search.

🚀 Overview

This MCP server provides a unified interface for document search and retrieval, combining:

• DuckDB for analytical queries on Parquet files stored in MinIO
• Supabase for metadata, vector embeddings (pgvector), and graph relations
• Redis for intelligent caching
• MinIO for document and Parquet storage

🏗️ Architecture

┌──────────────────┐
│  Claude/LLMs     │
└────────┬─────────┘
         │ MCP Protocol
┌────────▼─────────┐
│  MCP Server      │ Port 4001
├──────────────────┤
│ Tools:           │
│ • search.hub     │
│ • corpus.stats   │
│ • vector.search  │
│ • embed.schedule │
└────────┬─────────┘
         │
    ┌────┴────┬────────┬─────────┐
    ▼         ▼        ▼         ▼
┌────────┐┌────────┐┌────────┐┌────────┐
│DuckDB  ││Supabase││ Redis  ││ MinIO  │
└────────┘└────────┘└────────┘└────────┘

📦 Installation

Prerequisites

• Node.js >= 22
• PostgreSQL with pgvector extension (via Supabase)
• MinIO or S3-compatible storage
• Redis (optional but recommended)
• Ollama (optional, for embeddings)

Local Setup

1. Clone the repository:

git clone https://github.com/nicolas-geysse/deposium_MCPs.git
cd deposium_MCPs

2. Install dependencies:

npm install

3. Copy environment variables:

cp .env.example .env
# Edit .env with your configuration

4. Build the project:

npm run typecheck
npm run build:mcp

5. Run the MCP server:

npm run dev:mcp  # Development mode
npm run start:mcp # Production mode

🛠️ Available MCP Tools

search.hub

Unified search across documents using vector, keyword, and graph-based retrieval.

Input:

{
  "tenant_id": "string",
  "space_id": "string", 
  "query_text": "string",
  "top_k": 20,
  "use_vector_rel": true,
  "use_vector_kw": false,
  "use_graph": false,
  "max_depth": 2
}

corpus.stats

Get statistics about the document corpus.

Input:

{
  "tenant_id": "string",
  "space_id": "string",
  "include_details": false
}

vector.search

Direct vector search for debugging and testing.

Input:

{
  "tenant_id": "string",
  "space_id": "string",
  "channel": "relations|keywords|documents",
  "query_text": "string",
  "top_k": 20
}

embed.schedule

Schedule embedding generation for documents.

Input:

{
  "tenant_id": "string",
  "space_id": "string",
  "scope": "relations|keywords|documents|all",
  "model_id": "nomic-embed-text",
  "doc_ids": [1, 2, 3],
  "priority": 5,
  "overwrite": false
}

🚂 Railway Deployment

1. Create a new Railway project

2. Add the following services:

   • PostgreSQL (with pgvector)
   • Redis
   • MinIO (or configure external S3)

3. Deploy this repository:

railway link
railway up

4. Set environment variables in Railway dashboard:
   • SUPABASE_URL
   • SUPABASE_SERVICE_KEY
   • MINIO_ENDPOINT
   • MINIO_ACCESS_KEY
   • MINIO_SECRET_KEY
   • REDIS_URL

🔗 Claude Desktop Integration

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "deposium": {
      "command": "node",
      "args": ["/path/to/deposium_MCPs/dist/mcp-server.js"],
      "env": {
        "MCP_MODE": "stdio",
        "SUPABASE_URL": "your-url",
        "SUPABASE_SERVICE_KEY": "your-key",
        "MINIO_ENDPOINT": "localhost:9000",
        "MINIO_ACCESS_KEY": "minioadmin",
        "MINIO_SECRET_KEY": "minioadmin"
      }
    }
  }
}

📊 Database Schema

Supabase Tables

-- Document entities
CREATE TABLE document_entities (
  tenant_id UUID,
  space_id UUID,
  doc_id BIGINT,
  entity_key TEXT,
  entity_type TEXT,
  mentions JSONB[],
  PRIMARY KEY (tenant_id, space_id, doc_id, entity_key)
);

-- Entity relations
CREATE TABLE entity_relations (
  tenant_id UUID,
  space_id UUID,
  from_entity TEXT,
  to_entity TEXT,
  relation_type TEXT,
  doc_ids BIGINT[],
  strength REAL,
  PRIMARY KEY (tenant_id, space_id, from_entity, to_entity, relation_type)
);

-- Vector embeddings
CREATE TABLE rel_vec (
  tenant_id UUID,
  space_id UUID,
  embedding vector(768),
  -- ... other fields
);

MinIO Structure

minio/
├── tenants/
│   ├── {tenant_id}/
│   │   ├── spaces/
│   │   │   ├── {space_id}/
│   │   │   │   ├── blocks/*.parquet
│   │   │   │   ├── entities/*.parquet
│   │   │   │   └── documents/*.json

🧪 Testing

# Run type checking
npm run typecheck

# Test with Claude Desktop
npm run dev:mcp

# Test tool directly
curl -X POST http://localhost:4001/tools/call \
  -H "Content-Type: application/json" \
  -d '{
    "name": "corpus.stats",
    "arguments": {
      "tenant_id": "test",
      "space_id": "default"
    }
  }'

🤝 Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'feat: Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📝 License

MIT

🙏 Acknowledgments

• Built with Model Context Protocol SDK
• Powered by DuckDB, Supabase, and MinIO
• Optimized for use with Claude

📧 Contact

For questions or support, please open an issue on GitHub.