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
`search_symbols`	Search for code symbols with filters	path, language, name, match, kinds, scope
`search_text`	Search code using regex patterns	path, pattern, language, case_insensitive, literal, limit, paths
`search_files`	Find files by name, pattern, or extension	path, pattern, name, extension, directory
`detect_stacks`	Detect technology stacks in a directory	path, scan_mode (fast/thorough)
`analyze_dependencies`	Analyze project dependencies	path, include_transitive, check_outdated
`refresh_index`	Rebuild the symbol index	path, force_rebuild
`cache_stats`	View cache statistics	path (optional)
`clear_cache`	Clear cached indices	path (optional)
`search_ast_pattern`	Search using AST patterns with metavariables	path, language, pattern, paths, limit
`search_ast_rule`	Search using complex AST rules with relational and composite operators	path, 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

Security Model

All tools accept absolute path parameters and validate them against allowed workspaces configured at startup.

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",
        "--allowed-workspace", "/path/to/your/project1",
        "--allowed-workspace", "/path/to/your/project2"
      ]
    }
  }
}

Configuration Options

Option	Description
`--allowed-workspace <path>`	Whitelist a directory for search operations. Can be specified multiple times. If omitted, all paths are allowed (use with caution)
`-w <path>`	Short alias for `--allowed-workspace`

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, tool routing, and path validation
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

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

Symbol Search

Text Search

Dependency Analysis

JavaScript

Full

Full (npm)

TypeScript

Full

Full (npm)

Python

Full

Full (pip)

Java

Full

Full (Maven/Gradle)

Full

Full (NuGet)

Full

Limited

Full (go.mod)

Rust

Full

Limited

Full (Cargo)

C / C++

Full

Limited

PHP

Full

Limited

Full (Composer)

Ruby

Full

Limited

Full (Bundler)

Kotlin

Full

Limited

Full (Gradle)

Tool

Description

Key Parameters

search_symbols

Search for code symbols with filters

path, language, name, match, kinds, scope

search_text

Search code using regex patterns

path, pattern, language, case_insensitive, literal, limit, paths

search_files

Find files by name, pattern, or extension

path, pattern, name, extension, directory

detect_stacks

Detect technology stacks in a directory

path, scan_mode (fast/thorough)

analyze_dependencies

Analyze project dependencies

path, include_transitive, check_outdated

refresh_index

Rebuild the symbol index

path, force_rebuild

cache_stats

View cache statistics

path (optional)

clear_cache

Clear cached indices

path (optional)

search_ast_pattern

Search using AST patterns with metavariables

path, language, pattern, paths, limit

search_ast_rule

Search using complex AST rules with relational and composite operators

path, language, rule, paths, limit, debug

check_ast_grep

Check ast-grep availability and version

None

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

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.

// 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" } } }

Language

File Extensions

Bash

.sh, .bash

.c, .h

C++

.cpp, .cc, .cxx, .hpp, .hxx

.cs

CSS

.css

.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