[MLsys2026 Best Paper]: https://arxiv.org/abs/2506.08276. RAG on Everything with LEANN. Enjoy 97% storage savings while running a fast, accurate, and 100% private RAG application on your personal device.
Python aifaissgpt-osslangchainllama-indexllmlocalstorageoffline-firstollamaprivacypythonragretrieval-augmented-generationvector-databasevector-searchvectors
feat: improve MCP server with build, status tools and structured search output
yichuan520030910320c5f2b693cba3
diff --git a/packages/leann-core/src/leann/cli.py b/packages/leann-core/src/leann/cli.pyindex 5a178f9..3b6ed11 100644--- a/packages/leann-core/src/leann/cli.py+++ b/packages/leann-core/src/leann/cli.py@@ -2540,7 +2540,7 @@ Examples:json_results = [{"id": r.id,- "score": r.score,+ "score": float(r.score),"text": r.text,"metadata": r.metadata,}diff --git a/packages/leann-core/src/leann/mcp.py b/packages/leann-core/src/leann/mcp.pyindex 8ccde94..dc1fe0d 100755--- a/packages/leann-core/src/leann/mcp.py+++ b/packages/leann-core/src/leann/mcp.py@@ -5,138 +5,331 @@ import subprocessimport sys+def _run_leann(*args, timeout=120):+ """Run a leann CLI command and return (returncode, stdout, stderr)."""+ result = subprocess.run(+ ["leann", *args],+ capture_output=True,+ text=True,+ timeout=timeout,+ )+ return result.returncode, result.stdout, result.stderr+++def _make_result(request_id, content_text):+ return {+ "jsonrpc": "2.0",+ "id": request_id,+ "result": {"content": [{"type": "text", "text": content_text}]},+ }+++def _make_error(request_id, message):+ return {+ "jsonrpc": "2.0",+ "id": request_id,+ "error": {"code": -1, "message": message},+ }+++TOOLS = [+ {+ "name": "leann_search",+ "description": (+ "Semantic code search across an indexed codebase. Returns matching code "+ "chunks with file paths, scores, and surrounding context.\n\n"+ "Use this to find relevant code before making changes — understand existing "+ "patterns, locate implementations, and discover related files.\n\n"+ "Examples: 'authentication middleware', 'database connection pooling', "+ "'error handling in API routes', 'how are embeddings computed'"+ ),+ "inputSchema": {+ "type": "object",+ "properties": {+ "index_name": {+ "type": "string",+ "description": "Name of the LEANN index to search. Use leann_list to see available indexes.",+ },+ "query": {+ "type": "string",+ "description": "Natural language or technical search query.",+ },+ "top_k": {+ "type": "integer",+ "default": 5,+ "minimum": 1,+ "maximum": 20,+ "description": "Number of results to return (default 5).",+ },+ "complexity": {+ "type": "integer",+ "default": 32,+ "minimum": 16,+ "maximum": 128,+ "description": "Search precision level (default 32, use 64+ for thorough search).",+ },+ },+ "required": ["index_name", "query"],+ },+ },+ {+ "name": "leann_list",+ "description": "List all available LEANN indexes across projects. Shows index names, status, size, and location.",+ "inputSchema": {"type": "object", "properties": {}},+ },+ {+ "name": "leann_build",+ "description": (+ "Build or incrementally update a LEANN index for a codebase. "+ "If the index already exists, only new/modified/deleted files are processed "+ "(incremental update). Use this to keep the index current after code changes.\n\n"+ "Provide file paths or directories to index. For git repos, pass the output "+ "of 'git ls-files' as individual paths."+ ),+ "inputSchema": {+ "type": "object",+ "properties": {+ "index_name": {+ "type": "string",+ "description": "Name for the index (e.g., 'my-project'). Defaults to current directory name if omitted.",+ },+ "docs": {+ "type": "array",+ "items": {"type": "string"},+ "description": "List of file paths or directories to index.",+ },+ "backend_name": {+ "type": "string",+ "enum": ["hnsw", "ivf"],+ "default": "ivf",+ "description": "Index backend. 'ivf' supports incremental updates (recommended). 'hnsw' is faster for search but limited incremental support.",+ },+ "force": {+ "type": "boolean",+ "default": False,+ "description": "Force full rebuild instead of incremental update.",+ },+ },+ "required": ["docs"],+ },+ },+ {+ "name": "leann_status",+ "description": (+ "Show detailed status of a LEANN index: backend type, embedding model, "+ "number of chunks, file count, index size, and whether the index is up to date."+ ),+ "inputSchema": {+ "type": "object",+ "properties": {+ "index_name": {+ "type": "string",+ "description": "Name of the index to inspect.",+ },+ },+ "required": ["index_name"],+ },+ },+]+++def handle_search(request_id, args):+ index_name = args.get("index_name", "")+ query = args.get("query", "")+ if not index_name or not query:+ return _make_result(request_id, "Error: Both index_name and query are required.")++ top_k = args.get("top_k", 5)+ complexity = args.get("complexity", 32)++ rc, stdout, stderr = _run_leann(+ "search",+ index_name,+ query,+ f"--top-k={top_k}",+ f"--complexity={complexity}",+ "--json",+ "--show-metadata",+ "--non-interactive",+ )++ if rc != 0:+ return _make_result(request_id, f"Search failed: {stderr.strip()}")++ # Parse JSON results and format for code context+ try:+ results = json.loads(stdout)+ except json.JSONDecodeError:+ # Fallback to raw output if --json isn't available+ return _make_result(+ request_id, stdout if stdout.strip() else f"Search failed: {stderr.strip()}"+ )++ if not results:+ return _make_result(request_id, f"No results found for '{query}'.")++ formatted = []+ for i, r in enumerate(results, 1):+ meta = r.get("metadata", {})+ file_path = meta.get("file_path") or meta.get("source", "unknown")+ score = r.get("score", 0)+ text = r.get("text", "").strip()+ formatted.append(f"### Result {i} — {file_path} (score: {score:.3f})\n```\n{text}\n```")++ header = f"Found {len(results)} results for '{query}':\n"+ return _make_result(request_id, header + "\n\n".join(formatted))+++def handle_list(request_id):+ rc, stdout, stderr = _run_leann("list")+ if rc != 0:+ return _make_result(request_id, f"Error listing indexes: {stderr.strip()}")+ return _make_result(request_id, stdout)+++def handle_build(request_id, args):+ docs = args.get("docs", [])+ if not docs:+ return _make_result(+ request_id, "Error: 'docs' parameter is required (list of file paths or directories)."+ )++ cmd = ["build"]++ index_name = args.get("index_name")+ if index_name:+ cmd.append(index_name)++ cmd.extend(["--docs", *docs])++ backend = args.get("backend_name", "ivf")+ cmd.extend([f"--backend-name={backend}"])++ if args.get("force", False):+ cmd.append("--force")++ rc, stdout, stderr = _run_leann(*cmd, timeout=600)++ if rc != 0:+ return _make_result(request_id, f"Build failed:\n{stderr.strip()}\n{stdout.strip()}")++ return _make_result(request_id, stdout if stdout.strip() else "Build completed successfully.")+++def handle_status(request_id, args):+ index_name = args.get("index_name", "")+ if not index_name:+ return _make_result(request_id, "Error: index_name is required.")++ from pathlib import Path++ # Check standard location+ leann_dir = Path.cwd() / ".leann" / "indexes" / index_name+ meta_path = leann_dir / "documents.leann.meta.json"+ passages_path = leann_dir / "documents.leann.passages.jsonl"++ if not meta_path.exists():+ return _make_result(request_id, f"Index '{index_name}' not found at {leann_dir}")++ try:+ with open(meta_path) as f:+ meta = json.load(f)+ except Exception as e:+ return _make_result(request_id, f"Error reading index metadata: {e}")++ # Count passages+ num_chunks = 0+ file_paths = set()+ if passages_path.exists():+ with open(passages_path) as f:+ for line in f:+ line = line.strip()+ if not line:+ continue+ num_chunks += 1+ try:+ passage = json.loads(line)+ meta = passage.get("metadata", {})+ fp = meta.get("file_path") or meta.get("source", "")+ if fp:+ file_paths.add(fp)+ except json.JSONDecodeError:+ pass++ # Calculate total index size+ total_size = 0+ if leann_dir.exists():+ for f in leann_dir.iterdir():+ if f.is_file():+ total_size += f.stat().st_size++ size_mb = total_size / (1024 * 1024)++ backend = meta.get("backend_name", "unknown")+ embedding_model = meta.get("embedding_model", "unknown")+ embedding_mode = meta.get("embedding_mode", "unknown")+ dimensions = meta.get("dimensions", "unknown")++ status_lines = [+ f"Index: {index_name}",+ f"Backend: {backend}",+ f"Embedding: {embedding_model} ({embedding_mode})",+ f"Dimensions: {dimensions}",+ f"Chunks: {num_chunks}",+ f"Files indexed: {len(file_paths)}",+ f"Size: {size_mb:.1f} MB",+ f"Location: {leann_dir}",+ ]++ return _make_result(request_id, "\n".join(status_lines))++def handle_request(request):- if request.get("method") == "initialize":+ method = request.get("method")+ request_id = request.get("id")++ if method == "initialize":return {"jsonrpc": "2.0",- "id": request.get("id"),+ "id": request_id,"result": {"capabilities": {"tools": {}},"protocolVersion": "2024-11-05",- "serverInfo": {"name": "leann-mcp", "version": "1.0.0"},+ "serverInfo": {"name": "leann-mcp", "version": "2.0.0"},},}- elif request.get("method") == "tools/list":+ if method == "notifications/initialized":+ return None++ if method == "tools/list":return {"jsonrpc": "2.0",- "id": request.get("id"),- "result": {- "tools": [- {- "name": "leann_search",- "description": """🔍 Search code using natural language - like having a coding assistant who knows your entire codebase!--🎯 **Perfect for**:-- "How does authentication work?" → finds auth-related code-- "Error handling patterns" → locates try-catch blocks and error logic-- "Database connection setup" → finds DB initialization code-- "API endpoint definitions" → locates route handlers-- "Configuration management" → finds config files and usage--💡 **Pro tip**: Use this before making any changes to understand existing patterns and conventions.""",- "inputSchema": {- "type": "object",- "properties": {- "index_name": {- "type": "string",- "description": "Name of the LEANN index to search. Use 'leann_list' first to see available indexes.",- },- "query": {- "type": "string",- "description": "Search query - can be natural language (e.g., 'how to handle errors') or technical terms (e.g., 'async function definition')",- },- "top_k": {- "type": "integer",- "default": 5,- "minimum": 1,- "maximum": 20,- "description": "Number of search results to return. Use 5-10 for focused results, 15-20 for comprehensive exploration.",- },- "complexity": {- "type": "integer",- "default": 32,- "minimum": 16,- "maximum": 128,- "description": "Search complexity level. Use 16-32 for fast searches (recommended), 64+ for higher precision when needed.",- },- "show_metadata": {- "type": "boolean",- "default": False,- "description": "Include file paths and metadata in search results. Useful for understanding which files contain the results.",- },- },- "required": ["index_name", "query"],- },- },- {- "name": "leann_list",- "description": "📋 Show all your indexed codebases - your personal code library! Use this to see what's available for search.",- "inputSchema": {"type": "object", "properties": {}},- },- ]- },+ "id": request_id,+ "result": {"tools": TOOLS},}- elif request.get("method") == "tools/call":+ if method == "tools/call":tool_name = request["params"]["name"]args = request["params"].get("arguments", {})try:if tool_name == "leann_search":- # Validate required parameters- if not args.get("index_name") or not args.get("query"):- return {- "jsonrpc": "2.0",- "id": request.get("id"),- "result": {- "content": [- {- "type": "text",- "text": "Error: Both index_name and query are required",- }- ]- },- }-- # Build simplified command with non-interactive flag for MCP compatibility- cmd = [- "leann",- "search",- args["index_name"],- args["query"],- f"--top-k={args.get('top_k', 5)}",- f"--complexity={args.get('complexity', 32)}",- "--non-interactive",- ]- if args.get("show_metadata", False):- cmd.append("--show-metadata")- result = subprocess.run(cmd, capture_output=True, text=True)-+ return handle_search(request_id, args)elif tool_name == "leann_list":- result = subprocess.run(["leann", "list"], capture_output=True, text=True)-- return {- "jsonrpc": "2.0",- "id": request.get("id"),- "result": {- "content": [- {- "type": "text",- "text": result.stdout- if result.returncode == 0- else f"Error: {result.stderr}",- }- ]- },- }-+ return handle_list(request_id)+ elif tool_name == "leann_build":+ return handle_build(request_id, args)+ elif tool_name == "leann_status":+ return handle_status(request_id, args)+ else:+ return _make_error(request_id, f"Unknown tool: {tool_name}")+ except subprocess.TimeoutExpired:+ return _make_result(request_id, "Error: Command timed out.")except Exception as e:- return {- "jsonrpc": "2.0",- "id": request.get("id"),- "error": {"code": -1, "message": str(e)},- }+ return _make_error(request_id, str(e))++ return Nonedef main():diff --git a/packages/leann-mcp/README.md b/packages/leann-mcp/README.mdindex 5e2055e..8af4556 100644--- a/packages/leann-mcp/README.md+++ b/packages/leann-mcp/README.md@@ -37,8 +37,10 @@ claude mcp list | catOnce connected, you'll have access to these powerful semantic search tools in Claude Code:+- **`leann_search`** - Semantic code search with file paths, scores, and context- **`leann_list`** - List all available indexes across your projects-- **`leann_search`** - Perform semantic searches across code and documents+- **`leann_build`** - Build or incrementally update an index (keeps it current as code changes)+- **`leann_status`** - Show index details: backend, embedding model, chunk count, file count, size## 🎯 Quick Start Example