meshpop-db 1.0.8

Distributed search database with semantic indexing and MCP server

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

pip install meshpop-db

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

---

Single-Server Usage (No Config Needed)

1. Index your files

meshdb index ~/projects
meshdb index /var/www

2. Search

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

3. Use with Claude Code (MCP)

Add to ~/.claude/settings.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)
2. SSH key authentication configured
3. meshdb installed on each server

Configuration

Create ~/.meshdb/config.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 and Index Remote Servers

# Install on each server
ssh user@server1 "pip install meshpop-db"
ssh user@server2 "pip install meshpop-db"

# Index files on each server
ssh user@server1 "meshdb index ~"
ssh user@server2 "meshdb index /var/www"

Or batch install/index:

servers="user1@server1 user2@server2 user3@server3"

# Install all
for srv in $servers; do ssh $srv "pip install meshpop-db"; done

# Index all (parallel)
for srv in $servers; do ssh $srv "meshdb index ~" & done; wait

Each server maintains its own index. Searches query all servers in parallel.

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:

{
  "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

# 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

# Install ChromaDB
pip install chromadb

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

Configure meshdb

Add to ~/.meshdb/config.json:

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

Generate Embeddings

meshdb embed

Use Semantic Search

CLI:

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

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