everything-mcp-server 0.0.0-stage → 0.2.0

package/src/agent.js

@@ -0,0 +1,92 @@
+import { normalizeRoot, configFromEnv, composeQuery, filetimeToISO, resultPath, relativePath, logicalBytes, HttpTransport } from './everything.js';
+import { inspectWindows, discoverIpc } from './discovery.js';
+import { AgentError, errorResult, searchSchema } from './schema.js';
+import { validateQuery, validateRoot } from './validation.js';
+
+const metadata = [
+  ['size', 'size_bytes', logicalBytes],
+  ['date_modified', 'modified_utc', filetimeToISO],
+  ['date_created', 'created_utc', filetimeToISO],
+  ['date_accessed', 'accessed_utc', filetimeToISO],
+  ['attributes', 'attributes', logicalBytes],
+  ['run_count', 'run_count', logicalBytes],
+];
+
+export class AgentClient {
+  constructor(env = process.env, dependencies = {}) {
+    try { this.config = configFromEnv(env); }
+    catch (error) { this.configError = error; this.config = configFromEnv({}); }
+    this.env = env;
+    this.dependencies = dependencies;
+  }
+  async select(signal) {
+    if (this.configError) throw this.configError;
+    if (this.env.EVERYTHING_URL) {
+      const transport = new HttpTransport(this.config, this.dependencies.fetch);
+      return { transport, info: { transport: 'http', instance: this.env.EVERYTHING_INSTANCE ?? null, version: null, local: this.config.local, url: this.config.url } };
+    }
+    const inventory = this.env.EVERYTHING_INSTANCE !== undefined ? { instances: [] } : await (this.dependencies.inspect ?? inspectWindows)(this.env, signal);
+    return (this.dependencies.discoverIpc ?? discoverIpc)(inventory, this.config, this.env, signal);
+  }
+  async ensureSelected(signal) {
+    // Pin a successful selection; retry discovery after a failed connection.
+    this.pending ??= this.select(signal).catch(error => { this.pending = null; throw error; });
+    return this.pending;
+  }
+  async search(arguments_, signal) {
+    const input = searchSchema.parse(arguments_);
+    const deadline = AbortSignal.timeout(input.timeout_ms ?? this.config.timeoutMs);
+    const combined = signal ? AbortSignal.any([signal, deadline]) : deadline;
+    try {
+      const functions = await validateQuery(input);
+      const sumSize = input.count === 0 && input.fields.includes('size');
+      if (sumSize && input.kind !== 'file') throw new AgentError('INVALID_ARGUMENT', 'Use kind:"file" with count:0 and fields:["size"] to sum matching file bytes. Folder sizes are available in result rows.');
+      if (input.root) input.root = normalizeRoot(input.root);
+      const { transport, info } = await this.ensureSelected(combined);
+      if (input.root && info.local) await validateRoot(input.root, Math.min(input.timeout_ms ?? this.config.timeoutMs, 3000), combined);
+      if (functions.includes('dupe') && !info.version?.startsWith('1.5.')) {
+        throw new AgentError('UNSUPPORTED_QUERY', 'dupe: requires a verified Everything 1.5 backend', false, 'Use IPC with Everything 1.5 to verify the query-language version.');
+      }
+      const count = Math.min(input.count, this.config.maxResults);
+      const query = composeQuery(input);
+      const data = await transport.request(input, count, query, combined);
+      if (!count) return { total: data.totalResults, ...(sumSize ? { total_size_bytes: data.totalResults ? logicalBytes(await transport.totalSize(input, query, combined)) : 0, size_basis: 'indexed_logical' } : {}) };
+      if (!data.results.length && input.offset < data.totalResults) throw new AgentError('INCOMPLETE_PAGE', 'Repeat the query or narrow its scope to obtain the remaining results.', true);
+      const columns = metadata.filter(([field]) => input.fields.includes(field));
+      const rows = [];
+      for (const row of data.results) {
+        if (!['file', 'folder'].includes(row?.type) || typeof row.name !== 'string' || typeof row.path !== 'string') throw new AgentError('INVALID_RESPONSE', 'Expected an indexed file or folder path');
+        const full = resultPath(row);
+        const filename = input.root ? relativePath(input.root, full) : full;
+        let size = row.size;
+        if (input.fields.includes('size') && row.type === 'folder' &&
+            (info.version?.startsWith('1.4.') || (info.transport === 'http' && (size == null || size === '' || String(size) === '0')))) {
+          size = await transport.directorySize(full, input, combined);
+        }
+        rows.push([filename.replaceAll('\\', '/'), row.type, ...columns.map(([field, , format]) => format(field === 'size' ? size : row[field]))]);
+      }
+      return {
+        ...(input.root ? { base: input.root.replaceAll('\\', '/') } : {}),
+        total: data.totalResults, next_offset: input.offset + rows.length < data.totalResults ? input.offset + rows.length : null,
+        columns: ['path', 'type', ...columns.map(([, column]) => column)], rows,
+        ...(count < input.count ? { limited_by: ['result_cap'] } : {}),
+        ...(input.fields.includes('size') ? { size_basis: 'indexed_logical' } : {}),
+      };
+    } catch (error) {
+      if (combined.aborted) throw new AgentError(signal?.aborted ? 'CANCELLED' : 'TIMEOUT', signal?.aborted ? 'Request cancelled' : 'Search reached its time budget; narrow the scope or increase the timeout.', true);
+      throw error;
+    }
+  }
+  async status(signal, verbose = false) {
+    try {
+      const { transport, info } = await this.ensureSelected(signal);
+      const result = await transport.request({}, 0, '', signal);
+      return { ready: true, transport: info.transport, version: info.version, instance: info.instance,
+        capabilities: ['paths', 'count', 'browse', 'batch', 'file_size', 'folder_size', 'total_file_size', 'modified_time', 'regex', ...(info.transport === 'ipc' ? ['created_time', 'accessed_time', 'attributes', 'run_count'] : []), ...(info.version?.startsWith('1.5.') ? ['dupe'] : [])], problems: [],
+        ...(verbose ? { details: { total_indexed: result.totalResults, backend: info.url ?? 'local IPC', limits: { max_results: this.config.maxResults, output_bytes: this.config.outputBytes } } } : {}) };
+    } catch (error) {
+      if (signal?.aborted) throw error;
+      return { ready: false, transport: null, version: null, instance: null, capabilities: [], problems: [errorResult(error).error] };
+    }
+  }
+}

package/src/cli.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+import { readFile } from 'node:fs/promises';
+import { AgentClient } from './agent.js';
+import { errorResult, AgentError, diagnosticSchema } from './schema.js';
+import { compactSearch } from './compact.js';
+
+try {
+  const [command = 'mcp', ...rest] = process.argv.slice(2);
+  if (command === 'mcp') {
+    if (rest.length) throw new AgentError('INVALID_ARGUMENT', 'Run mcp as a standalone command');
+    await (await import('./server.js')).startServer();
+  } else {
+    let raw = '{}';
+    if (rest[0] === '--input' && rest.length === 2) raw = await readFile(rest[1], 'utf8');
+    else if (rest[0] === '--stdin' && rest.length === 1) {
+      const chunks = []; let bytes = 0;
+      for await (const chunk of process.stdin) {
+        bytes += chunk.length;
+        if (bytes > 1048576) throw new AgentError('INVALID_ARGUMENT', 'stdin exceeds 1 MiB');
+        chunks.push(chunk);
+      }
+      raw = Buffer.concat(chunks).toString('utf8');
+    } else if (rest.length === 1) raw = rest[0];
+    else if (rest.length) throw new AgentError('INVALID_ARGUMENT', 'Use JSON, --input file.json or --stdin.');
+    let args;
+    try { args = JSON.parse(raw.replace(/^\uFEFF/, '')); }
+    catch { throw new AgentError('INVALID_ARGUMENT', 'Input must be valid JSON'); }
+    const client = new AgentClient();
+    let result;
+    if (command === 'search') result = await compactSearch(client, args);
+    else if (command === 'doctor') { diagnosticSchema.parse(args); result = await client.status(undefined, true); }
+    else if (command === 'help') result = { commands: ['mcp', 'doctor', 'search'], input: 'JSON | --input file.json | --stdin', example: { requests: [{ query: 'ext:pdf', count: 10 }] } };
+    else throw new AgentError('INVALID_ARGUMENT', `Choose mcp, doctor or search; received ${command}.`);
+    console.log(JSON.stringify(result));
+    if (result.ready === false || result.results?.every(item => item.error)) process.exitCode = 1;
+  }
+} catch (error) { console.log(JSON.stringify(errorResult(error))); process.exitCode = 1; }

package/src/compact.js

@@ -0,0 +1,64 @@
+import { AgentError, errorResult, requestsSchema } from './schema.js';
+
+export async function compactSearch(client, arguments_ = {}, signal) {
+  const { requests } = requestsSchema.parse(arguments_);
+  if (requests.reduce((sum, request) => sum + Math.min(request.count, client.config.maxResults), 0) > client.config.maxResults) {
+    throw new AgentError('INVALID_ARGUMENT', 'Batch aggregate count exceeds the configured result cap');
+  }
+  const results = new Array(requests.length);
+  const budget = Math.floor((client.config.outputBytes - 512) / requests.length);
+  let next = 0;
+  const worker = async () => {
+    while (next < requests.length) {
+      const index = next++;
+      const request = requests[index];
+      try {
+        const result = await client.search(request, signal);
+        const returned = result.rows?.length ?? 0;
+        if (result.rows?.length && Buffer.byteLength(JSON.stringify(result)) > budget) {
+          const allRows = result.rows;
+          const originalLimitedBy = result.limited_by ?? [];
+          const candidate = (rowCount) => {
+            result.rows = allRows.slice(0, rowCount);
+            result.next_offset = request.offset + rowCount < result.total ? request.offset + rowCount : null;
+            result.limited_by = [...new Set([...originalLimitedBy, 'output_bytes'])];
+            return Buffer.byteLength(JSON.stringify(result)) <= budget;
+          };
+
+          let low = 1;
+          let high = allRows.length - 1;
+          let best = 0;
+          while (low <= high) {
+            const mid = (low + high) >> 1;
+            if (candidate(mid)) {
+              best = mid;
+              low = mid + 1;
+            } else {
+              high = mid - 1;
+            }
+          }
+          if (best > 0) {
+            candidate(best);
+          } else {
+            result.rows = [];
+            result.next_offset = request.offset < result.total ? request.offset : null;
+            result.limited_by = [...new Set([...originalLimitedBy, 'output_bytes'])];
+          }
+        }
+        if (Buffer.byteLength(JSON.stringify(result)) > budget || (returned && !result.rows.length)) {
+          throw new AgentError('OUTPUT_TOO_LARGE', 'Reduce fields or batch size to fit the output budget.');
+        }
+        results[index] = result;
+      } catch (error) {
+        if (signal?.aborted) throw error;
+        results[index] = { error: errorResult(error).error };
+      }
+    }
+  };
+  await Promise.all([worker(), worker()]);
+  const output = { results };
+  if (Buffer.byteLength(JSON.stringify(output)) > client.config.outputBytes) {
+    throw new AgentError('OUTPUT_TOO_LARGE', 'Reduce batch size to fit the output budget.');
+  }
+  return output;
+}

package/src/discovery.js

@@ -0,0 +1,47 @@
+import path from 'node:path';
+import { access } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import { AgentError } from './schema.js';
+import { IpcTransport } from './ipc.js';
+
+const project = fileURLToPath(new URL('../', import.meta.url));
+
+export async function inspectWindows(env = process.env, _signal) {
+  if (process.platform !== 'win32') throw new AgentError('PLATFORM_SELECTION', 'Use Windows for local IPC, or configure EVERYTHING_URL.');
+  return { instances: [] };
+}
+
+export async function discoverIpc(discovery, config, env = process.env, signal, factory = options => new IpcTransport(options)) {
+  const arch = { x64: 'x64', ia32: 'x86', arm64: 'ARM64', arm: 'ARM' }[process.arch];
+  const executable = env.EVERYTHING_ES_PATH || path.join(project, 'vendor', 'es', arch || process.arch, 'es.exe');
+  try { await access(executable); }
+  catch { throw new AgentError('HELPER_NOT_FOUND', 'Install the bundled ES helper, or set EVERYTHING_ES_PATH to ES 1.1.0.38 or newer.'); }
+
+  const explicit = env.EVERYTHING_INSTANCE !== undefined;
+  const instances = explicit ? [env.EVERYTHING_INSTANCE] : [...new Set([...(discovery?.instances ?? []), '', '1.5a', '1.5'])];
+  const candidates = [];
+
+  for (const instance of instances) {
+    if (signal?.aborted) throw new AgentError('CANCELLED', 'Request cancelled', true);
+    const transport = factory({ executable, instance, timeoutMs: config.timeoutMs, responseBytes: config.responseBytes });
+    try {
+      const version = await transport.getVersion(signal);
+      const [major, minor, revision] = version.split('.').map(Number);
+      if (major < 1 || (major === 1 && (minor < 4 || (minor === 4 && revision < 1)))) {
+        throw new AgentError('UNSUPPORTED_VERSION', 'Everything 1.4.1 or newer is required');
+      }
+      await transport.request({ timeout_ms: 2500 }, 0, '', signal);
+      candidates.push({ transport, info: { transport: 'ipc', instance, version, local: true } });
+    } catch (error) {
+      if (signal?.aborted || error.code === 'CANCELLED' || explicit) throw error;
+    }
+  }
+
+  if (candidates.length > 1) {
+    throw new AgentError('MULTIPLE_INSTANCES', 'Multiple active Everything instances detected: ' + candidates.map(c => JSON.stringify(c.info.instance)).join(', '), false, 'Set EVERYTHING_INSTANCE to select the intended instance.');
+  }
+  if (!candidates.length) {
+    throw new AgentError('INSTANCE_NOT_FOUND', 'Start Everything and ensure its index is ready, or configure EVERYTHING_URL.', true);
+  }
+  return candidates[0];
+}

package/src/everything.js

@@ -0,0 +1,166 @@
+import path from 'node:path';
+import { AgentError } from './schema.js';
+
+const integerEnv = (env, name, fallback, min, max) => {
+  if (env[name] === undefined || env[name] === '') return fallback;
+  const n = Number(env[name]);
+  if (!Number.isInteger(n) || n < min || n > max) throw new AgentError('INVALID_CONFIG', `${name} must be an integer between ${min} and ${max}`);
+  return n;
+};
+export function configFromEnv(env = process.env) {
+  let url;
+  try { url = new URL(env.EVERYTHING_URL || 'http://127.0.0.1/'); }
+  catch { throw new AgentError('INVALID_CONFIG', 'EVERYTHING_URL must be an HTTP(S) origin'); }
+  if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.pathname !== '/' || url.search || url.hash) {
+    throw new AgentError('INVALID_CONFIG', 'Use an HTTP(S) origin without credentials, path, query or fragment; use EVERYTHING_USERNAME/PASSWORD for authentication');
+  }
+  return {
+    url: url.href,
+    username: env.EVERYTHING_USERNAME || '', password: env.EVERYTHING_PASSWORD || '',
+    maxResults: integerEnv(env, 'EVERYTHING_MAX_RESULTS', 1000, 1, 1000),
+    outputBytes: integerEnv(env, 'EVERYTHING_OUTPUT_BYTES', 16384, 4096, 65536),
+    responseBytes: integerEnv(env, 'EVERYTHING_RESPONSE_BYTES', 2097152, 4096, 16777216),
+    timeoutMs: integerEnv(env, 'EVERYTHING_TIMEOUT_MS', 15000, 100, 120000),
+    local: ['127.0.0.1', 'localhost', '[::1]'].includes(url.hostname),
+  };
+}
+
+export function normalizeRoot(root) {
+  const value = root.replaceAll('/', '\\');
+  // Reject search operators and relative/device paths before embedding in query syntax.
+  if (!/^(?:[a-z]:\\|\\\\[^\\]+\\[^\\]+(?:\\|$))/i.test(value) || /["<>|*?\x00-\x1f]/.test(value) || value.startsWith('\\\\.\\') || value.startsWith('\\\\?\\') || /:(?!\\)/.test(value)) {
+    throw new AgentError('INVALID_ARGUMENT', 'root must be an absolute Windows drive or UNC directory without wildcards or query operators');
+  }
+  const normalized = path.win32.normalize(value);
+  return normalized.length > path.win32.parse(normalized).root.length ? normalized.replace(/\\+$/, '') : normalized;
+}
+
+export function composeQuery(input) {
+  const filters = [];
+  if (input.root) {
+    const root = normalizeRoot(input.root);
+    filters.push(input.recursive ? `path:"${root.endsWith('\\') ? root : root + '\\'}"` : `parent:"${root}"`);
+  }
+  if (input.kind !== 'any') filters.push(`${input.kind}:`);
+  let query = input.query;
+  // HTTP regex=1 disables all native filters. Use a scoped modifier instead.
+  if (input.regex && query) query = `regex:"${query.replaceAll('"', '\\x22')}"`;
+  if (query) filters.push(filters.length ? `<${query}>` : query);
+  return filters.join(' ');
+}
+
+export function filetimeToISO(value) {
+  if (value === undefined || value === null || value === '' || String(value) === '0') return null;
+  try {
+    // BigInt avoids rounding away 100-nanosecond Windows FILETIME ticks.
+    const milliseconds = BigInt(value) / 10000n - 11644473600000n;
+    if (milliseconds < -8640000000000000n || milliseconds > 8640000000000000n) return null;
+    return new Date(Number(milliseconds)).toISOString();
+  } catch { return null; }
+}
+
+export function resultPath(row) {
+  // Everything represents indexed drive roots as name="C:", path="".
+  if (row.path === '' && /^[a-z]:$/i.test(row.name)) return `${row.name}\\`;
+  const fullPath = path.win32.join(row.path, row.name);
+  if (!/^(?:[a-z]:\\|\\\\[^\\]+\\[^\\]+)/i.test(fullPath)) throw new AgentError('INVALID_RESPONSE', 'Everything returned a non-absolute result path');
+  return fullPath;
+}
+
+export const syntax = {
+  query_language: 'Everything native syntax; regex:true treats query as a regular expression pattern',
+  examples: [
+    { query: 'ext:pdf;docx report', purpose: 'Documents with report in filename' },
+    { query: 'size:>100mb dm:thismonth', purpose: 'Large recently modified files' },
+    { query: '<ext:ts | ext:js> !path:node_modules !path:.git', root: 'D:\\Projects', purpose: 'Source files beneath a directory' },
+    { query: '^IMG_\\d+\\.jpg$', regex: true, purpose: 'Filename regex' },
+    { query: 'ext:log', kind: 'file', count: 0, fields: ['size'], purpose: 'Count matching files and sum their indexed logical bytes' },
+  ],
+  operators: { and: 'space', or: '|', not: '!', grouping: '<...>', literal: '"..."', wildcard: '* ?', extension: 'ext:ts;js', size: 'size:>10mb or size:1kb..1mb', modified: 'dm:today / dm:thisweek / dm:2026-01-01..2026-12-31', created: 'dc:thismonth', direct_children: 'parent:"D:\\Projects"' },
+  notes: ['Empty query matches all; omitted root searches the selected index.', 'Use regex:true with a regular expression pattern; root/kind filters stay active.', 'Directory exclusions use !path:node_modules.', 'Results and pagination use a live index. File and folder sizes use indexed logical bytes.'],
+  docs: ['https://www.voidtools.com/support/everything/searching/', 'https://www.voidtools.com/support/everything/http/'],
+};
+
+export function logicalBytes(value) {
+  if (!/^\d+$/.test(String(value))) return null;
+  const bytes = BigInt(value);
+  return bytes <= BigInt(Number.MAX_SAFE_INTEGER) ? Number(bytes) : bytes.toString();
+}
+export function relativePath(root, full) {
+  const relative = path.win32.relative(root, full);
+  if (relative === '..' || relative.startsWith('..\\') || path.win32.isAbsolute(relative)) throw new AgentError('INVALID_RESPONSE', 'Expected a result within root');
+  return relative || '.';
+}
+
+export class HttpTransport {
+  constructor(config, fetchImpl = fetch) {
+    this.config = config;
+    this.fetch = fetchImpl;
+  }
+  async request(input, count, query, signal) {
+    if (input.sort && !['name', 'path', 'size', 'date_modified'].includes(input.sort)) throw new AgentError('UNSUPPORTED_QUERY', `Use IPC for sort:${input.sort}; HTTP sorts by name, path, size or date_modified.`);
+    const url = new URL(this.config.url);
+    const params = {
+      search: query, json: 1, count, offset: input.offset ?? 0,
+      sort: input.sort ?? 'path', ascending: input.ascending === false ? 0 : 1,
+      path_column: count > 0 ? 1 : 0, size_column: input.fields?.includes('size') ? 1 : 0,
+      date_modified_column: input.fields?.includes('date_modified') ? 1 : 0,
+      regex: 0, case: 0, wholeword: 0, path: 0, diacritics: 0, prefix: 0, suffix: 0,
+      ignore_punctuation: 0, ignore_whitespace: 0,
+    };
+    for (const field of input.fields ?? []) params[`${field}_column`] = 1;
+    for (const [key, value] of Object.entries(params)) url.searchParams.set(key, String(value));
+    const deadline = AbortSignal.timeout(input.timeout_ms ?? this.config.timeoutMs);
+    const combined = signal ? AbortSignal.any([signal, deadline]) : deadline;
+    const headers = { Accept: 'application/json' };
+    if (this.config.username || this.config.password) headers.Authorization = 'Basic ' + Buffer.from(this.config.username + ':' + this.config.password).toString('base64');
+    try {
+      if (combined.aborted) throw combined.reason;
+      const response = await this.fetch(url, { headers, signal: combined, redirect: 'error' });
+      if (!response.ok) {
+        await response.body?.cancel();
+        if ([401, 403].includes(response.status)) throw new AgentError('AUTH_REQUIRED', 'Set EVERYTHING_USERNAME and EVERYTHING_PASSWORD for this HTTP service.');
+        throw new AgentError('HTTP_ERROR', 'Everything returned HTTP ' + response.status, response.status >= 500);
+      }
+      if (!response.body) throw new AgentError('INVALID_RESPONSE', 'Expected a JSON response body');
+      const chunks = []; let bytes = 0;
+      for await (const chunk of response.body) {
+        bytes += chunk.byteLength;
+        if (bytes > this.config.responseBytes) throw new AgentError('RESPONSE_TOO_LARGE', 'Reduce count or fields to fit the backend response budget.');
+        chunks.push(chunk);
+      }
+      let data;
+      try { data = JSON.parse(Buffer.concat(chunks).toString('utf8')); }
+      catch { throw new AgentError('INVALID_RESPONSE', 'Expected JSON from the configured Everything HTTP service'); }
+      if (!Number.isSafeInteger(data?.totalResults) || data.totalResults < 0 || !Array.isArray(data.results) || data.results.length > count) throw new AgentError('INVALID_RESPONSE', 'Expected a valid search result envelope');
+      for (const field of (input.fields ?? []).filter(field => !['size', 'date_modified'].includes(field))) {
+        if (data.results.some(row => !(field in row))) throw new AgentError('UNSUPPORTED_METADATA', `Use IPC for ${field}; the selected HTTP service provides other metadata columns.`);
+      }
+      return data;
+    } catch (error) {
+      if (combined.aborted) throw new AgentError(signal?.aborted ? 'CANCELLED' : 'TIMEOUT', signal?.aborted ? 'Request cancelled' : 'HTTP request reached its time budget', true);
+      if (error instanceof AgentError) throw error;
+      throw new AgentError('CONNECTION_FAILED', 'Check the configured Everything HTTP URL and service availability.', true);
+    }
+  }
+  async directorySize(root, input, signal) {
+    // HTTP 1.4 may omit folder sizes; sum only the requested folder's indexed files.
+    const scoped = { root, query: '', recursive: true, kind: 'file', fields: ['size'], timeout_ms: input.timeout_ms };
+    return this.totalSize(scoped, composeQuery(scoped), signal);
+  }
+  async totalSize(input, query, signal) {
+    let offset = 0, sum = 0n;
+    for (;;) {
+      const page = await this.request({ ...input, fields: ['size'], offset }, this.config.maxResults, query, signal);
+      if (!page.results.length && offset < page.totalResults) throw new AgentError('INCOMPLETE_PAGE', 'Repeat the size query to obtain the remaining files.', true);
+      for (const row of page.results) {
+        if (row.type !== 'file' || typeof row.name !== 'string' || typeof row.path !== 'string') throw new AgentError('INVALID_RESPONSE', 'Expected indexed files for a size sum');
+        if (input.root) relativePath(input.root, resultPath(row));
+        if (logicalBytes(row.size) === null) throw new AgentError('METADATA_PENDING', 'Wait for indexed file sizes, then repeat the query.', true);
+        sum += BigInt(row.size);
+      }
+      offset += page.results.length;
+      if (offset >= page.totalResults) return sum.toString();
+    }
+  }
+}

package/src/ipc.js

@@ -0,0 +1,82 @@
+import path from 'node:path';
+import { runProcess } from './process.js';
+import { AgentError } from './schema.js';
+import { composeQuery } from './everything.js';
+
+export function parseCSV(text) {
+  const rows = []; let row = [], cell = '', quoted = false;
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i];
+    if (c === '"') { if (quoted && text[i + 1] === '"') { cell += '"'; i++; } else quoted = !quoted; }
+    else if (c === ',' && !quoted) { row.push(cell); cell = ''; }
+    else if ((c === '\n' || c === '\r') && !quoted) { if (c === '\r' && text[i+1] === '\n') i++; row.push(cell); if (row.some(Boolean)) rows.push(row); row = []; cell = ''; }
+    else cell += c;
+  }
+  if (quoted) throw new AgentError('INVALID_RESPONSE', 'Unterminated CSV field from ES');
+  if (cell || row.length) { row.push(cell); rows.push(row); }
+  return rows;
+}
+
+export class IpcTransport {
+  constructor({ executable, instance = '', timeoutMs = 15000, responseBytes = 2097152 }, runner = runProcess) {
+    Object.assign(this, { executable, instance, timeoutMs, responseBytes, runner });
+  }
+  async call(args, signal, timeoutMs = this.timeoutMs) {
+    const result = await this.runner(this.executable, ['-argv', '-code-page', '65001', '-instance', this.instance, ...args], { signal, timeoutMs, maxBytes: this.responseBytes });
+    if (result.code !== 0) throw new AgentError(result.code === 8 ? 'INSTANCE_NOT_FOUND' : result.code === 6 ? 'ES_VERSION_UNSUPPORTED' : 'IPC_QUERY_FAILED', `ES IPC request failed (exit ${result.code})`, true, 'Run everything-mcp-server doctor; check the instance, index readiness, helper version and process permissions.');
+    return result.stdout;
+  }
+  async getVersion(signal) {
+    const value = (await this.call(['-get-everything-version'], signal, 2500)).trim();
+    if (!/^\d+\.\d+\.\d+\.\d+$/.test(value) || value.startsWith('0.')) throw new AgentError('INSTANCE_NOT_FOUND', 'Choose an active Everything client instance');
+    return value;
+  }
+  options(input) {
+    const args = ['-timeout', String(input.timeout_ms ?? this.timeoutMs), '-count', '4294967295', '-no-pause', '-no-highlight', '-no-hide-empty-search-results', '-no-empty-search-help', '-header', '-no-footer'];
+    for (const flag of ['case','whole-word','match-path','diacritics','prefix','suffix','ignore-punctuation','ignore-whitespace']) args.push(`-no-${flag}`);
+    args.push('-sort', `${(input.sort ?? 'path').replaceAll('_', '-')}-${input.ascending === false ? 'descending' : 'ascending'}`);
+    return args;
+  }
+  async request(input, count, query, signal) {
+    const deadline = AbortSignal.timeout(input.timeout_ms ?? this.timeoutMs);
+    try { return await this.execute(input,count,query,signal ? AbortSignal.any([signal,deadline]) : deadline); }
+    catch(error) { if (deadline.aborted && !signal?.aborted) throw new AgentError('TIMEOUT','IPC query reached its time budget',true,'Narrow the query or increase timeout_ms.'); throw error; }
+  }
+  async execute(input, count, query, signal) {
+    const common = this.options(input);
+    const text = await this.call([...common, '-viewport-offset','0','-viewport-count','0','-get-result-count','--',query],signal,input.timeout_ms);
+    if (!/^\d+\s*$/.test(text)) throw new AgentError('INVALID_RESPONSE', 'ES returned an invalid count');
+    const totalResults = Number(text.trim());
+    if (!Number.isSafeInteger(totalResults)) throw new AgentError('INVALID_RESPONSE', 'ES count exceeds the safe integer range');
+    if (!count) return { totalResults, results: [] };
+    const fields = [...new Set(['attributes', ...(input.fields ?? [])])];
+    const csv = await this.call([...common, '-columns', ['filename', ...fields.map(field => field.replaceAll('_', '-'))].join(';'),
+      '-csv','-no-folder-append-path-separator','-no-digit-grouping','-size-format','1','-date-format','2',
+      '-viewport-offset',String(input.offset ?? 0),'-viewport-count',String(count),'--',query],signal,input.timeout_ms);
+    const [header = [], ...rows] = parseCSV(csv);
+    const filename = header.indexOf('Filename'), attributes = header.indexOf('Attributes');
+    const indexes = fields.map(field => [field, header.indexOf(field.split('_').map(word => word[0].toUpperCase() + word.slice(1)).join(' '))]);
+    if (filename < 0 || indexes.some(([, index]) => index < 0) || rows.length > count) throw new AgentError('INVALID_RESPONSE', 'ES returned unexpected CSV columns or too many rows');
+    const results = rows.map(row => {
+      if (row.length !== header.length) throw new AgentError('INVALID_RESPONSE', 'ES returned a malformed CSV row');
+      const attr = row[attributes];
+      if (!/^(?:\d+|[A-Z]*)$/.test(attr)) throw new AgentError('INVALID_RESPONSE', 'ES returned invalid attributes');
+      const full = row[filename], folder = /^\d+$/.test(attr) ? Boolean(BigInt(attr) & 16n) : attr.includes('D');
+      const drive = /^[a-z]:\\?$/i.test(full);
+      return { name: drive ? full.slice(0,2) : path.win32.basename(full), path: drive ? '' : path.win32.dirname(full), type: folder ? 'folder' : 'file', ...Object.fromEntries(indexes.map(([field, index]) => [field, row[index]])) };
+    });
+    return { totalResults, results };
+  }
+  async totalSize(input, query, signal) {
+    const sum = (await this.call([...this.options(input), '-size-format', '1', '-no-digit-grouping', '-viewport-offset', '0', '-viewport-count', '4294967295', '-get-total-size', '--', query], signal, input.timeout_ms)).trim();
+    if (!/^\d+$/.test(sum)) throw new AgentError('INVALID_RESPONSE', 'Expected an integer byte count from ES');
+    if (sum === '18446744073709551615') {
+      if ((await this.request(input, 0, query, signal)).totalResults === 0) return '0';
+      throw new AgentError('METADATA_PENDING', 'Wait for indexed file sizes, then repeat the query.', true);
+    }
+    return sum;
+  }
+  async directorySize(root, input, signal) {
+    return this.totalSize(input, composeQuery({ root, query: '', recursive: true, kind: 'file', regex: false }), signal);
+  }
+}

package/src/process.js

@@ -0,0 +1,22 @@
+import { spawn } from 'node:child_process';
+import { AgentError } from './schema.js';
+
+export function runProcess(executable, args, { signal, timeoutMs = 15000, maxBytes = 2097152, env } = {}) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) return reject(new AgentError('CANCELLED', 'Request cancelled', true));
+    let child, timer, ended = false, size = 0;
+    const chunks = [], errors = [], cleanup = new AbortController();
+    const finish = (error, result) => {
+      if (ended) return; ended = true; clearTimeout(timer); cleanup.abort();
+      if (error) { child?.kill(); reject(error); } else resolve(result);
+    };
+    try { child = spawn(executable, args, { shell: false, windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'], ...(env ? {env} : {}) }); }
+    catch { return finish(new AgentError('PROCESS_START_FAILED', 'Install the backend helper and check execution permissions')); }
+    timer = setTimeout(() => finish(new AgentError('TIMEOUT', 'Backend helper timed out', true)), timeoutMs);
+    signal?.addEventListener('abort', () => finish(new AgentError('CANCELLED', 'Request cancelled', true)), { once: true, signal: cleanup.signal });
+    child.on('error', error => finish(new AgentError(error.code === 'ENOENT' ? 'HELPER_NOT_FOUND' : 'PROCESS_START_FAILED', 'Install the backend helper and check execution permissions')));
+    child.stdout.on('data', chunk => { size += chunk.length; if (size > maxBytes) finish(new AgentError('RESPONSE_TOO_LARGE', 'Backend output exceeded the configured byte limit')); else chunks.push(chunk); });
+    child.stderr.on('data', chunk => { if (errors.reduce((n,b)=>n+b.length,0) < 8192) errors.push(chunk); });
+    child.on('close', code => finish(null, { code, stdout: Buffer.concat(chunks).toString('utf8').replace(/^\uFEFF/, ''), stderr: Buffer.concat(errors).toString('utf8') }));
+  });
+}

package/src/schema.js

@@ -0,0 +1,92 @@
+import { z } from 'zod';
+
+export const requestSchema = z.object({
+  query: z.string().max(8192).default('').describe('Everything filename, path or indexed metadata query (e.g. *.pdf, size:>10mb).'),
+  root: z.string().max(1024).optional().describe('Absolute Windows directory or drive path; omitted = global search.'),
+  recursive: z.boolean().default(true).describe('When root is set: search all descendants (true) or direct children only (false).'),
+  kind: z.enum(['any', 'file', 'folder']).default('any').describe('Filter by entry type (any, file, folder).'),
+  regex: z.boolean().default(false).describe('Treat query as a regular expression.'),
+  count: z.number().int().min(0).max(1000).default(20).describe('Maximum rows; 0 counts. With kind:file and fields:[size], also sums matched file bytes.'),
+  offset: z.number().int().min(0).max(4294967295).default(0).describe('Zero-based result offset for pagination.'),
+  sort: z.enum(['name', 'path', 'size', 'extension', 'date_modified', 'date_created', 'date_accessed', 'attributes', 'run_count']).default('path').describe('Sort field. HTTP supports name/path/size/date_modified; IPC supports all.'),
+  ascending: z.boolean().default(true).describe('Sort ascending (true) or descending (false).'),
+  fields: z.array(z.enum(['size', 'date_modified', 'date_created', 'date_accessed', 'attributes', 'run_count'])).max(6).default([]).describe('Optional metadata columns to retrieve.'),
+}).strict();
+
+export const searchSchema = requestSchema.extend({
+  timeout_ms: z.number().int().min(100).max(120000).optional().describe('Search timeout in milliseconds.'),
+});
+
+export const requestsSchema = z.object({
+  requests: z.array(requestSchema).min(1).max(8).describe('1–8 queries, in result order.'),
+}).strict();
+
+export const diagnosticSchema = z.object({ verbose: z.boolean().default(false) }).strict();
+
+const uint = z.number().int().nonnegative();
+
+export const errorSchema = z.object({
+  code: z.string(),
+  message: z.string(),
+  retryable: z.boolean(),
+  hint: z.string().optional(),
+});
+
+export const searchOutputSchema = z.object({
+  results: z.array(z.union([
+    z.object({
+      total: uint,
+      next_offset: uint.nullable(),
+      base: z.string().optional(),
+      columns: z.array(z.string()),
+      rows: z.array(z.array(z.union([z.string(), z.number(), z.null()]))),
+      limited_by: z.array(z.string()).optional(),
+      size_basis: z.literal('indexed_logical').optional(),
+    }).strict(),
+    z.object({
+      total: uint,
+      total_size_bytes: z.union([uint, z.string()]).optional(),
+      size_basis: z.literal('indexed_logical').optional(),
+    }).strict(),
+    z.object({ error: errorSchema }).strict(),
+  ])),
+}).strict();
+
+export const statusOutputSchema = z.object({
+  ready: z.boolean(),
+  transport: z.string().nullable(),
+  version: z.string().nullable(),
+  instance: z.string().nullable(),
+  capabilities: z.array(z.string()),
+  problems: z.array(errorSchema),
+  details: z.record(z.string(), z.unknown()).optional(),
+}).strict();
+
+export class AgentError extends Error {
+  constructor(code, message, retryable = false, hint) {
+    super(message);
+    Object.assign(this, { code, retryable, hint });
+  }
+}
+
+export function errorResult(error) {
+  if (error instanceof z.ZodError) {
+    return {
+      ok: false,
+      error: {
+        code: 'INVALID_ARGUMENT',
+        message: error.issues.map(issue => `${issue.path.join('.') || 'arguments'}: ${issue.message}`).join('; '),
+        retryable: false,
+      },
+    };
+  }
+  return {
+    ok: false,
+    error: {
+      code: error instanceof AgentError ? error.code : 'INTERNAL_ERROR',
+      message: error instanceof AgentError ? error.message : 'Unexpected internal error',
+      retryable: error.retryable ?? false,
+      ...(error.hint ? { hint: error.hint } : {}),
+    },
+  };
+}