# meshdb

Distributed full-text search for your servers. Index files locally or across multiple machines, search instantly.

**No dependencies required for single-server use.**

## Features

- **Full-text search** - BM25 ranking with SQLite FTS5
- **Zero dependencies** - Works out of the box with Python 3.8+
- **Multi-server search** - Query across machines via SSH
- **MCP integration** - Works with Claude Code and AI assistants
- **Semantic search** - Optional AI-powered search (requires ChromaDB)

---

## Installation

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

Creates `~/.meshdb/` directory for database and config.

---

## Single-Server Usage (No Config Needed)

### 1. Index your files

```bash
meshdb index ~/projects
meshdb index /var/www
```

### 2. Search

```bash
meshdb search "nginx proxy"
meshdb find "docker-compose.yml"
meshdb status
```

### 3. Use with Claude Code (MCP)

Add to `~/.claude/settings.json`:

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

**That's it!** Single-server mode works without any configuration.

---

## Multi-Server Setup

Search across multiple machines with SSH.

### Requirements

1. **Network connectivity** between machines (see [VPN Requirements](#vpn-requirements))
2. **SSH key authentication** configured
3. **meshdb installed** on each server

### Configuration

Create `~/.meshdb/config.json`:

```json
{
  "servers": {
    "web": {
      "ip": "192.168.1.10",
      "user": "deploy"
    },
    "db": {
      "ip": "192.168.1.20",
      "user": "admin"
    }
  },
  "meshdb_servers": {
    "web": ["/var/www", "/etc/nginx"],
    "db": ["/var/lib/postgresql"]
  }
}
```

### Server Config Fields

| Field | Required | Description |
|-------|----------|-------------|
| `ip` | Yes | Server IP address |
| `user` | Yes | SSH username |
| `home_path` | No | Custom home directory (e.g., `/var/services/homes/user` for Synology NAS) |
| `platform` | No | Set `"darwin"` for macOS servers |
| `agent_path` | No | Custom path to meshdb_agent.py |

### Install on Remote Servers

```bash
ssh user@server "pip install meshpop-db"
```

### VPN Requirements

**Multi-server search requires network connectivity between machines.**

Options:
- **Local network** - All servers on same LAN (192.168.x.x)
- **VPN** - Servers connected via WireGuard, Tailscale, OpenVPN, etc.
- **Public IPs** - Direct internet access (ensure firewall security)

meshdb uses **SSH** for remote connections. Ensure:
1. SSH port (22) is accessible between machines
2. SSH key authentication is configured (`ssh-copy-id`)
3. Firewall allows connections

Example with Tailscale:
```json
{
  "servers": {
    "laptop": { "ip": "100.100.1.10", "user": "me" },
    "server": { "ip": "100.100.1.20", "user": "deploy" }
  }
}
```

---

## MCP Tools Reference

| Tool | Description |
|------|-------------|
| `meshdb_search` | Full-text search with BM25 ranking |
| `meshdb_find` | Find files by filename pattern |
| `meshdb_read` | Read file contents from index |
| `meshdb_status` | Index statistics per server |
| `meshdb_semantic` | Semantic search (requires ChromaDB) |

### meshdb_search Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `query` | Yes | Search query. Supports: AND, OR, NOT, "phrase", prefix* |
| `servers` | No | Comma-separated server list (default: all) |
| `limit` | No | Max results per server (default: 10) |
| `type` | No | Filter: python, json, markdown, shell, rust, etc. |
| `dir` | No | Filter by directory substring |

---

## CLI Reference

```bash
# Indexing
meshdb index <path>              # Index directory
meshdb index <path> --watch      # Index and watch for changes

# Searching
meshdb search <query>            # Full-text search
meshdb search <query> --type py  # Filter by file type
meshdb find <pattern>            # Find by filename

# Status
meshdb status                    # Show index statistics
```

---

## Semantic Search (Optional)

AI-powered search by meaning, not just keywords.

### Requirements

1. **ChromaDB server** running (separate installation)
2. **Embeddings generated** for your files

### Setup ChromaDB

```bash
# Install ChromaDB
pip install chromadb

# Run ChromaDB server
chroma run --host localhost --port 8686
```

### Configure meshdb

Add to `~/.meshdb/config.json`:

```json
{
  "chromadb_host": "localhost",
  "chromadb_port": 8686
}
```

### Generate Embeddings

```bash
meshdb embed
```

### Use Semantic Search

CLI:
```bash
meshdb search --smart "how does authentication work"
```

MCP:
```
meshdb_semantic(query="retry logic on network failure")
```

### How It Works

1. ChromaDB stores vector embeddings of your code
2. Query is converted to embedding
3. Similar code found by vector similarity
4. Results ranked by semantic relevance

**Note:** Semantic search is optional. Full-text search works without ChromaDB.

---

## Architecture

```
┌─────────────────────────────────────────────────────────┐
│                   meshdb_mcp_server.py                  │
│                      (MCP Protocol)                     │
└─────────────────────────────────────────────────────────┘
                            │
            ┌───────────────┼───────────────┐
            ▼               ▼               ▼
     ┌───────────┐   ┌───────────┐   ┌───────────┐
     │  Local    │   │  Remote   │   │  Remote   │
     │  SQLite   │   │  (SSH)    │   │  (SSH)    │
     └─────┬─────┘   └─────┬─────┘   └─────┬─────┘
           │               │               │
     ┌─────▼─────┐   ┌─────▼─────┐   ┌─────▼─────┐
     │ meshdb.db │   │ meshdb.db │   │ meshdb.db │
     └───────────┘   └───────────┘   └───────────┘
```

- **Local queries**: Direct SQLite access (fastest)
- **Remote queries**: SSH to run meshdb_agent.py
- **Results merged**: Combined and ranked by BM25 score

---

## File Locations

| File | Location |
|------|----------|
| Database | `~/.meshdb/meshdb.db` |
| Config | `~/.meshdb/config.json` |
| Agent | `~/.local/bin/meshdb_agent.py` |

Legacy paths (`~/.mpop/`) are supported for backward compatibility.

---

## Environment Variables

| Variable | Description |
|----------|-------------|
| `MESHDB_DB` | Custom database path |
| `MESHDB_AGENT_PATH_<SERVER>` | Custom agent path per server |

---

## Supported File Types

| Category | Extensions |
|----------|------------|
| Code | .py, .js, .ts, .rs, .go, .c, .cpp, .java |
| Shell | .sh, .bash, .zsh |
| Config | .json, .yaml, .yml, .toml, .conf, .ini |
| Docs | .md, .txt, .rst |
| Web | .html, .css, .scss |

---

## Python API

```python
from meshdb import api_search, api_status, index_directory

# Search
results = api_search("nginx config", limit=20)

# Index
index_directory("/path/to/project")

# Status
status = api_status()
```

---

## Troubleshooting

### "Connection failed" to remote server

1. Check SSH connectivity: `ssh user@ip`
2. Verify meshdb is installed: `ssh user@ip "meshdb status"`
3. Check config has correct `user` field

### Search returns no results

1. Index your files first: `meshdb index <path>`
2. Check status: `meshdb status`

### ChromaDB semantic search not working

1. Ensure ChromaDB server is running
2. Check config has `chromadb_host` and `chromadb_port`
3. Generate embeddings: `meshdb embed`

---

## License

MIT
