PocketMCP

PocketMCP is a lightweight, local-first MCP (Model Context Protocol) server that automatically watches folders, chunks and embeds files locally using Transformers.js with MiniLM, stores vectors in SQLite + sqlite-vec, and exposes semantic search capabilities to VS Code and Cursor. Designed for small machines (I'm running on an Intel N100 with 16GB RAM) with zero external dependencies after initial model download.

Features

• 🔍 Semantic Search: Find content by meaning, not just keywords

• 📁 Auto-Ingestion: Watches folders and automatically processes new/changed files

• 📄 Multi-Format Support: PDF, DOCX, Markdown, and plain text files

• ⚡ Local-First: Runs completely offline after initial model download

• 🗄️ SQLite Storage: Fast, reliable vector storage with sqlite-vec extension

• 🔧 MCP Integration: Native support for VS Code and Cursor via MCP protocol

• 🌐 Web Interface: Built-in web tester for validation and manual testing

• 💾 Efficient: Designed for resource-constrained environments

• 🔄 Real-time: Debounced file watching with smart concurrency limits

• 📊 Smart Segmentation: Page-aware PDF processing and section-aware DOCX handling

• 🛡️ Robust Error Handling: Graceful handling of encrypted, corrupted, or oversized files

Architecture

Performance & Limits

• Sweet spot: 10K-100K chunks on modest hardware

• Query latency: Sub-100ms for top_k <= 10 on typical corpora

• Memory usage: ~100MB for model + minimal overhead per document

• Concurrency: Limited to 3 simultaneous file operations by default

• File size limit: 50MB per file (configurable)

Screenshots

Table of Contents

• Features

• Architecture

• Performance & Limits

• Quick Start

• Web Tester

• MCP Client Integration

• API Reference

• Configuration

• Development

• Deployment

• Troubleshooting

Quick Start

1. Installation

2. Configuration

Edit .env file:

3. Create Content Directory

4. Start the Server

On first run, the server will download the MiniLM model (~100MB) and then process any files in your watch directory.

Web Tester

PocketMCP includes a comprehensive web interface for testing and validation.

Access Points

• Web Interface: http://127.0.0.1:5173

• API Server: http://127.0.0.1:5174

• Health Check: http://127.0.0.1:5174/health

Features

📊 Database Diagnostics Panel

• Real-time database status monitoring

• Table counts and vector dimensions

• SQLite WAL mode verification

• Error detection and reporting

• One-click smoke testing

🔍 Search Panel

• Interactive semantic search testing

• LIKE vs Vector search modes

• Configurable result count (top-K)

• Detailed result inspection

• Performance metrics (response time)

📄 Documents Panel

• Browse all indexed documents

• Pagination support

• Document metadata display

• Creation and update timestamps

🔎 Chunk Viewer

• Detailed chunk inspection modal

• Full text content display

• Metadata and offset information

• Copy-to-clipboard functionality

API Endpoints

Example API Usage

Search Documents:

Get Diagnostics:

🔧 MCP Client Integration

Cursor Integration

1. Open Cursor Settings → MCP

2. Add a new server:

VS Code Integration

Add to your MCP settings:

HTTP Transport (Web Clients)

For web clients or remote access:

📚 API Reference

MCP Tools

search

Search for similar content using semantic search.

upsert_documents

Insert or update documents programmatically.

delete_documents

Delete documents by ID.

list_documents

List all documents with pagination.

MCP Resources

PocketMCP provides resource URIs for accessing specific chunks:

• Format: mcp+doc://<doc_id>#<chunk_id>

• Returns: Complete chunk data including text, offsets, and metadata

Configuration

Environment Variables

Available Scripts

Watch Directory

• WATCH_DIR - if not set, only manual document upserts work

• Supported files: .md, .txt, .pdf, .docx

• File filtering: Automatically ignores temp files, .DS_Store, node_modules, etc.

• Nested directories: Recursively watches all subdirectories

Document Processing

Processing Pipeline: Documents → Segments → Chunks

1. Documents: Top-level files with metadata

2. Segments: Logical divisions (PDF pages, DOCX sections, etc.)

3. Chunks: Text pieces optimized for embedding (~1000 chars)

Status Types: ok, skipped, needs_ocr, too_large, error

Supported File Types

• Markdown (.md)

• Plain text (.txt)

• PDF (.pdf) - Text-based only, no OCR

• DOCX (.docx) - Microsoft Word documents

Notes:

• Encrypted/password-protected files are skipped

• Large files exceeding limits are marked as too_large

• Scanned PDFs requiring OCR are marked as needs_ocr

Development

Project Structure

Development Commands

Deployment

Docker (Recommended)

Quick Start:

Access Points:

• MCP Server: http://localhost:8001

• API Server: http://localhost:5174

• Web UI: http://localhost:5173

Docker Compose:

Portainer Stacks

1. Go to Stacks → Add stack

2. Name: pocketmcp

3. Paste this configuration:

Direct Installation

Access Points:

• MCP Server: http://localhost:8001

• API Server: http://localhost:5174

• Web UI: http://localhost:5173

Troubleshooting

Model Download Issues

If the embedding model fails to download:

• Check internet connection for initial download

• Model cache location: ~/.cache/huggingface/transformers/

• Clear cache and retry if needed

SQLite Extension Issues

If sqlite-vec fails to load:

• Ensure sqlite-vec npm package is installed

• Check that your system supports the required SQLite version

• The system automatically falls back to regular SQLite tables if vec0 virtual tables fail

File Watching Issues

• Files not being detected: Check file extensions and ignore patterns

• High CPU usage: Increase debounce time with larger debounceMs values

• Permission errors: Ensure read/write access to watch and data directories

Web Interface Issues

• API not accessible: Ensure API server is running on port 5174

• Database not found: Check SQLITE_PATH environment variable

• CORS errors: API server includes CORS headers for local development

Memory Issues

• Reduce CHUNK_SIZE for lower memory usage

• Process fewer files simultaneously by reducing maxConcurrency

• Consider using a smaller embedding model (though this requires code changes)

Common Error Messages

"Too many parameter values were provided"

• This was a known issue with sqlite-vec virtual tables, now fixed with automatic fallback

"Failed to load sqlite-vec extension"

• System automatically falls back to regular SQLite tables with JSON embeddings

"Database file does not exist"

• Run the MCP server first to create the database, or check the SQLITE_PATH

License

MIT License - see LICENSE file for details.

Contributing

1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Add tests if applicable

5. Submit a pull request

Acknowledgments

• sqlite-vec for fast vector similarity search

• Transformers.js for local embedding generation

• Model Context Protocol for standardized tool integration

• Hugging Face for the MiniLM model

• React + Vite for the modern web interface

• TailwindCSS for beautiful, responsive styling