doc_find

Instructions

Implementation Reference

• src/tools/doc.ts:85-99 (handler)

  The core handler function that searches the local document index (MiniSearch). Loads/builds the index, searches with prefix/fuzzy matching, and returns scored snippets.

  export async function docFind(q: string, top = 5) {
    let idx = loadIndex();
    if (!idx) { await indexBuild(CONFIG.sandboxDir); idx = loadIndex(); }
    if (!idx) return [];
    const res = idx.mini.search(q, { prefix: true, fuzzy: 0.2, boost: { title: 2 } }).slice(0, top);
    return res.map((r: any) => {
      const doc = idx.docs.find(d => d.id === r.id)!;
      const text = doc.text || '';
      const i = text.toLowerCase().indexOf(q.toLowerCase());
      const start = Math.max(0, i - 80);
      const end = Math.min(text.length, i + 80);
      const snippet = text.slice(start, end).replace(/\s+/g, ' ');
      return { path: doc.path, score: r.score, snippet };
    });
  }

• src/server.ts:104-108 (schema)

  Zod schema defining inputs for doc_find: 'q' (string, required), 'top' (optional int), 'limit' (optional int).

  const docFindShape = {
    q: z.string(),
    top: z.number().int().optional(),
    limit: z.number().int().optional()
  };

• src/server.ts:116-122 (registration)

  Registration of the 'doc_find' tool alias, delegating to the docFind handler with the same docFindShape schema.

  server.tool('doc_find', 'Alias of doc.find',
    docFindShape, OPEN,
    async ({ q, top, limit }) => {
      const res = await docFind(q, top ?? limit ?? 5);
      return { content: [{ type: 'text', text: JSON.stringify(res) }] };
    }
  );

• src/tools/doc.ts:58-76 (helper)

  indexBuild helper that collects files from the sandbox directory, converts them to text (with PDF/HTML support), and builds a MiniSearch index saved to .cache/index.json.

  export async function indexBuild(root?: string) {
    const base = root ? path.resolve(root) : CONFIG.sandboxDir;
    const files = await collectFiles(base);
    const docs: DocRecord[] = [];
    for (const p of files) {
      const { title, text } = await fileToText(p);
      docs.push({ id: p, path: p, title, text });
    }
    const mini = new MiniSearch({
      fields: ['title','text'],
      storeFields: ['path','title'],
      searchOptions: { boost: { title: 2 } }
    });
    mini.addAll(docs);
    const payload = { docs, index: mini.toJSON() };
    await fs.mkdir(path.dirname(INDEX_PATH), { recursive: true }).catch(()=>{});
    await fs.writeFile(INDEX_PATH, JSON.stringify(payload));
    return { ok: true, indexed: docs.length };
  }

• src/tools/doc.ts:78-83 (helper)

  loadIndex helper that loads the cached MiniSearch index from disk, used by docFind.

  function loadIndex() {
    if (!fssync.existsSync(INDEX_PATH)) return null;
    const payload = JSON.parse(fssync.readFileSync(INDEX_PATH, 'utf-8'));
    const mini = MiniSearch.loadJSON(payload.index, { fields: ['title','text'], storeFields: ['path','title'] });
    return { mini, docs: payload.docs as DocRecord[] };
  }