LLMStore MCP Server

A Model Context Protocol (MCP) server for LLMStore - a semantic document storage system built on Supabase with pgvector for intelligent document retrieval.

Features

Document Management

• Store documents with automatic embedding generation
• Search documents using semantic similarity
• Update and delete documents with cascade options
• Bulk import multiple documents at once
• Export documents in JSON, CSV, or Markdown formats

Categorization & Organization

• Dynamic categories with hierarchical structure
• Auto-categorization using LLM
• Category assignment with confidence scores
• Tag-based filtering for precise retrieval

Admin Tools

• Regenerate embeddings for documents
• Clean up orphaned data in the database
• Usage analytics with trend analysis
• Statistics dashboard for monitoring

Installation

Quick Start (Recommended)

Using npx (no installation needed)

npx llmstoremcp

Global Installation

npm install -g llmstoremcp

From source

git clone https://github.com/yourusername/llmstoremcp.git
cd llmstoremcp
npm install
npm run build
npm link

Configuration

1. Copy .env.example to .env:

cp .env.example .env

2. Configure your Supabase credentials:

SUPABASE_URL=https://your-project-ref.supabase.co
SUPABASE_ANON_KEY=your-anon-key-here
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key-here

Usage

With Claude Desktop

Add to your Claude Desktop configuration:

Windows

Location: %APPDATA%\Claude\claude_desktop_config.json

macOS

Location: ~/Library/Application Support/Claude/claude_desktop_config.json

Configuration (using npx - recommended)

{
  "mcpServers": {
    "llmstore": {
      "command": "npx",
      "args": ["llmstoremcp"],
      "env": {
        "SUPABASE_URL": "https://your-project-ref.supabase.co",
        "SUPABASE_ANON_KEY": "your-anon-key",
        "SUPABASE_SERVICE_ROLE_KEY": "your-service-key"
      }
    }
  }
}

With Claude Code CLI

One-liner to add MCP server (Windows)

cc mcp add llmstore "npx" "llmstoremcp" --env SUPABASE_URL="https://your-project-ref.supabase.co" SUPABASE_ANON_KEY="your-anon-key" SUPABASE_SERVICE_ROLE_KEY="your-service-key"

One-liner to add MCP server (macOS/Linux)

claude mcp add llmstore "npx" "llmstoremcp" --env SUPABASE_URL="https://your-project-ref.supabase.co" SUPABASE_ANON_KEY="your-anon-key" SUPABASE_SERVICE_ROLE_KEY="your-service-key"

Standalone Server

# With environment variables from .env file
llmstoremcp

# Or with inline environment variables
SUPABASE_URL=https://your-project.supabase.co llmstoremcp

Available Tools

Document Operations

store_document

Store a new document with automatic embedding generation.

{
  "title": "API Documentation",
  "content": "Complete API reference...",
  "description": "REST API documentation",
  "document_type": "documentation",
  "tags": ["api", "rest"],
  "auto_embed": true,
  "auto_categorize": true
}

list_documents

List all documents with filtering and pagination.

{
  "limit": 50,
  "offset": 0,
  "order_by": "created_at",
  "order_direction": "desc",
  "document_type": "documentation",
  "tags": ["api", "rest"],
  "is_active": true,
  "search_title": "API",
  "date_from": "2024-01-01",
  "date_to": "2024-12-31",
  "include_count": true
}

search_documents

Search documents using semantic similarity.

{
  "query": "How to authenticate users",
  "threshold": 0.7,
  "limit": 10,
  "document_type": "documentation"
}

get_document

Retrieve a specific document by ID.

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "include_embeddings": false,
  "include_relationships": true
}

update_document

Update an existing document.

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "title": "Updated Title",
  "content": "Updated content",
  "regenerate_embedding": true
}

delete_document

Delete a document from the system.

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "cascade": true
}

Category Management

list_categories

List all document categories.

{
  "include_stats": true,
  "parent_id": null
}

create_category

Create a new category.

{
  "name": "Technical Documentation",
  "description": "All technical docs",
  "parent_id": null
}

assign_category

Assign a category to a document.

{
  "document_id": "doc-id",
  "category_id": "cat-id",
  "confidence_score": 0.95
}

Admin Tools

get_statistics

Get usage statistics.

{
  "include_search_logs": true,
  "date_from": "2024-01-01",
  "date_to": "2024-12-31"
}

bulk_import

Import multiple documents at once.

{
  "documents": [
    {
      "title": "Doc 1",
      "content": "Content 1"
    },
    {
      "title": "Doc 2",
      "content": "Content 2"
    }
  ],
  "auto_embed": true
}

export_documents

Export documents in various formats.

{
  "format": "json",
  "include_embeddings": false,
  "date_from": "2024-01-01"
}

regenerate_embeddings

Regenerate embeddings for documents.

{
  "document_ids": ["id1", "id2"],
  "batch_size": 10
}

cleanup_orphaned

Clean up orphaned data.

{
  "cleanup_embeddings": true,
  "cleanup_relationships": true,
  "cleanup_categories": false,
  "dry_run": true
}

analyze_usage

Analyze usage patterns.

{
  "period": "month",
  "top_n": 10,
  "include_trends": true
}

Development

Build

npm run build

Development Mode

npm run dev

Testing

npm test

Publishing to npm

1. Update version in package.json
2. Build the project:

npm run build

3. Login to npm:

npm login

4. Publish:

npm publish

Requirements

• Node.js >= 18.0.0
• Supabase project with:
  • pgvector extension enabled
  • LLMStore schema deployed
  • Edge Functions deployed

Architecture

The MCP server communicates with your Supabase instance through:

• REST API for database operations
• Edge Functions for specialized operations:
  • /llmstore-api/* - Main API endpoints
  • /generate-embeddings - Vector generation
  • /semantic-search - Similarity search
  • /auto-categorize - Document categorization

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For issues and questions, please use the GitHub issue tracker.