@liendev/lien 0.23.0 → 0.25.0

package/README.md

@@ -4,7 +4,7 @@
 
 **Give AI deep understanding of your codebase through semantic search. 100% local, 100% private.**
 
-Lien connects AI coding assistants like Cursor to your codebase through the Model Context Protocol (MCP). Ask questions in natural language, get precise answers from semantic search—all running locally on your machine.
+Lien connects AI coding assistants like Cursor and Claude Code to your codebase through the Model Context Protocol (MCP). Ask questions in natural language, get precise answers from semantic search—all running locally on your machine.
 
 📚 **[Full Documentation](https://lien.dev)** | 🚀 **[Getting Started](https://lien.dev/guide/getting-started)** | 🔍 **[How It Works](https://lien.dev/how-it-works)**
 
@@ -15,7 +15,7 @@ Lien connects AI coding assistants like Cursor to your codebase through the Mode
 - 🔒 **100% Local & Private** - All code analysis happens on your machine
 - 🚀 **Semantic Search** - Natural language queries: "How does authentication work?"
 - 🌐 **Cross-Repo Search** - Search across all repositories in your organization (Qdrant backend)
-- 🎯 **MCP Integration** - Works seamlessly with Cursor and other MCP-compatible tools
+- 🎯 **MCP Integration** - Works seamlessly with Cursor, Claude Code, and other MCP-compatible tools
 - ⚡ **Fast** - Sub-500ms queries, minutes to index large codebases
 - 🆓 **Free Forever** - No API costs, no subscriptions, no usage limits
 - 📦 **Framework-Aware** - Auto-detects Node.js, Laravel, Shopify; supports 15+ languages
@@ -26,15 +26,10 @@ Lien connects AI coding assistants like Cursor to your codebase through the Mode
 ## Quick Start
 
 ```bash
-# Install
+# 1. Install
 npm install -g @liendev/lien
 
-# Setup in your project
-cd /path/to/your/project
-lien init
-lien index
-
-# Configure Cursor - create .cursor/mcp.json
+# 2. Add to your project - create .cursor/mcp.json
 {
   "mcpServers": {
     "lien": {
@@ -44,9 +39,11 @@ lien index
   }
 }
 
-# Restart Cursor and start asking questions!
+# 3. Restart your AI assistant (Cursor, Claude Code) and start asking questions!
 ```
 
+That's it—zero configuration needed. Lien auto-detects your project and indexes on first use.
+
 **👉 [Full installation guide](https://lien.dev/guide/installation)**
 
 ### Qdrant Backend (Cross-Repo Search)
@@ -102,7 +99,7 @@ Lien tracks code complexity with intuitive outputs:
 ## Documentation
 
 - **[Installation](https://lien.dev/guide/installation)** - npm, npx, or local setup
-- **[Getting Started](https://lien.dev/guide/getting-started)** - Step-by-step configuration for Cursor
+- **[Getting Started](https://lien.dev/guide/getting-started)** - Step-by-step configuration for Cursor or Claude Code
 - **[Configuration](https://lien.dev/guide/configuration)** - Customize indexing, thresholds, performance
 - **[CLI Commands](https://lien.dev/guide/cli-commands)** - Full command reference
 - **[MCP Tools](https://lien.dev/guide/mcp-tools)** - Complete API reference for all 6 tools

package/dist/index.js

@@ -3591,15 +3591,13 @@ var require_dist = __commonJS({
 // src/cli/index.ts
 import { Command } from "commander";
 import { createRequire as createRequire3 } from "module";
-import { fileURLToPath as fileURLToPath4 } from "url";
+import { fileURLToPath as fileURLToPath3 } from "url";
 import { dirname as dirname3, join as join3 } from "path";
 
 // src/cli/init.ts
 import fs from "fs/promises";
 import path from "path";
-import { fileURLToPath as fileURLToPath2 } from "url";
 import chalk2 from "chalk";
-import inquirer from "inquirer";
 
 // src/utils/banner.ts
 import figlet from "figlet";
@@ -3661,8 +3659,6 @@ function showCompactBanner() {
 }
 
 // src/cli/init.ts
-var __filename2 = fileURLToPath2(import.meta.url);
-var __dirname2 = path.dirname(__filename2);
 async function initCommand(options = {}) {
   showCompactBanner();
   console.log(chalk2.bold("\nLien Initialization\n"));
@@ -3695,129 +3691,6 @@ async function initCommand(options = {}) {
     console.log(chalk2.dim("  You can safely delete it."));
   } catch {
   }
-  await promptAndInstallCursorRules(rootDir, options);
-}
-async function getPathType(filepath) {
-  try {
-    const stats = await fs.stat(filepath);
-    if (stats.isDirectory()) return "directory";
-    if (stats.isFile()) return "file";
-    return "other";
-  } catch {
-    return "none";
-  }
-}
-async function convertRulesFileToDirectory(rulesPath, templatePath) {
-  const existingRules = await fs.readFile(rulesPath, "utf-8");
-  const parentDir = path.dirname(rulesPath);
-  const baseName = path.basename(rulesPath);
-  const tempDir = await fs.mkdtemp(path.join(parentDir, baseName + "_tmp_"));
-  const backupPath = rulesPath + ".backup";
-  try {
-    await fs.writeFile(path.join(tempDir, "project.mdc"), existingRules);
-    await fs.copyFile(templatePath, path.join(tempDir, "lien.mdc"));
-    try {
-      await fs.unlink(backupPath);
-    } catch {
-    }
-    await fs.rename(rulesPath, backupPath);
-    try {
-      await fs.rename(tempDir, rulesPath);
-      try {
-        await fs.unlink(backupPath);
-      } catch {
-        console.log(chalk2.yellow("\u26A0\uFE0F  Could not remove backup file, but conversion succeeded"));
-        console.log(chalk2.dim(`Backup file: ${backupPath}`));
-      }
-    } catch (renameErr) {
-      try {
-        await fs.rename(backupPath, rulesPath);
-      } catch (restoreErr) {
-        console.log(chalk2.red("\u274C Failed to restore original .cursor/rules from backup after failed conversion."));
-        console.log(chalk2.red(`   - Original error: ${renameErr instanceof Error ? renameErr.message : renameErr}`));
-        console.log(chalk2.red(`   - Restore error: ${restoreErr instanceof Error ? restoreErr.message : restoreErr}`));
-        console.log(chalk2.red(`   - Backup file location: ${backupPath}`));
-        throw new Error("Failed to convert .cursor/rules to directory and failed to restore from backup. Manual recovery needed.");
-      }
-      throw renameErr;
-    }
-    console.log(chalk2.green("\u2713 Converted .cursor/rules to directory"));
-    console.log(chalk2.green("  - Your project rules: .cursor/rules/project.mdc"));
-    console.log(chalk2.green("  - Lien rules: .cursor/rules/lien.mdc"));
-  } catch (err) {
-    try {
-      await fs.rm(tempDir, { recursive: true, force: true });
-    } catch {
-    }
-    throw err;
-  }
-}
-async function handleExistingRulesDirectory(rulesPath, templatePath) {
-  const targetPath = path.join(rulesPath, "lien.mdc");
-  try {
-    await fs.access(targetPath);
-    console.log(chalk2.dim("lien.mdc already exists in .cursor/rules/, skipping..."));
-    return;
-  } catch {
-  }
-  await fs.copyFile(templatePath, targetPath);
-  console.log(chalk2.green("\u2713 Installed Cursor rules as .cursor/rules/lien.mdc"));
-}
-async function handleExistingRulesFile(rulesPath, templatePath, options) {
-  if (options.yes) {
-    console.log(chalk2.dim("Skipped Cursor rules installation (preserving existing .cursor/rules file)"));
-    return;
-  }
-  const { convertToDir } = await inquirer.prompt([{
-    type: "confirm",
-    name: "convertToDir",
-    message: "Existing .cursor/rules file found. Convert to directory and preserve your rules?",
-    default: true
-  }]);
-  if (convertToDir) {
-    await convertRulesFileToDirectory(rulesPath, templatePath);
-  } else {
-    console.log(chalk2.dim("Skipped Cursor rules installation (preserving existing file)"));
-  }
-}
-async function handleInvalidRulesPath() {
-  console.log(chalk2.yellow("\u26A0\uFE0F  .cursor/rules exists but is not a regular file or directory"));
-  console.log(chalk2.dim("Skipped Cursor rules installation"));
-}
-async function handleFreshRulesInstall(rulesPath, templatePath) {
-  await fs.mkdir(rulesPath, { recursive: true });
-  await fs.copyFile(templatePath, path.join(rulesPath, "lien.mdc"));
-  console.log(chalk2.green("\u2713 Installed Cursor rules as .cursor/rules/lien.mdc"));
-}
-async function installCursorRulesFiles(rootDir, options) {
-  const cursorRulesDir = path.join(rootDir, ".cursor");
-  await fs.mkdir(cursorRulesDir, { recursive: true });
-  const templatePath = path.join(__dirname2, "../CURSOR_RULES_TEMPLATE.md");
-  const rulesPath = path.join(cursorRulesDir, "rules");
-  const pathType = await getPathType(rulesPath);
-  const handlers = {
-    directory: () => handleExistingRulesDirectory(rulesPath, templatePath),
-    file: () => handleExistingRulesFile(rulesPath, templatePath, options),
-    other: () => handleInvalidRulesPath(),
-    none: () => handleFreshRulesInstall(rulesPath, templatePath)
-  };
-  await handlers[pathType]();
-}
-async function promptAndInstallCursorRules(rootDir, options) {
-  const shouldInstall = options.yes || (await inquirer.prompt([{
-    type: "confirm",
-    name: "installCursorRules",
-    message: "Install recommended Cursor rules?",
-    default: true
-  }])).installCursorRules;
-  if (!shouldInstall) return;
-  try {
-    await installCursorRulesFiles(rootDir, options);
-  } catch (error) {
-    console.log(chalk2.yellow("\u26A0\uFE0F  Could not install Cursor rules"));
-    console.log(chalk2.dim(`Error: ${error instanceof Error ? error.message : "Unknown error"}`));
-    console.log(chalk2.dim("You can manually copy CURSOR_RULES_TEMPLATE.md to .cursor/rules/lien.mdc"));
-  }
 }
 
 // src/cli/status.ts
@@ -4119,7 +3992,7 @@ import path4 from "path";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { createRequire as createRequire2 } from "module";
-import { fileURLToPath as fileURLToPath3 } from "url";
+import { fileURLToPath as fileURLToPath2 } from "url";
 import { dirname as dirname2, join as join2 } from "path";
 import {
   LocalEmbeddings,
@@ -8419,11 +8292,17 @@ var SemanticSearchSchema = external_exports.object({
 
 // src/mcp/schemas/similarity.schema.ts
 var FindSimilarSchema = external_exports.object({
-  code: external_exports.string().min(10, "Code snippet must be at least 10 characters").describe(
+  code: external_exports.string().min(24, "Code snippet must be at least 24 characters").describe(
     "Code snippet to find similar implementations for.\n\nProvide a representative code sample that demonstrates the pattern you want to find similar examples of in the codebase."
   ),
   limit: external_exports.number().int().min(1, "Limit must be at least 1").max(20, "Limit cannot exceed 20").default(5).describe(
     "Number of similar code blocks to return.\n\nDefault: 5"
+  ),
+  language: external_exports.string().min(1, "Language filter cannot be empty").optional().describe(
+    "Filter by programming language.\n\nExamples: 'typescript', 'python', 'javascript', 'php'\n\nIf omitted, searches all languages."
+  ),
+  pathHint: external_exports.string().min(1, "Path hint cannot be empty").optional().describe(
+    "Filter by file path substring.\n\nOnly returns results where the file path contains this string (case-insensitive).\n\nExamples: 'src/api', 'components', 'utils'"
   )
 });
 
@@ -8487,7 +8366,7 @@ var tools = [
   toMCPToolSchema(
     SemanticSearchSchema,
     "semantic_search",
-    `Search codebase by MEANING, not text. USE THIS INSTEAD OF grep/ripgrep for finding implementations, features, or understanding how code works.
+    `Search codebase by MEANING, not text. Complements grep - use this for discovery and understanding, grep for exact matches.
 
 Examples:
 - "Where is authentication handled?" \u2192 semantic_search({ query: "handles user authentication" })
@@ -8505,7 +8384,13 @@ Results include a relevance category (highly_relevant, relevant, loosely_related
 - Finding duplicate implementations
 - Refactoring similar patterns together
 
-Provide at least 10 characters of code to match against. Results include a relevance category for each match.`
+Provide at least 24 characters of code to match against. Results include a relevance category for each match.
+
+Optional filters:
+- language: Filter by programming language (e.g., "typescript", "python")
+- pathHint: Filter by file path substring (e.g., "src/api", "components")
+
+Low-relevance results (not_relevant) are automatically pruned.`
   ),
   toMCPToolSchema(
     GetFilesContextSchema,
@@ -8703,6 +8588,19 @@ async function handleSemanticSearch(args, ctx) {
 }
 
 // src/mcp/handlers/find-similar.ts
+function applyLanguageFilter(results, language) {
+  const lang = language.toLowerCase();
+  return results.filter((r) => r.metadata.language?.toLowerCase() === lang);
+}
+function applyPathHintFilter(results, pathHint) {
+  const hint = pathHint.toLowerCase();
+  return results.filter((r) => (r.metadata.file?.toLowerCase() ?? "").includes(hint));
+}
+function pruneIrrelevantResults(results) {
+  const beforePrune = results.length;
+  const filtered = results.filter((r) => r.relevance !== "not_relevant");
+  return { filtered, prunedCount: beforePrune - filtered.length };
+}
 async function handleFindSimilar(args, ctx) {
   const { vectorDB, embeddings, log, checkAndReconnect, getIndexMetadata } = ctx;
   return await wrapToolHandler(
@@ -8711,11 +8609,27 @@ async function handleFindSimilar(args, ctx) {
       log(`Finding similar code...`);
       await checkAndReconnect();
       const codeEmbedding = await embeddings.embed(validatedArgs.code);
-      const results = await vectorDB.search(codeEmbedding, validatedArgs.limit, validatedArgs.code);
-      log(`Found ${results.length} similar chunks`);
+      const limit = validatedArgs.limit ?? 5;
+      const extraLimit = limit + 10;
+      let results = await vectorDB.search(codeEmbedding, extraLimit, validatedArgs.code);
+      const filtersApplied = { prunedLowRelevance: 0 };
+      if (validatedArgs.language) {
+        filtersApplied.language = validatedArgs.language;
+        results = applyLanguageFilter(results, validatedArgs.language);
+      }
+      if (validatedArgs.pathHint) {
+        filtersApplied.pathHint = validatedArgs.pathHint;
+        results = applyPathHintFilter(results, validatedArgs.pathHint);
+      }
+      const { filtered, prunedCount } = pruneIrrelevantResults(results);
+      filtersApplied.prunedLowRelevance = prunedCount;
+      const finalResults = filtered.slice(0, limit);
+      log(`Found ${finalResults.length} similar chunks`);
+      const hasFilters = filtersApplied.language || filtersApplied.pathHint || filtersApplied.prunedLowRelevance > 0;
       return {
         indexInfo: getIndexMetadata(),
-        results
+        results: finalResults,
+        ...hasFilters && { filtersApplied }
       };
     }
   )(args);
@@ -8938,6 +8852,25 @@ async function handleGetFilesContext(args, ctx) {
 }
 
 // src/mcp/handlers/list-functions.ts
+async function performContentScan(vectorDB, args, log) {
+  log("Falling back to content scan...");
+  let results = await vectorDB.scanWithFilter({
+    language: args.language,
+    limit: 200
+    // Fetch more, we'll filter by symbolName
+  });
+  if (args.pattern) {
+    const regex = new RegExp(args.pattern, "i");
+    results = results.filter((r) => {
+      const symbolName = r.metadata?.symbolName;
+      return symbolName && regex.test(symbolName);
+    });
+  }
+  return {
+    results: results.slice(0, 50),
+    method: "content"
+  };
+}
 async function handleListFunctions(args, ctx) {
   const { vectorDB, log, checkAndReconnect, getIndexMetadata } = ctx;
   return await wrapToolHandler(
@@ -8945,38 +8878,29 @@ async function handleListFunctions(args, ctx) {
     async (validatedArgs) => {
       log("Listing functions with symbol metadata...");
       await checkAndReconnect();
-      let results;
-      let usedMethod = "symbols";
+      let queryResult;
       try {
-        results = await vectorDB.querySymbols({
+        const results = await vectorDB.querySymbols({
           language: validatedArgs.language,
           pattern: validatedArgs.pattern,
           limit: 50
         });
         if (results.length === 0 && (validatedArgs.language || validatedArgs.pattern)) {
           log("No symbol results, falling back to content scan...");
-          results = await vectorDB.scanWithFilter({
-            language: validatedArgs.language,
-            pattern: validatedArgs.pattern,
-            limit: 50
-          });
-          usedMethod = "content";
+          queryResult = await performContentScan(vectorDB, validatedArgs, log);
+        } else {
+          queryResult = { results, method: "symbols" };
         }
       } catch (error) {
-        log(`Symbol query failed, falling back to content scan: ${error}`);
-        results = await vectorDB.scanWithFilter({
-          language: validatedArgs.language,
-          pattern: validatedArgs.pattern,
-          limit: 50
-        });
-        usedMethod = "content";
+        log(`Symbol query failed: ${error}`);
+        queryResult = await performContentScan(vectorDB, validatedArgs, log);
       }
-      log(`Found ${results.length} matches using ${usedMethod} method`);
+      log(`Found ${queryResult.results.length} matches using ${queryResult.method} method`);
       return {
         indexInfo: getIndexMetadata(),
-        method: usedMethod,
-        results,
-        note: usedMethod === "content" ? 'Using content search. Run "lien reindex" to enable faster symbol-based queries.' : void 0
+        method: queryResult.method,
+        results: queryResult.results,
+        note: queryResult.method === "content" ? 'Using content search. Run "lien reindex" to enable faster symbol-based queries.' : void 0
       };
     }
   )(args);
@@ -9377,14 +9301,14 @@ function registerMCPHandlers(server, toolContext, log) {
 }
 
 // src/mcp/server.ts
-var __filename3 = fileURLToPath3(import.meta.url);
-var __dirname3 = dirname2(__filename3);
+var __filename2 = fileURLToPath2(import.meta.url);
+var __dirname2 = dirname2(__filename2);
 var require3 = createRequire2(import.meta.url);
 var packageJson2;
 try {
-  packageJson2 = require3(join2(__dirname3, "../package.json"));
+  packageJson2 = require3(join2(__dirname2, "../package.json"));
 } catch {
-  packageJson2 = require3(join2(__dirname3, "../../package.json"));
+  packageJson2 = require3(join2(__dirname2, "../../package.json"));
 }
 async function initializeDatabase(rootDir, log) {
   const embeddings = new LocalEmbeddings();
@@ -9719,14 +9643,14 @@ async function complexityCommand(options) {
 }
 
 // src/cli/index.ts
-var __filename4 = fileURLToPath4(import.meta.url);
-var __dirname4 = dirname3(__filename4);
+var __filename3 = fileURLToPath3(import.meta.url);
+var __dirname3 = dirname3(__filename3);
 var require4 = createRequire3(import.meta.url);
 var packageJson3;
 try {
-  packageJson3 = require4(join3(__dirname4, "../package.json"));
+  packageJson3 = require4(join3(__dirname3, "../package.json"));
 } catch {
-  packageJson3 = require4(join3(__dirname4, "../../package.json"));
+  packageJson3 = require4(join3(__dirname3, "../../package.json"));
 }
 var program = new Command();
 program.name("lien").description("Local semantic code search for AI assistants via MCP").version(packageJson3.version);