# meshpop-db (meshdb)

Distributed full-text search engine for server meshes. SQLite FTS5 with optional semantic search via ChromaDB.

## Quick Start

```bash
pip install meshpop-db
```

This installs `meshdb` CLI and `meshdb-mcp` MCP server.

## MCP Server Setup

Add to Claude Code config (`~/.claude/settings.json`):

```json
{
  "mcpServers": {
    "meshdb": { "command": "meshdb-mcp" }
  }
}
```

If not on PATH:

```json
{
  "mcpServers": {
    "meshdb": { "command": "python3", "args": ["-m", "meshdb_mcp_server"] }
  }
}
```

## MCP Tools Reference

| Tool | Parameters | Description |
|------|-----------|-------------|
| `meshdb_search` | `query` (required), `servers`, `limit`, `type`, `dir` | Full-text search across all servers (244K+ indexed files) |
| `meshdb_find` | `query` (required), `servers`, `limit` | Find files by filename pattern |
| `meshdb_read` | `path`, `server` (required) | Read indexed file contents |
| `meshdb_status` | `server` | Index status — file count, size, last updated |
| `meshdb_semantic` | `query` (required), `limit` | Semantic code search via AI embeddings (ChromaDB) |

### Search Examples (for AI)

```
meshdb_search(query="nginx config")           # Find nginx configs across all servers
meshdb_search(query="ssl certificate", type="conf")  # Search only config files
meshdb_find(query="docker-compose")           # Find docker-compose files everywhere
meshdb_read(path="/etc/nginx/nginx.conf", server="v1")  # Read specific file
meshdb_semantic(query="how does authentication work")   # AI-powered semantic search
```

## CLI Usage

```bash
# Index a directory
meshdb index /path/to/project

# Full-text search
meshdb search "nginx proxy"

# Smart search (AI-enhanced)
meshdb search --smart "how does the backup work"

# Find files by name
meshdb find "*.conf"

# Search with filters
meshdb search "database" --type py --server relay1

# Check index status
meshdb status
```

## How It Works

1. **Indexing**: Scans directories, extracts text from files, stores in SQLite FTS5
2. **Search**: BM25 ranking with snippet highlighting
3. **Distributed**: Each server maintains its own index, queries fan out to all
4. **Semantic** (optional): ChromaDB embeddings for meaning-based code search

## Interfaces

| Interface | Usage |
|-----------|-------|
| CLI | `meshdb search <query>` |
| Python API | `import meshdb; meshdb.api_search(query)` |
| MCP Server | `meshdb-mcp` for Claude Code / AI tools |

## Requirements

- Python 3.8+
- Zero external dependencies (uses built-in sqlite3 FTS5)
- ChromaDB optional for semantic search

## License

MIT — [MeshPOP](https://github.com/meshpop)
