agentic-knowledge-mcp 1.5.0 → 1.6.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-knowledge-mcp",
-  "version": "1.5.0",
+  "version": "1.6.1",
   "description": "A Model Context Protocol server for agentic knowledge guidance with web-based documentation loading and intelligent search instructions",
   "type": "module",
   "main": "packages/cli/dist/index.js",
@@ -8,7 +8,7 @@
     "agentic-knowledge": "packages/cli/dist/index.js"
   },
   "engines": {
-    "node": ">=18.0.0",
+    "node": ">=20.0.0",
     "pnpm": ">=9.0.0"
   },
   "files": [
@@ -29,9 +29,9 @@
     "commander": "^12.0.0",
     "js-yaml": "4.1.0",
     "ora": "^8.0.1",
-    "@codemcp/knowledge": "1.5.0",
-    "@codemcp/knowledge-content-loader": "1.5.0",
-    "@codemcp/knowledge-core": "1.5.0"
+    "@codemcp/knowledge-content-loader": "1.6.1",
+    "@codemcp/knowledge": "1.6.1",
+    "@codemcp/knowledge-core": "1.6.1"
   },
   "devDependencies": {
     "@eslint/js": "^9.34.0",

package/packages/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codemcp/knowledge-cli",
-  "version": "1.5.0",
+  "version": "1.6.1",
   "description": "Command-line interface for agentic knowledge web content management",
   "type": "module",
   "main": "dist/exports.js",

package/packages/content-loader/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codemcp/knowledge-content-loader",
-  "version": "1.5.0",
+  "version": "1.6.1",
   "description": "Web content loading and metadata management for agentic knowledge system",
   "type": "module",
   "main": "dist/index.js",

package/packages/core/dist/index.d.ts

@@ -13,3 +13,4 @@ export { createSymlinks, removeSymlinks } from "./paths/symlinks.js";
 export { discoverDirectoryPatterns, discoverMinimalPatterns, } from "./paths/discovery.js";
 export { safelyClearDirectory, containsSymlinks, getDirectoryInfo, } from "./paths/cleanup.js";
 export { processTemplate, getEffectiveTemplate, validateTemplate, extractVariables, createTemplateContext, createStructuredResponse, } from "./templates/processor.js";
+export { buildFileIndex, searchDocset, formatSearchResult, type DocsetIndex, } from "./search/searcher.js";

package/packages/core/dist/index.js

@@ -20,3 +20,5 @@ export { discoverDirectoryPatterns, discoverMinimalPatterns, } from "./paths/dis
 export { safelyClearDirectory, containsSymlinks, getDirectoryInfo, } from "./paths/cleanup.js";
 // Export template processing
 export { processTemplate, getEffectiveTemplate, validateTemplate, extractVariables, createTemplateContext, createStructuredResponse, } from "./templates/processor.js";
+// Export search functionality
+export { buildFileIndex, searchDocset, formatSearchResult, } from "./search/searcher.js";

package/packages/core/dist/search/searcher.d.ts

@@ -0,0 +1,53 @@
+/**
+ * File-content search for docsets.
+ *
+ * Strategy (ADR-001 Option C + optional MiniSearch pre-filter):
+ *   1. Walk the docset directory, skip binary files and ignored paths.
+ *   2. If MiniSearch is available AND the pattern looks like a plain term (no regex
+ *      metacharacters), build/retrieve a lightweight in-memory index and use it to
+ *      rank the most relevant files first — this keeps the hot path fast on large
+ *      docsets without requiring any extra dependency.
+ *   3. Stream each candidate file line by line; test against the compiled RegExp.
+ *   4. Collect up to `maxMatches` results with surrounding context lines.
+ *   5. If 0 matches and a fallbackPattern is provided, repeat with that pattern.
+ *   6. If still 0, re-run without pre-filtering (safety net for exotic regex).
+ */
+import type { SearchDocsResult, SearchOptions } from "../types.js";
+/** Opaque handle returned by {@link buildFileIndex}. */
+export interface DocsetIndex {
+    /** MiniSearch instance (null when MiniSearch could not be loaded) */
+    _ms: {
+        search(_query: string, _opts?: Record<string, unknown>): Array<{
+            id: unknown;
+            score: number;
+        }>;
+    } | null;
+    /** Absolute path to the docset root used to build this index */
+    rootPath: string;
+    /** Map from numeric doc id → absolute file path */
+    _idToPath: Map<number, string>;
+}
+/**
+ * Build an in-memory full-text index over all text files in `rootPath`.
+ * Returns a {@link DocsetIndex} regardless of whether MiniSearch is available;
+ * when it is not, the index is a no-op stub that causes the caller to fall
+ * back to a full streaming search.
+ */
+export declare function buildFileIndex(rootPath: string): Promise<DocsetIndex>;
+/**
+ * Search `rootPath` for lines matching `pattern` (a regex string).
+ *
+ * @param rootPath  Absolute path to the docset directory.
+ * @param pattern   Primary search pattern. Supports full JS regex syntax
+ *                  (e.g. `"auth|login"`, `"function\\s+\\w+"`, `"TODO.*fix"`).
+ *                  The match is always case-insensitive.
+ * @param options   Optional tuning parameters.
+ * @param index     Pre-built index for the docset. Pass one to avoid re-walking
+ *                  on repeated calls. Omit to build ad-hoc (no caching).
+ */
+export declare function searchDocset(rootPath: string, pattern: string, options?: SearchOptions, index?: DocsetIndex): Promise<SearchDocsResult>;
+/**
+ * Format a {@link SearchDocsResult} as a human-readable, grep-style text block
+ * suitable for returning as MCP tool content.
+ */
+export declare function formatSearchResult(result: SearchDocsResult): string;

package/packages/core/dist/search/searcher.js

@@ -0,0 +1,371 @@
+/**
+ * File-content search for docsets.
+ *
+ * Strategy (ADR-001 Option C + optional MiniSearch pre-filter):
+ *   1. Walk the docset directory, skip binary files and ignored paths.
+ *   2. If MiniSearch is available AND the pattern looks like a plain term (no regex
+ *      metacharacters), build/retrieve a lightweight in-memory index and use it to
+ *      rank the most relevant files first — this keeps the hot path fast on large
+ *      docsets without requiring any extra dependency.
+ *   3. Stream each candidate file line by line; test against the compiled RegExp.
+ *   4. Collect up to `maxMatches` results with surrounding context lines.
+ *   5. If 0 matches and a fallbackPattern is provided, repeat with that pattern.
+ *   6. If still 0, re-run without pre-filtering (safety net for exotic regex).
+ */
+import { createReadStream } from "node:fs";
+import { readdir, stat } from "node:fs/promises";
+import { join, relative } from "node:path";
+import { createInterface } from "node:readline";
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const DEFAULT_CONTEXT_LINES = 0;
+const DEFAULT_MAX_MATCHES = 50;
+/** Directories / files that are never useful to search inside a docset. */
+const IGNORED_NAMES = new Set([
+    "node_modules",
+    ".git",
+    "dist",
+    "build",
+    ".turbo",
+    ".cache",
+]);
+/** Files that are always skipped regardless of directory. */
+const IGNORED_FILES = new Set([".agentic-metadata.json", ".gitignore"]);
+/**
+ * Regex metacharacters that indicate the user supplied a real regex pattern.
+ * When present we skip the MiniSearch pre-filter (it would tokenise the raw
+ * pattern incorrectly) and go straight to streaming grep.
+ */
+const REGEX_META = /[.+*?^${}()|[\]\\]/;
+// ---------------------------------------------------------------------------
+// MiniSearch integration (optional, best-effort)
+// ---------------------------------------------------------------------------
+/**
+ * Lazily attempt to load MiniSearch. Returns null when the package is absent
+ * so callers can degrade gracefully without throwing.
+ */
+async function tryLoadMiniSearch() {
+    try {
+        const mod = await import("minisearch");
+        return (mod.default ??
+            mod
+                .default);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Build an in-memory full-text index over all text files in `rootPath`.
+ * Returns a {@link DocsetIndex} regardless of whether MiniSearch is available;
+ * when it is not, the index is a no-op stub that causes the caller to fall
+ * back to a full streaming search.
+ */
+export async function buildFileIndex(rootPath) {
+    const MiniSearch = await tryLoadMiniSearch();
+    if (!MiniSearch) {
+        return { _ms: null, rootPath, _idToPath: new Map() };
+    }
+    const ms = new MiniSearch({
+        fields: ["content"],
+        storeFields: [],
+    });
+    const idToPath = new Map();
+    let id = 0;
+    const batch = [];
+    for await (const absPath of walkFiles(rootPath)) {
+        const content = await readTextFile(absPath);
+        if (content === null)
+            continue; // binary or unreadable
+        batch.push({ id, content });
+        idToPath.set(id, absPath);
+        id++;
+    }
+    await ms.addAllAsync(batch);
+    return { _ms: ms, rootPath, _idToPath: idToPath };
+}
+// ---------------------------------------------------------------------------
+// Main search entry point
+// ---------------------------------------------------------------------------
+/**
+ * Search `rootPath` for lines matching `pattern` (a regex string).
+ *
+ * @param rootPath  Absolute path to the docset directory.
+ * @param pattern   Primary search pattern. Supports full JS regex syntax
+ *                  (e.g. `"auth|login"`, `"function\\s+\\w+"`, `"TODO.*fix"`).
+ *                  The match is always case-insensitive.
+ * @param options   Optional tuning parameters.
+ * @param index     Pre-built index for the docset. Pass one to avoid re-walking
+ *                  on repeated calls. Omit to build ad-hoc (no caching).
+ */
+export async function searchDocset(rootPath, pattern, options = {}, index) {
+    const contextLines = options.contextLines ?? DEFAULT_CONTEXT_LINES;
+    const maxMatches = options.maxMatches ?? DEFAULT_MAX_MATCHES;
+    // --- primary search ---
+    const primary = await runSearch(rootPath, pattern, { contextLines, maxMatches, include: options.include }, index);
+    if (primary.total_matches > 0 || !options.fallbackPattern?.trim()) {
+        return primary;
+    }
+    // --- fallback search ---
+    const fallback = await runSearch(rootPath, options.fallbackPattern.trim(), { contextLines, maxMatches, include: options.include }, index);
+    return fallback;
+}
+async function runSearch(rootPath, pattern, opts, index) {
+    let regex;
+    try {
+        regex = new RegExp(pattern, "i");
+    }
+    catch {
+        // Invalid regex: treat as literal string
+        regex = new RegExp(escapeRegex(pattern), "i");
+    }
+    // Decide which files to scan
+    const useMiniSearch = index?._ms !== null && index !== undefined && !REGEX_META.test(pattern);
+    let candidateFiles;
+    if (useMiniSearch && index) {
+        // Use MiniSearch to rank and limit candidate files
+        const results = index._ms.search(pattern, {
+            prefix: true,
+            fuzzy: 0.2,
+            combineWith: "OR",
+        });
+        // Take top 20 ranked files; fall back to all files if no results
+        if (results.length > 0) {
+            candidateFiles = results
+                .slice(0, 20)
+                .map((r) => index._idToPath.get(r.id))
+                .filter((p) => p !== undefined);
+        }
+        else {
+            // MiniSearch found nothing — walk all files
+            candidateFiles = await collectFiles(rootPath, opts.include);
+        }
+    }
+    else {
+        candidateFiles = await collectFiles(rootPath, opts.include);
+    }
+    // Stream-grep the candidate files
+    const matches = [];
+    let totalMatches = 0;
+    let searchedFiles = 0;
+    let truncated = false;
+    for (const absPath of candidateFiles) {
+        if (truncated)
+            break;
+        const relPath = relative(rootPath, absPath).replace(/\\/g, "/");
+        searchedFiles++;
+        const fileMatches = await grepFile(absPath, relPath, regex, opts.contextLines, opts.maxMatches - totalMatches);
+        totalMatches += fileMatches.length;
+        matches.push(...fileMatches);
+        if (totalMatches >= opts.maxMatches) {
+            truncated = true;
+        }
+    }
+    return {
+        matches,
+        total_matches: totalMatches,
+        searched_files: searchedFiles,
+        used_pattern: pattern,
+        truncated,
+    };
+}
+// ---------------------------------------------------------------------------
+// File walking
+// ---------------------------------------------------------------------------
+/** Recursively yield absolute paths of all non-ignored files under `dir`. */
+async function* walkFiles(dir) {
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        const absPath = join(dir, entry.name);
+        // For symlinks, stat() follows the link to get the real type.
+        // entry.isDirectory() / entry.isFile() return false for symlinks.
+        let isDir = entry.isDirectory();
+        let isFile = entry.isFile();
+        if (entry.isSymbolicLink()) {
+            try {
+                const s = await stat(absPath);
+                isDir = s.isDirectory();
+                isFile = s.isFile();
+            }
+            catch {
+                continue; // broken symlink — skip
+            }
+        }
+        if (isDir) {
+            if (!IGNORED_NAMES.has(entry.name)) {
+                yield* walkFiles(absPath);
+            }
+        }
+        else if (isFile) {
+            if (!IGNORED_FILES.has(entry.name)) {
+                yield absPath;
+            }
+        }
+    }
+}
+/** Collect all walkable file paths into an array (respects optional glob include). */
+async function collectFiles(rootPath, include) {
+    const files = [];
+    for await (const absPath of walkFiles(rootPath)) {
+        if (include && !matchGlob(absPath, include))
+            continue;
+        files.push(absPath);
+    }
+    return files;
+}
+// ---------------------------------------------------------------------------
+// Per-file grep
+// ---------------------------------------------------------------------------
+/**
+ * Read `absPath` line by line; return up to `limit` matches with context.
+ * Returns an empty array for binary files.
+ */
+async function grepFile(absPath, relPath, regex, contextLines, limit) {
+    if (limit <= 0)
+        return [];
+    // Binary detection: read first 8 KB and check for null bytes
+    if (await isBinaryFile(absPath))
+        return [];
+    const lines = [];
+    const matchIndices = []; // 0-based indices into `lines`
+    try {
+        const rl = createInterface({
+            input: createReadStream(absPath, { encoding: "utf8" }),
+            crlfDelay: Infinity,
+        });
+        for await (const line of rl) {
+            lines.push(line);
+            if (regex.test(line)) {
+                matchIndices.push(lines.length - 1);
+            }
+        }
+    }
+    catch {
+        // Unreadable file (permissions, encoding errors) — skip silently
+        return [];
+    }
+    const results = [];
+    for (const idx of matchIndices) {
+        if (results.length >= limit)
+            break;
+        const before = lines
+            .slice(Math.max(0, idx - contextLines), idx)
+            .map((l) => l.trimEnd());
+        const after = lines
+            .slice(idx + 1, idx + 1 + contextLines)
+            .map((l) => l.trimEnd());
+        results.push({
+            file: relPath,
+            line: idx + 1, // convert to 1-based
+            content: lines[idx].trimEnd(),
+            context_before: before,
+            context_after: after,
+        });
+    }
+    return results;
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/** Read a file as UTF-8 text; returns null for binary or unreadable files. */
+async function readTextFile(absPath) {
+    if (await isBinaryFile(absPath))
+        return null;
+    try {
+        const { readFile } = await import("node:fs/promises");
+        return await readFile(absPath, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Detect binary files by reading the first 8 KB and looking for a null byte.
+ * This is the same heuristic used by git and ripgrep.
+ */
+async function isBinaryFile(absPath) {
+    try {
+        const fileStat = await stat(absPath);
+        if (fileStat.size === 0)
+            return false;
+        const { open } = await import("node:fs/promises");
+        const fh = await open(absPath, "r");
+        try {
+            const buf = Buffer.alloc(Math.min(8192, fileStat.size));
+            const { bytesRead } = await fh.read(buf, 0, buf.length, 0);
+            for (let i = 0; i < bytesRead; i++) {
+                if (buf[i] === 0)
+                    return true;
+            }
+            return false;
+        }
+        finally {
+            await fh.close();
+        }
+    }
+    catch {
+        return true; // treat unreadable as binary → skip
+    }
+}
+/** Escape all regex metacharacters in a literal string. */
+function escapeRegex(s) {
+    return s.replace(/[.+*?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+ * Very lightweight glob matching supporting `*`, `**`, and `?`.
+ * Only used for the `include` file-filter option; not a full glob engine.
+ */
+function matchGlob(filePath, pattern) {
+    // Convert simple glob to regex.
+    // Use a rare Unicode placeholder (U+FFFE) to temporarily represent **
+    // so that the single-* replacement doesn't clobber it.
+    const DOUBLE_STAR = "\uFFFE";
+    const regexStr = pattern
+        .replace(/[.+^${}()|[\]\\]/g, "\\$&") // escape regex chars (not * and ?)
+        .replace(/\*\*/g, DOUBLE_STAR) // placeholder for **
+        .replace(/\*/g, "[^/]*") // * → any chars except /
+        .replace(/\?/g, "[^/]") // ? → single char except /
+        .replace(new RegExp(DOUBLE_STAR, "g"), ".*"); // ** → any chars including /
+    return new RegExp(regexStr + "$", "i").test(filePath);
+}
+// ---------------------------------------------------------------------------
+// Formatting helpers (used by the MCP server layer)
+// ---------------------------------------------------------------------------
+/**
+ * Format a {@link SearchDocsResult} as a human-readable, grep-style text block
+ * suitable for returning as MCP tool content.
+ */
+export function formatSearchResult(result) {
+    if (result.matches.length === 0) {
+        return `No matches found for pattern: ${result.used_pattern}\n(searched ${result.searched_files} file${result.searched_files === 1 ? "" : "s"})`;
+    }
+    const lines = [];
+    let currentFile = "";
+    for (const match of result.matches) {
+        if (match.file !== currentFile) {
+            if (currentFile !== "")
+                lines.push(""); // blank separator between files
+            lines.push(`==> ${match.file} <==`);
+            currentFile = match.file;
+        }
+        for (const ctx of match.context_before) {
+            lines.push(`  ${ctx}`);
+        }
+        lines.push(`${match.line}: ${match.content}`);
+        for (const ctx of match.context_after) {
+            lines.push(`  ${ctx}`);
+        }
+    }
+    const summary = [
+        ``,
+        `--- ${result.total_matches} match${result.total_matches === 1 ? "" : "es"} in ${result.searched_files} file${result.searched_files === 1 ? "" : "s"} (pattern: "${result.used_pattern}")${result.truncated ? ` [truncated at ${DEFAULT_MAX_MATCHES}]` : ""}`,
+    ];
+    return [...lines, ...summary].join("\n");
+}

package/packages/core/dist/types.d.ts

@@ -85,6 +85,7 @@ export interface SearchDocsParams {
 }
 /**
  * Response from the search_docs tool
+ * @deprecated Use SearchDocsResult for actual search results
  */
 export interface SearchDocsResponse {
     /** Instructions for the agent on how to search */
@@ -96,6 +97,55 @@ export interface SearchDocsResponse {
     /** The calculated local path for searching */
     path: string;
 }
+/**
+ * A single line match from a file search
+ */
+export interface SearchMatch {
+    /** Path to the file, relative to the docset root */
+    file: string;
+    /** 1-based line number of the match */
+    line: number;
+    /** The full content of the matched line (trimmed) */
+    content: string;
+    /** Lines immediately before the match (up to contextLines lines) */
+    context_before: string[];
+    /** Lines immediately after the match (up to contextLines lines) */
+    context_after: string[];
+}
+/**
+ * Result returned by the search_docs tool when performing an actual search
+ */
+export interface SearchDocsResult {
+    /** All matched lines across all searched files */
+    matches: SearchMatch[];
+    /** Total number of matches found (may be higher than matches.length if truncated) */
+    total_matches: number;
+    /** Number of files inspected during the search */
+    searched_files: number;
+    /** The pattern that was actually used (may differ from input if fallback was triggered) */
+    used_pattern: string;
+    /** True when results were capped at the maximum match limit */
+    truncated: boolean;
+}
+/**
+ * Options controlling search behaviour
+ */
+export interface SearchOptions {
+    /**
+     * Fallback pattern used when the primary pattern yields no results.
+     * Typically the value of the `generalized_keywords` tool parameter.
+     */
+    fallbackPattern?: string;
+    /** Number of context lines to include before and after each match (default: 2) */
+    contextLines?: number;
+    /** Maximum number of matches to return before truncating (default: 50) */
+    maxMatches?: number;
+    /**
+     * Glob-style pattern to restrict which files are searched (e.g. "*.md", "*.{ts,js}").
+     * When omitted all non-binary files are searched.
+     */
+    include?: string;
+}
 /**
  * Response from the list_docsets tool
  */

package/packages/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codemcp/knowledge-core",
-  "version": "1.5.0",
+  "version": "1.6.1",
   "description": "Core functionality for agentic knowledge guidance system",
   "type": "module",
   "main": "dist/index.js",
@@ -29,7 +29,8 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "js-yaml": "^4.1.0"
+    "js-yaml": "^4.1.0",
+    "minisearch": "^7.1.2"
   },
   "devDependencies": {
     "@eslint/js": "^9.34.0",

package/packages/mcp-server/dist/server.js

@@ -4,10 +4,18 @@
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
-import { loadConfig, findConfigPath, calculateLocalPath, processTemplate, createTemplateContext, getEffectiveTemplate, createStructuredResponse, ConfigManager, ensureKnowledgeGitignoreSync, } from "@codemcp/knowledge-core";
+import { loadConfig, findConfigPath, calculateLocalPath, ConfigManager, ensureKnowledgeGitignoreSync, buildFileIndex, searchDocset, formatSearchResult, } from "@codemcp/knowledge-core";
 import { initDocset } from "@codemcp/knowledge-content-loader";
 import { existsSync } from "node:fs";
 import { resolve, dirname } from "node:path";
+/** Shared keywords parameter description advertised to agents */
+const KEYWORDS_DESCRIPTION = "Primary search terms or concepts you're looking for. " +
+    'Supports full regex syntax (e.g. "log.*Error", "function\\s+\\w+", "auth|login"). ' +
+    "Returns file path, line number, matched line, and surrounding context lines. " +
+    'Be specific: "authentication middleware", "useData hook", "sidebar.items".';
+const GENERALIZED_KEYWORDS_DESCRIPTION = "Broader synonyms or related terms used as a fallback when the primary keywords " +
+    'return no results (e.g. for "authentication" you might include "login|signin|oauth"). ' +
+    "Also supports regex syntax.";
 /**
  * Create an agentic knowledge MCP server
  * @returns MCP server instance
@@ -25,6 +33,8 @@ export function createAgenticKnowledgeServer() {
     let configCache = null;
     let configLoadTime = 0;
     const CONFIG_CACHE_TTL = 60000; // 1 minute cache
+    // Per-docset search index cache (keyed by docset id)
+    const indexCache = new Map();
     /**
      * Load configuration with caching (returns null if no config found)
      */
@@ -55,6 +65,35 @@ export function createAgenticKnowledgeServer() {
             return null;
         }
     }
+    /**
+     * Resolve the absolute local path for an initialized docset.
+     * Throws if the docset has not been initialized yet.
+     */
+    function resolveDocsetPath(docset, configPath) {
+        const primarySource = docset.sources?.[0];
+        const configDir = dirname(configPath);
+        if (primarySource?.type === "local_folder") {
+            const symlinkDir = resolve(configDir, "docsets", docset.id);
+            const metadataPath = resolve(symlinkDir, ".agentic-metadata.json");
+            if (!existsSync(metadataPath)) {
+                throw new Error(`Docset '${docset.id}' hasn't been initialized yet.`);
+            }
+            return symlinkDir;
+        }
+        if (primarySource?.type === "git_repo" ||
+            primarySource?.type === "archive") {
+            const localRelPath = calculateLocalPath(docset, configPath);
+            const projectRoot = dirname(configDir);
+            const absolutePath = resolve(projectRoot, localRelPath);
+            const metadataPath = resolve(absolutePath, ".agentic-metadata.json");
+            if (!existsSync(metadataPath)) {
+                throw new Error(`Docset '${docset.id}' hasn't been initialized yet.`);
+            }
+            return absolutePath;
+        }
+        // Fallback — unknown source type, no initialization check
+        return resolve(dirname(configDir), calculateLocalPath(docset, configPath));
+    }
     // Register tool handlers
     server.setRequestHandler(ListToolsRequestSchema, async () => {
         // Load configuration to get available docsets
@@ -65,7 +104,7 @@ export function createAgenticKnowledgeServer() {
                 tools: [
                     {
                         name: "search_docs",
-                        description: `Search for documentation in configured docsets. Returns structured response with search instructions and parameters.
+                        description: `Search for documentation in configured docsets. Returns file path, line number, matched content, and surrounding context.
 
 ⚠️ **NO DOCSETS CONFIGURED**
 
@@ -109,11 +148,11 @@ After configuring, the tool will show available docsets here.`,
                                 },
                                 keywords: {
                                     type: "string",
-                                    description: 'Primary search terms or concepts you\'re looking for. Be specific about what you want to find (e.g., "authentication middleware", "user validation", "API rate limiting").',
+                                    description: KEYWORDS_DESCRIPTION,
                                 },
                                 generalized_keywords: {
                                     type: "string",
-                                    description: "Related terms, synonyms, or contextual keywords that may appear alongside your primary keywords but are not your main target.",
+                                    description: GENERALIZED_KEYWORDS_DESCRIPTION,
                                 },
                             },
                             required: ["docset_id", "keywords"],
@@ -161,11 +200,8 @@ After configuring, the tool will show available docsets here.`,
             return `• **${docset.id}** (${docset.name})${description}`;
         })
             .join("\n");
-        const searchDocsDescription = `Search for documentation in available docsets. Returns structured response with search instructions and parameters.
-
-📚 **AVAILABLE DOCSETS:**
-${docsetInfo}
-`;
+        const searchDocsDescription = `Search for documentation in available docsets. Returns file path, line number, matched content, and surrounding context lines.\n\n` +
+            `📚 **AVAILABLE DOCSETS:**\n${docsetInfo}`;
         return {
             tools: [
                 {
@@ -181,11 +217,16 @@ ${docsetInfo}
                             },
                             keywords: {
                                 type: "string",
-                                description: 'Primary search terms or concepts you\'re looking for. Be specific about what you want to find (e.g., "authentication middleware", "user validation", "API rate limiting"). Include the exact terms you expect to appear in the documentation.',
+                                description: KEYWORDS_DESCRIPTION,
                             },
                             generalized_keywords: {
                                 type: "string",
-                                description: 'Related terms, synonyms, or contextual keywords that may appear alongside your primary keywords but are not your main target. These help broaden the search context and catch relevant content that might use different terminology (e.g., for "authentication" you might include "login, signin, oauth, credentials, tokens"). Think of terms that would appear in the same sections or discussions as your main keywords.',
+                                description: GENERALIZED_KEYWORDS_DESCRIPTION,
+                            },
+                            context_lines: {
+                                type: "number",
+                                description: "Number of lines to show before and after each matching line (default: 0). " +
+                                    "Increase to 1–3 when you need surrounding context to understand a match.",
                             },
                         },
                         required: ["docset_id", "keywords"],
@@ -232,7 +273,7 @@ ${config.docsets.map((d) => `• **${d.id}** (${d.name})`).join("\n")}`,
         try {
             switch (name) {
                 case "search_docs": {
-                    const { docset_id, keywords, generalized_keywords } = args;
+                    const { docset_id, keywords, generalized_keywords, context_lines } = args;
                     // Validate required parameters
                     if (!docset_id || typeof docset_id !== "string") {
                         throw new Error("docset_id is required and must be a string");
@@ -257,52 +298,27 @@ ${config.docsets.map((d) => `• **${d.id}** (${d.name})`).join("\n")}`,
                     const docset = config.docsets.find((d) => d.id === docset_id);
                     if (!docset) {
                         const availableIds = config.docsets.map((d) => d.id).join(", ");
-                        throw new Error(`Docset '${docset_id}' not found.\n\n` +
-                            `Available docsets: ${availableIds}\n\n`);
-                    }
-                    // Determine path calculation method and validate initialization
-                    const primarySource = docset.sources?.[0];
-                    let localPath;
-                    if (primarySource?.type === "local_folder") {
-                        // For local folders, use symlinked path
-                        localPath = calculateLocalPath(docset, configPath);
-                        // Check if initialized by verifying .agentic-metadata.json exists
-                        const configDir = dirname(configPath);
-                        const symlinkDir = resolve(configDir, "docsets", docset.id);
-                        const metadataPath = resolve(symlinkDir, ".agentic-metadata.json");
-                        if (!existsSync(metadataPath)) {
-                            throw new Error(`Docset '${docset_id}' hasn't been initialized yet.`);
-                        }
-                        // Return the symlinked path for consistency
-                        localPath = resolve(configDir, "docsets", docset.id);
-                        const projectRoot2 = dirname(configDir);
-                        localPath = resolve(projectRoot2, localPath).replace(projectRoot2 + "/", "");
-                    }
-                    else if (primarySource?.type === "git_repo") {
-                        // For git repos, use standard path calculation
-                        localPath = calculateLocalPath(docset, configPath);
-                        // Check if .agentic-metadata.json exists
-                        const configDir = dirname(configPath);
-                        const projectRoot = dirname(configDir);
-                        const absolutePath = resolve(projectRoot, localPath);
-                        const metadataPath = resolve(absolutePath, ".agentic-metadata.json");
-                        if (!existsSync(metadataPath)) {
-                            throw new Error(`Docset '${docset_id}' hasn't been initialized yet.\n\n`);
-                        }
+                        throw new Error(`Docset '${docset_id}' not found.\n\nAvailable docsets: ${availableIds}`);
                     }
-                    else {
-                        // Fallback to standard calculation for unknown types
-                        localPath = calculateLocalPath(docset, configPath);
+                    // Resolve the absolute local path (also validates initialization)
+                    const absoluteLocalPath = resolveDocsetPath(docset, configPath);
+                    // Get or build the search index for this docset
+                    let index = indexCache.get(docset_id);
+                    if (!index) {
+                        index = await buildFileIndex(absoluteLocalPath);
+                        indexCache.set(docset_id, index);
                     }
-                    // Create template context with proper function signature
-                    const templateContext = createTemplateContext(localPath, keywords.trim(), (generalized_keywords || "").trim(), docset);
-                    // Get effective template and process it
-                    const effectiveTemplate = getEffectiveTemplate(docset, config.template);
-                    const instructions = processTemplate(effectiveTemplate, templateContext);
-                    // Create structured response
-                    const structuredResponse = createStructuredResponse(instructions, keywords.trim(), (generalized_keywords || "").trim(), localPath);
+                    // Perform the search
+                    const fallbackPattern = generalized_keywords?.trim();
+                    const searchOptions = {};
+                    if (fallbackPattern)
+                        searchOptions.fallbackPattern = fallbackPattern;
+                    if (typeof context_lines === "number")
+                        searchOptions.contextLines = context_lines;
+                    const result = await searchDocset(absoluteLocalPath, keywords.trim(), searchOptions, index);
+                    const text = formatSearchResult(result);
                     return {
-                        structuredContent: structuredResponse,
+                        content: [{ type: "text", text }],
                     };
                 }
                 case "list_docsets": {
@@ -380,9 +396,11 @@ ${config.docsets.map((d) => `• **${d.id}** (${d.name})`).join("\n")}`,
                     }
                     const configManager = new ConfigManager();
                     const { config, configPath } = await configManager.loadConfig(process.cwd());
-                    // Invalidate cache so the next search_docs call sees the new state
+                    // Invalidate config cache and search index cache so the next
+                    // search_docs call sees the newly initialized content
                     configCache = null;
                     configLoadTime = 0;
+                    indexCache.delete(docset_id);
                     ensureKnowledgeGitignoreSync(configPath);
                     const docset = config.docsets.find((d) => d.id === docset_id);
                     if (!docset) {

package/packages/mcp-server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codemcp/knowledge",
-  "version": "1.5.0",
+  "version": "1.6.1",
   "description": "MCP server implementation for agentic knowledge guidance system",
   "type": "module",
   "main": "dist/index.js",