npm package: @oneqode/mcp-codebase-index
Description: MCP server for intelligent codebase indexing and search with AI-friendly natural language queries
Author: OneQode
Latest version: 1.0.0

# @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)

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

### Local Installation

```bash
npm install @oneqode/mcp-codebase-index
```

## Quick Start

### CLI Usage

```bash
# 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`:

```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.

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

### 2. `get_entity_details`
Get comprehensive information about a specific entity.

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

### 3. `find_relationships`
Explore dependency graphs and relationships.

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

### 4. `suggest_similar`
Find entities similar to a given name or description.

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

### 5. `check_duplicates`
Check if similar entities exist before creating new ones.

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

### 6. `index_file`
Index or reindex a specific file.

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

### 7. `reindex_all`
Reindex the entire codebase.

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

### 8. `get_statistics`
Get comprehensive statistics about the indexed codebase.

```typescript
await get_statistics({
  detailed: true
})
```

### 9. `generate_tree_index`
Generate a markdown file with full directory tree and statistics.

```typescript
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

```bash
# 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](https://github.com/anthropics/model-context-protocol)
- [Better SQLite3](https://github.com/WiseLibs/better-sqlite3)
- [TypeScript Compiler API](https://github.com/microsoft/TypeScript)
- [@vue/compiler-sfc](https://github.com/vuejs/core)