Code Search MCP

Universal MCP server for intelligent code search across any programming language

Overview

Code Search MCP is a high-performance Model Context Protocol server that enables LLMs to intelligently search and analyze codebases across 12 programming languages with comprehensive AST search support for 15 languages. Built on our universal-ctags wrapper, ripgrep, and ast-grep, it provides fast symbol search, structural AST pattern matching, text search, file search, and dependency analysis with persistent caching for 80%+ faster startup times.

Core Features

Feature	Description	Performance
Symbol Search	Find classes, functions, methods, and variables with intelligent filtering	Fast (indexed)
AST Search	Structural code search using Abstract Syntax Trees with metavariables and relational rules	Fast
Text Search	Regex-powered code search using ripgrep	Very Fast
File Search	Locate files by name, pattern, or extension with glob support	Very Fast
Stack Detection	Automatically detect technology stacks and frameworks in projects	Fast
Dependency Analysis	Analyze project dependencies across multiple ecosystems	Fast
Index Caching	Persistent symbol indices with automatic invalidation	80%+ faster startup

Language Support

Code Search MCP supports 12 programming languages with full symbol indexing and intelligent search capabilities.

Language	Symbol Search	Text Search	Dependency Analysis
JavaScript	Full	Full	Full (npm)
TypeScript	Full	Full	Full (npm)
Python	Full	Full	Full (pip)
Java	Full	Full	Full (Maven/Gradle)
C#	Full	Full	Full (NuGet)
Go	Full	Limited	Full (go.mod)
Rust	Full	Limited	Full (Cargo)
C / C++	Full	Limited	Limited
PHP	Full	Limited	Full (Composer)
Ruby	Full	Limited	Full (Bundler)
Kotlin	Full	Limited	Full (Gradle)

MCP Tools

The server exposes the following tools through the Model Context Protocol interface.

Tool	Description	Key Parameters
add_workspace	Register a workspace directory for searching	path, name (optional)
list_workspaces	List all registered workspaces	None
search_symbols	Search for code symbols with filters	workspace_id, language, name, match, kinds, scope
search_text	Search code using regex patterns	workspace_id, pattern, language, case_insensitive
search_files	Find files by name, pattern, or extension	workspace_id, pattern, name, extension, directory
detect_stacks	Detect technology stacks in a workspace	workspace_id, scan_mode (fast/thorough)
analyze_dependencies	Analyze project dependencies	workspace_id, include_transitive, check_outdated
refresh_index	Rebuild the symbol index	workspace_id, force_rebuild
cache_stats	View cache statistics	workspace_id (optional)
clear_cache	Clear cached indices	workspace_id (optional)
search_ast_pattern	Search using AST patterns with metavariables	workspace_id, language, pattern, paths, limit
search_ast_rule	Search using complex AST rules with relational and composite operators	workspace_id, language, rule, paths, limit, debug
check_ast_grep	Check ast-grep availability and version	None

Search Capabilities

Search Type	Match Modes	Filter Options
Symbol Search	exact, prefix, substring, regex	kind, scope (class/namespace/module), language
Text Search	regex, literal	language, case sensitivity, result limit
File Search	glob patterns, wildcards	extension, directory, case sensitivity

AST Search

Search code using Abstract Syntax Tree analysis for structural pattern matching that goes beyond simple text search.

Capability	Description	Example Pattern
Metavariables	Capture and match code elements	$VAR (named), $$VAR (anonymous), $$$VAR (multiple)
Relational Rules	Context-aware matching	inside, has, precedes, follows
Composite Rules	Logical combinations	all (AND), any (OR), not (negation)
Kind Matching	Match specific AST node types	function_declaration, class_declaration, etc.

AST Search Examples:

// Find async functions without await
{
  "rule": {
    "all": [
      { "pattern": "async function $NAME($$$) { $$$ }" },
      { "not": { "has": { "pattern": "await $$$", "stopBy": "end" } } }
    ]
  }
}

// Find React components using useEffect without dependencies
{
  "rule": {
    "all": [
      { "pattern": "useEffect($$$)" },
      { "not": { "pattern": "useEffect($CALLBACK, [$$$DEPS])" } }
    ]
  }
}

// Find functions with console.log inside
{
  "rule": {
    "pattern": "console.log($$$)",
    "inside": {
      "pattern": "function $NAME($$$) { $$$ }",
      "stopBy": "end"
    }
  }
}

Supported Languages (15 Total):

Language	File Extensions
Bash	.sh, .bash
C	.c, .h
C++	.cpp, .cc, .cxx, .hpp, .hxx
C#	.cs
CSS	.css
Go	.go
HTML	.html, .htm
Java	.java
JavaScript	.js, .jsx, .mjs
JSON	.json
Kotlin	.kt, .kts
Python	.py
Rust	.rs
Scala	.scala
Swift	.swift
TypeScript	.ts, .tsx
YAML	.yml, .yaml

All AST language packages are bundled with the server - no additional installation required!

Tech Stack Detection

Automatically identify technologies, frameworks, and tools used in your projects with intelligent file-based detection.

Category	Technologies Detected	Detection Method
Languages	JavaScript, TypeScript, Python, Java, C#, Go, Rust, C/C++, PHP, Ruby, Kotlin, Swift	File extensions & patterns
Build Tools	Webpack, Vite, Rollup, Parcel, Gradle, Maven, Make, CMake, MSBuild	Config files
Package Managers	npm, Yarn, pnpm, pip, Poetry, Cargo, Go modules, NuGet, Composer, Bundler	Lock files & manifests
Frameworks	React, Vue, Angular, Next.js, Svelte, Django, Flask, FastAPI, Spring Boot, .NET Core	Dependencies & configs
Testing	Jest, Mocha, Vitest, Pytest, JUnit, NUnit, Go Test, Cargo Test	Config files & dependencies
Databases	PostgreSQL, MySQL, MongoDB, Redis, SQLite, Prisma, TypeORM, Sequelize	Config files & dependencies
DevOps	Docker, Kubernetes, GitHub Actions, GitLab CI, CircleCI, Jenkins, Terraform	Config files & manifests
Code Quality	ESLint, Prettier, Black, Pylint, Flake8, RuboCop, Clippy, TSLint	Config files

Scan Modes: Fast (config files only) • Thorough (includes dependency analysis)

Performance

The persistent caching system delivers dramatic performance improvements for repeated searches.

Repository	Cold Start	Cached Start	Improvement
Express.js (8,234 symbols)	2,453ms	127ms	19.3x faster
Lodash (12,456 symbols)	1,876ms	89ms	21.1x faster
Large Codebase (5,000 symbols)	3,124ms	145ms	21.5x faster

Average improvement: 94.5% time saved

Installation

Prerequisites

Install the required dependencies:

# Install universal-ctags (required for symbol search)
# macOS
brew install universal-ctags

# Ubuntu/Debian
sudo apt-get install universal-ctags

# Windows (via Chocolatey)
choco install universal-ctags

# Install ripgrep (required for text search)
# macOS
brew install ripgrep

# Ubuntu/Debian
sudo apt-get install ripgrep

# Windows (via Chocolatey)
choco install ripgrep

# ast-grep is bundled with the MCP server - no separate installation needed!

Install the MCP Server

# Clone the repository
git clone https://github.com/GhostTypes/code-search-mcp.git
cd code-search-mcp

# Install dependencies
npm install

# Build the project
npm run build

Configuration

Add to your MCP settings file (e.g., claude_desktop_config.json):

{
  "mcpServers": {
    "code-search": {
      "command": "node",
      "args": [
        "/path/to/code-search-mcp/dist/index.js"
      ]
    }
  }
}

Development

# Clone the repository
git clone https://github.com/GhostTypes/code-search-mcp.git
cd code-search-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

# Run integration tests
npm run test:integration

Architecture

The server is built with a modular architecture for maintainability and extensibility.

Component	Responsibility
MCP Server	Protocol handling and tool routing
Workspace Manager	Workspace registration and lifecycle
Symbol Indexer	Universal-ctags integration and indexing
Symbol Search Service	Symbol query processing and filtering
Text Search Service	Ripgrep integration for text search
File Search Service	Fast file finding with glob patterns
Stack Detection Engine	Technology stack identification
Dependency Analyzer	Multi-ecosystem dependency analysis
Cache Manager	Index persistence and invalidation
AST Search Service	Structural code search using ast-grep

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

License

MIT License - see LICENSE for details

Acknowledgments

Tool	Purpose
universal-ctags	Symbol indexing
ripgrep	Text search
ast-grep	AST-based structural search
MCP SDK	Protocol implementation