CodeSearch MCP Server

A lightning-fast code search and navigation tool for Claude Code that helps you find files, search code, navigate symbols, and understand your projects instantly. Just ask Claude to "find all my React components", "show me recent changes", or "find the definition of UserService" and get results in milliseconds.

Built with .NET 9.0 and COA MCP Framework 2.1.8, featuring Lucene-powered search with AI-optimized responses.

🚀 Features

⚡ Lightning-Fast Search: Lucene indexing enables instant search across millions of lines
🔍 Smart Code Analysis: Custom analyzer preserves code patterns like : ITool, [Fact], and enhanced CamelCase tokenization with full generic type support (finds McpToolBase<TParams, TResult> when searching for "McpToolBase")
📁 File Discovery: Pattern-based file and directory search with fuzzy matching
🧬 Advanced Type Extraction: Extract types, interfaces, classes, and methods from 25 programming languages using julie-codesearch Rust CLI tool (includes C#, TypeScript, JavaScript, Python, Java, Rust, Go, C/C++, PHP, Ruby, Swift, Kotlin, and 13 more specialized languages)
🧭 Code Navigation: Symbol search, find references, and goto definition without compilation
📝 Line-Level Search: Get ALL occurrences with exact line numbers - faster than grep with structured JSON output
🔄 Search and Replace: Bulk find/replace across entire codebase with preview mode for safety, plus fuzzy matching for handling typos and variations
🔧 Smart Refactoring: AST-aware symbol renaming using byte-offset replacement - safer than text search/replace
✏️ Surgical Line Editing: Insert, replace, or delete specific line ranges without reading entire files
⏱️ Recent Files: Track and find recently modified files
🔗 Call Path Tracing: Hierarchical call chain analysis with semantic bridging for cross-language tracing
🧠 Semantic Search: Vector similarity search using embeddings for finding conceptually similar code
🎯 Real-time Updates: File watchers automatically update indexes on changes
📊 AI-Optimized: Token-efficient responses with confidence-based result limiting
🏠 Hybrid Local Indexing: Indexes stored in workspace .coa/codesearch/indexes/ with multi-workspace support

Performance

Startup: < 500ms
Text search: < 10ms indexed
File search: < 50ms
Memory usage: < 200MB typical
Index size: ~1MB per 1000 files

🎯 Token Optimization

60-85% token reduction through confidence-based limiting
Progressive disclosure: Essential results first, full data via resource URIs
Smart context handling: Fewer results when context lines included
Standardized responses: Consistent format across all tools

🧬 Supported Languages for Type Extraction

The type extraction system supports 25 programming languages using julie-codesearch, a Rust-based CLI tool with native tree-sitter bindings:

Core Languages (10):

Rust • TypeScript • JavaScript • Python • Java • C# • PHP • Ruby • Swift • Kotlin

Systems Languages (4):

C • C++ • Go • Lua

Specialized Languages (11):

GDScript • Vue SFCs • Razor • SQL • HTML • CSS • Regex • Bash • PowerShell • Zig • Dart

Special Features:

Vue Single File Components: Extracts types from <script> blocks (TS/JS)
Razor/Blazor: Extracts types from @code and @functions blocks
Mixed Languages: Handles embedded code in templating systems
Cross-Platform Binaries: Pre-compiled julie-codesearch binaries for macOS (ARM64), Linux (x64), and Windows (x64) included in the build
Zero Dependencies: No manual tree-sitter library installation required - julie-codesearch binaries are self-contained

📋 Prerequisites

.NET 9.0 SDK or later
No tree-sitter libraries required - julie-codesearch binaries are self-contained and included in the build

🚀 Quick Start

Build from Source

# Clone the repository
git clone https://github.com/anortham/coa-codesearch-mcp.git
cd coa-codesearch-mcp

# Build the project
dotnet build -c Release

Add to Claude Code

# macOS/Linux
claude mcp add codesearch /path/to/coa-codesearch-mcp/COA.CodeSearch.McpServer/bin/Release/net9.0/COA.CodeSearch.McpServer

# Windows
claude mcp add codesearch C:\path\to\coa-codesearch-mcp\COA.CodeSearch.McpServer\bin\Release\net9.0\COA.CodeSearch.McpServer.exe

After adding:

Restart Claude Code completely
Claude will now have powerful search capabilities - just ask naturally!

Optional: Add to .gitignore

# CodeSearch local indexes (can be regenerated)
.coa/

Note: NuGet package installation will be available in a future release

🌟 What Makes This Special

Unlike basic file search, CodeSearch understands your code:

Smart Pattern Recognition: Finds async Task, [Fact], interface IService patterns, plus enhanced CamelCase splitting for generic types
Context-Aware: Knows the difference between C# classes and JavaScript functions using julie-codesearch native tree-sitter extraction
Instant Results: Millisecond search across millions of lines of code
Fuzzy Matching: Finds files even with typos in names
Content Similarity: "Find files like this one" using advanced analysis
Recent Activity: Tracks what you've been working on lately
Multi-Workspace Support: Index and search multiple projects simultaneously with perfect isolation
Local Storage: Fast access with indexes stored directly in your workspace
Code Navigation: Symbol search, find references, and goto definition without compilation
Structured Line Search: Better than grep - returns JSON with exact line numbers and context
Safe Bulk Edits: Preview mode for search/replace prevents accidental changes
Type-Aware: Extracts and indexes types from 25 languages via julie-codesearch for accurate navigation across all major programming languages
Precise Editing: Complete line-based editing suite for surgical code modifications without full file reads

🛠️ Available Tools - Now with Smart Defaults! ✨

Note: All tools support smart defaults - most parameters are optional and default to sensible values. The workspacePath parameter defaults to the current workspace directory across all tools.

Core Search Tools

Tool	Purpose	Key Parameters (all others optional)
`index_workspace`	Index files for search	`workspacePath` (optional, defaults to current dir)
`text_search`	Search file contents with semantic/fuzzy/regex modes	`query` (required), `searchMode` (optional: "auto", "exact", "fuzzy", "semantic", "regex")
`search_files`	🆕 Find files or directories by pattern	`pattern` (required), `resourceType` (optional: "file", "directory", "both")
`recent_files`	Get recently modified files	`timeFrame` (optional, e.g., "2d", "1w")

Navigation Tools

Tool	Purpose	Key Parameters (all others optional)
`symbol_search`	Find classes, interfaces, methods by name	`symbol` (required)
`find_references`	Find all usages of a symbol	`symbol` (required)
`goto_definition`	Jump to symbol definition	`symbol` (required)

Advanced Search Tools

Tool	Purpose	Key Parameters (all others optional)
`line_search`	Get ALL occurrences with line numbers	`pattern` (required)
`search_and_replace`	Replace patterns across files with preview and fuzzy matching	`searchPattern` (required), `replacePattern` (optional)

Refactoring Tools

Tool	Purpose	Key Parameters (all others optional)
`smart_refactor`	AST-aware symbol renaming with byte-offset precision	`operation` (required), `params` (required)

Editing Tools

Tool	Purpose	Key Parameters (all others optional)
`edit_lines`	🆕 Unified line editing (insert/replace/delete)	`filePath` (required), `operation` (required: "insert", "replace", "delete"), `startLine` (required)

Analysis Tools

Tool	Purpose	Key Parameters (all others optional)
`get_symbols_overview`	Extract all symbols from files	`filePath` (required)
`find_patterns`	Detect code patterns and quality issues	`filePath` (required)
`trace_call_path`	Hierarchical call chain analysis	`symbol` (required)

💬 How to Use with Claude Code

Once installed, just chat naturally with Claude Code! Here are examples of what you can say:

Finding Files and Code

"Find all my TypeScript files"

Claude will search for *.ts files in your project

"Show me all the async functions in my codebase"

Claude will search for patterns like "async function" and "async Task"

"Find files containing 'UserService'"

Claude will search file contents for the term "UserService"

"What files have been changed in the last 2 days?"

Claude will show recently modified files with timestamps

Project Understanding

"Find all my React components"

Claude will look for .jsx, .tsx files and React patterns

"Show me all the test files"

Claude will find files with "test", "spec" in names or paths

"Find files similar to UserController.cs"

Claude will use content analysis to find structurally similar files

"Search for all database queries in my project"

Claude will look for SQL patterns, ORM calls, etc.

Code Navigation

"Find the definition of UserService"

Claude will jump directly to where UserService class is defined
Shows exact line and column, with optional context snippet

"Show me all references to the UpdateUser method"

Claude will find all places where UpdateUser is called
Groups results by file for easy scanning

"Search for all classes ending with Controller"

Claude will find all classes matching the pattern like UserController, OrderController
Uses julie-codesearch tree-sitter-based extraction for accurate results across 25 languages

"Find where IRepository interface is implemented"

Claude will locate all implementations of the IRepository interface
Shows inheritance relationships and usage counts

Type and Code Analysis

"Find all classes and interfaces in my project"

Claude will extract types from 25 languages including C#, TypeScript, Python, Java, Rust, Go, C/C++, PHP, Ruby, Swift, Kotlin, and more
Uses julie-codesearch native tree-sitter extraction for LSP-quality results

"Show me all functions and methods in my codebase"

Claude will parse 25 languages and extract function/method definitions with signatures
Supports everything from C# to Bash to specialized languages like GDScript

"Find all Vue component methods"

Claude will parse Vue SFCs and extract methods from JavaScript/TypeScript script blocks
julie-codesearch handles embedded languages in templating systems

"Show me all Python classes with their methods"

Claude will analyze Python files and extract class definitions and methods
Full support for Python's class hierarchies and method signatures

"Find all Rust structs and impl blocks"

Claude will parse Rust code and extract struct definitions and implementations
julie-codesearch provides native Rust tree-sitter integration

Development Workflow

"Index my project for searching"

Claude will scan and index your files for fast searching

"Find all TODO comments"

Claude will search for TODO, FIXME, HACK comments

"Show me configuration files"

Claude will find .json, .yaml, .config files

Advanced Examples

"Find all files in the Services directory that haven't been touched in 30 days"

Claude will use recent_files with a time filter to find stale code

"Search for error handling patterns in my C# code"

Claude will use text_search to find try-catch blocks and exception handling

"Find all API endpoints in my project"

Claude will search for route decorators and endpoint definitions

"Show me files that import React but don't use hooks"

Claude will combine multiple searches to find React imports without useState/useEffect

Line-Level Search Examples

"Show me every line that contains 'Thread.Sleep'"

Claude will use line_search to find ALL occurrences with exact line numbers
Returns structured JSON instead of plain text grep output

"Find all console.log statements with their line numbers"

Claude will return every console.log with file path and line number
Perfect for cleanup tasks before production deployment

Search and Replace Examples

"Replace all 'var' declarations with 'let' in my JavaScript files"

Claude will use search_and_replace with preview mode first
Shows what will change before applying modifications

"Update all copyright headers to 2025"

Claude will find and replace copyright patterns across all files
Supports regex patterns for complex replacements

Fuzzy Matching Examples

"Replace getUserData() even with typos using fuzzy matching"

Claude will use fuzzy mode with threshold 0.7-0.8
Finds: getUserData(), getUserDat() (typo), getUserData () (spacing), getUserDatta() (double-t)
Perfect for cleaning up inconsistent code patterns

"Fix method name variations across the codebase"

Claude will use fuzzy search to find all similar variations
Handles typos, spacing issues, and minor differences automatically

Smart Refactoring Examples

"Rename UserService to AccountService everywhere"

Claude will use smart_refactor with AST-aware symbol renaming
Finds all usages via SQLite identifiers table (LSP-quality)
Uses byte-offset replacement for precise, safe refactoring

"Refactor UpdateUser method name to UpdateUserAccount"

Claude will find ALL references using symbol analysis
Replaces at exact byte positions (not regex)
Preview mode shows exactly what will change before applying

🔒 Security & Thread Safety

Path Validation

The PathResolutionService implements comprehensive path validation:

Directory traversal protection: Blocks paths containing ".." sequences
Path length validation: Prevents excessively long paths (240+ characters)
Input sanitization: Validates and normalizes all workspace paths
Cross-platform compatibility: Handles path separators and special folders

Thread Safety

Concurrent metadata access: Semaphore locks protect workspace metadata files
Atomic file operations: Metadata updates use temporary files with atomic replacement
Lock management: Per-file locking prevents corruption during concurrent access
Safe file system operations: All I/O operations include error handling and fallbacks

API Security

Path resolution: Internal hash directories never exposed via HTTP API
Real path validation: Only existing, accessible workspace paths are returned
URL encoding support: Handles special characters in workspace paths
Fallback handling: Gracefully handles unresolvable or corrupted metadata

⚙️ Configuration

Configuration via appsettings.json:

{
  "CodeSearch": {
    "BasePath": "~/.coa/codesearch",
    "LogsPath": "~/.coa/codesearch/logs",
    "Lucene": {
      "IndexRootPath": ".coa/codesearch/indexes",
      "MaxIndexingConcurrency": 8,
      "RAMBufferSizeMB": 256,
      "SupportedExtensions": [".cs", ".js", ".ts", ".py", ".java", ...]
    },
    "FileWatcher": {
      "Enabled": true,
      "DebounceMilliseconds": 500
    },
    "QueryCache": {
      "Enabled": true,
      "MaxCacheSize": 1000,
      "CacheDuration": "00:15:00"
    }
  }
}

🏗️ Architecture

Hybrid Local Indexing Storage

Primary Workspace Indexes: .coa/codesearch/indexes/[workspace-name_hash]/
- Indexes stored locally within the primary workspace directory
- Each workspace gets its own isolated index for fast, context-aware search
- Supports multiple workspace projects from single CodeSearch session
Cross-Platform Lock Management: SimpleFSLockFactory ensures compatibility across macOS, Windows, and Linux
Logs: ~/.coa/codesearch/logs/ (global logging location)
Configuration: Per-workspace settings with workspace-specific isolation

Framework Integration

Built on COA MCP Framework 2.1.8:

Automatic tool discovery
Token optimization
Progressive response disclosure
Circuit breaker patterns
Memory pressure management

Search Engine

Lucene.NET 4.8.0 backend
Custom CodeAnalyzer for programming language patterns
Multi-factor scoring with path relevance, recency, and type matching
Configurable analyzers per file type

🧪 Development

Building

# Debug build
dotnet build -c Debug

# Release build  
dotnet build -c Release

# Run tests
dotnet test

Testing

# Test indexing
mcp__codesearch__index_workspace --workspacePath "."

# Test search
mcp__codesearch__text_search --query "LuceneIndexService"

# Test file discovery
mcp__codesearch__recent_files --timeFrame "7d"

🔧 Troubleshooting

Common Issues

"Claude says it can't find files I know exist"

Tell Claude: "Please index my project for searching first"

"Search results seem outdated"

Ask Claude: "Rebuild the search index for this project"

"Claude is responding slowly to search requests"

Try asking for fewer results: "Find 5 recent TypeScript files"
Ask Claude to check system memory: "Check CodeSearch memory usage"

"Getting index lock errors"

Close Claude Code completely and restart it

Installation issues:

Make sure you have .NET 9.0 installed: dotnet --version
Try rebuilding: cd coa-codesearch-mcp && dotnet build -c Release
Verify the path in your Claude Code configuration is correct

Template Embedding Fix (v2.1.4+)

Background: Prior to v2.1.4, CodeSearch would fail to connect in workspaces other than the development workspace due to attempting to load instruction templates from a Templates/ directory that only existed in the source repository.

Solution: Templates are now embedded as resources in the assembly, ensuring they're always available regardless of workspace location. The codesearch-instructions.scriban template is compiled into the binary as an embedded resource.

Technical Details:

Template file: Templates/codesearch-instructions.scriban
Embedded resource name: COA.CodeSearch.McpServer.Templates.codesearch-instructions.scriban
Loading mechanism: Changed from file-based (WithInstructionsFromTemplate) to resource-based (WithTemplateInstructions with embedded content)
Framework fix: COA.Mcp.Framework v2.1.8+ includes defensive checks for missing template directories

This change ensures CodeSearch works consistently across all workspaces without filesystem dependencies.

Logging

Set log levels in appsettings.json:

{
  "Logging": {
    "LogLevel": {
      "COA.CodeSearch": "Information"  // Debug, Trace for more detail
    }
  }
}

📚 Integration

With Other MCP Servers

CodeSearch works seamlessly with other MCP servers configured in Claude Code:

Goldfish MCP: Handles session management, checkpoints, and task tracking
Other MCP servers: Can be combined for comprehensive development workflows

Example workflow:

# 1. Search for code patterns using CodeSearch
mcp__codesearch__text_search --query "async Task"

# 2. Navigate to specific definitions
mcp__codesearch__goto_definition --symbol "UserService"

# 3. Find all references to a method
mcp__codesearch__find_references --symbol "UpdateUser"

📄 License

MIT License - see LICENSE file.

🤝 Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request

📞 Support

Issues: GitHub Issues
Documentation: docs/ folder
Framework: COA MCP Framework 2.1.8

Built with COA MCP Framework 2.1.8 • Powered by Lucene.NET