@oneqode/mcp-codebase-index

A Model Context Protocol (MCP) server that provides intelligent codebase indexing and search capabilities for AI agents. This tool enables AI assistants to understand codebases deeply through natural language queries, dependency analysis, and comprehensive code entity tracking.

Features

• 🔍 Natural Language Search: Query your codebase using plain English
• 🏗️ Comprehensive Indexing: Indexes Vue, TypeScript, JavaScript files with full AST parsing
• 🔗 Relationship Tracking: Understands imports, exports, and component dependencies
• 📊 Codebase Analytics: Generate statistics and insights about your code
• 🌳 Tree Visualization: Create markdown index files with full directory structure
• 🚀 Real-time Updates: File watcher keeps the index current as you code
• 🤖 AI-Optimized: Designed specifically for use with AI assistants like Claude

Installation

Global Installation (Recommended)

npm install -g @oneqode/mcp-codebase-index

Local Installation

npm install @oneqode/mcp-codebase-index

Quick Start

CLI Usage

# Index your codebase
codebase-index reindex --clean

# Search for components
codebase-index search "user authentication"

# Get statistics
codebase-index stats --detailed

# Generate markdown tree
codebase-index tree

# Check for duplicates before creating new components
codebase-index check UserProfile component

MCP Server Configuration

Add to your .mcp.json:

{
  "mcpServers": {
    "codebase-index": {
      "command": "npx",
      "args": ["@oneqode/mcp-codebase-index"]
    }
  }
}

Available Tools

The MCP server provides these tools for AI agents:

1. search_entities

Search for code entities using natural language queries.

await search_entities({
  query: "find all React hooks",
  limit: 20,
  types: ["composable", "function"]
})

2. get_entity_details

Get comprehensive information about a specific entity.

await get_entity_details({
  entityId: "abc123",
  includeRelationships: true,
  includeContent: false
})

3. find_relationships

Explore dependency graphs and relationships.

await find_relationships({
  entityId: "abc123",
  depth: 2,
  types: ["imports", "uses"]
})

4. suggest_similar

Find entities similar to a given name or description.

await suggest_similar({
  name: "UserAuth",
  type: "component",
  limit: 5
})

5. check_duplicates

Check if similar entities exist before creating new ones.

await check_duplicates({
  name: "UserProfile",
  type: "component",
  threshold: 0.8
})

6. index_file

Index or reindex a specific file.

await index_file({
  filePath: "/src/components/NewComponent.vue",
  force: true
})

7. reindex_all

Reindex the entire codebase.

await reindex_all({
  clean: true  // Clear existing index first
})

8. get_statistics

Get comprehensive statistics about the indexed codebase.

await get_statistics({
  detailed: true
})

9. generate_tree_index

Generate a markdown file with full directory tree and statistics.

await generate_tree_index({})
// Creates .index/CODEBASE_INDEX.md

Database Schema

The index uses SQLite with the following structure:

• entities: All code entities (components, functions, classes, etc.)
• relationships: Dependencies and connections between entities
• entity_search: Full-text search index
• index_metadata: Indexing metadata and configuration

Supported File Types

• Vue Single File Components (.vue)
• TypeScript (.ts, .tsx)
• JavaScript (.js, .jsx)

Entity Types

• component - Vue/React components
• composable - Vue composables / React hooks
• service - Service classes/modules
• store - State management stores
• type - TypeScript types/interfaces
• function - Standalone functions
• class - Class definitions
• page - Page components
• layout - Layout components
• middleware - Middleware functions
• util - Utility functions

Natural Language Query Examples

# Find all authentication-related components
codebase-index search "authentication components"

# Find all API service files
codebase-index search "api services"

# Find all Vue composables
codebase-index search "composables"

# Find all test files
codebase-index search "test files"

Configuration

The index database is stored at .index/db/codebase.db in your project root. This directory is automatically created on first use.

Ignored Patterns

By default, these directories are ignored:

• node_modules/**
• .nuxt/**
• dist/**
• .output/**
• .index/**

Use Cases for AI Agents

1. Before Creating Components: Use check_duplicates to avoid redundancy
2. Understanding Code: Use search_entities with natural language
3. Exploring Dependencies: Use find_relationships to understand connections
4. Getting Context: Use get_entity_details for deep understanding
5. Maintaining Knowledge: Use reindex_all to keep the index current

Performance

• Indexes ~500 files in under 1 second
• Natural language search returns results in <100ms
• Incremental updates via file watcher
• Efficient SQLite database with full-text search

Contributing

Contributions are welcome! Please submit issues and pull requests on GitHub.

License

MIT © OneQode

Credits

Built with:

• Model Context Protocol SDK
• Better SQLite3
• TypeScript Compiler API
• @vue/compiler-sfc