README

🔎 searchhelper 🔎

searchhelper is a small PHP helper and MCP server for indexed file search.

it wraps fast host indexes instead of recursively scanning slow mounts:

• Everything on Windows via its HTTP server
• plocate on Linux via CLI

installation

install once with composer:

composer require vielhuber/searchhelper

then add this to your files:

require __DIR__ . '/vendor/autoload.php';
use vielhuber\searchhelper\searchhelper;

setup

searchhelper reads configuration from the .env in your project root.

SEARCHHELPER_ROOTS=/host/data/documents,/host/data/projects
SEARCHHELPER_ENGINES=everything,plocate
SEARCHHELPER_EVERYTHING_URL=http://host.docker.internal:8081
SEARCHHELPER_EVERYTHING_USERNAME=
SEARCHHELPER_EVERYTHING_PASSWORD=
SEARCHHELPER_PATH_MAPPINGS=C:\Data=>/host/data
MCP_TOKEN=

SEARCHHELPER_ROOTS is the final search allowlist. Everything and plocate may index more files, but searchhelper only returns results below these roots. use focused roots like /host/data/documents.

SEARCHHELPER_PATH_MAPPINGS is only needed for Everything. Everything returns Windows paths, while code running in Docker/WSL usually needs Linux paths.

usage

$search = searchhelper::create();

$result = $search->searchFiles(
    query: 'project notes',
    limit: 10
);

print_r($result['items']);

everything

1. install Everything.
2. settings > HTTP-Server > enable, Port: 8081
3. set SEARCHHELPER_EVERYTHING_URL=http://host.docker.internal:8081 when searchhelper runs in Docker.
4. set SEARCHHELPER_PATH_MAPPINGS so Windows result paths can be converted to mounted Linux paths.

when Everything returns Windows paths, SEARCHHELPER_PATH_MAPPINGS maps them back into the container. example:

SEARCHHELPER_PATH_MAPPINGS=C:\Data=>/host/data

then a result like C:\Data\documents\file.pdf becomes /host/data/documents/file.pdf.

plocate

plocate is mainly useful when searchhelper runs directly on the Linux system that owns the index, for example in WSL. for Docker setups with slow Windows/OneDrive mounts, prefer Everything on the Windows host.

short setup in WSL/Linux:

apt-get update
apt-get install -y plocate
updatedb

searchhelper executes plocate where PHP runs. if the MCP server runs directly in WSL, WSL's plocate is used. installing plocate inside Docker only helps when the relevant files are on fast container-local or Linux-native mounts.

mcp server

searchhelper ships as a standalone MCP server:

vendor/bin/mcp-server.php

available tools:

• search_files(query, limit?)
• status()

tests

vendor/bin/phpunit