Quick Start

Get textrawl running in 5 minutes.

Prerequisites

Node.js 22+ (Download)
Supabase account (Sign up free)
OpenAI API key (Get one)

Step 1: Clone and Install

git clone https://github.com/jeffgreendesign/textrawl.git
cd textrawl
pnpm install

Step 2: Run Setup

The setup script creates your .env file with secure defaults:

pnpm run setup

You'll be prompted for:

Supabase URL
Supabase Service Key
OpenAI API Key

Step 3: Initialize Database

In the Supabase SQL Editor, run:

-- Paste contents of scripts/setup-db.sql

Then run the security script:

-- Paste contents of scripts/security-rls.sql

Step 4: Start the Server

pnpm run dev

Server runs at http://localhost:3000

Step 5: Connect a Client

textrawl supports multiple access methods. Choose whichever suits your workflow:

Web Dashboard

Open http://localhost:3000 in your browser. You should see the knowledge explorer where you can browse documents, upload files, and explore your knowledge base.

Claude Desktop (MCP)

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

{
  "mcpServers": {
    "textrawl": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

Restart Claude Desktop to connect.

REST API

Query textrawl directly over HTTP (the setup script generates API_BEARER_TOKEN in your .env):

curl -H "Authorization: Bearer $API_BEARER_TOKEN" http://localhost:3000/api/documents

Verify It Works

Using the Dashboard

Open http://localhost:3000. Try uploading a document or creating a note from the dashboard.

Using the REST API

# Check health (no auth required)
curl http://localhost:3000/health
 
# Search for documents
curl -H "Authorization: Bearer $API_BEARER_TOKEN" \
  "http://localhost:3000/api/search?q=test&limit=5"

Using MCP Inspector

pnpm run inspector

Opens a web UI at http://localhost:5173 to test tools interactively.

In Claude Desktop

Ask Claude:

"Use the search tool to find documents about getting started"

If no documents exist yet, add a test note:

"Use add_note to create a note titled 'Test Note' with content 'This is a test of textrawl'"

Then search for it:

"Search for 'test' in my knowledge base"

Next Steps

Add your first documents with CLI tools
Configure embeddings for Ollama (local)
Supabase requirements for compute tier and sizing
Deploy to production with Docker

Troubleshooting

"Database not configured"

Verify your .env has valid Supabase credentials:

SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_KEY=your-service-key

"OpenAI not configured"

Ensure OPENAI_API_KEY is set in .env

Claude can't connect

Verify server is running: curl http://localhost:3000/health
Check Claude Desktop config path is correct
Restart Claude Desktop after config changes

On this page