Component Index MCP 🗂️

A Model Context Protocol server that automatically indexes and tracks ALL components in a project, providing intelligent discovery and preventing code duplication. Agents can manually add definitions, and the index maintains a comprehensive view of the project structure that grows with the project and can be augmented by AI.

Overview

The Component Index MCP solves the problem of AI agents losing track of existing components, modules, and functions in complex development projects. Instead of relying on MCP-to-MCP communication (which has proven unreliable), this implementation uses Claude Code hooks for seamless automation.

Key Features

• Automatic Discovery: Scan and index all components and project entities, not just TypeScript/React
• Manual Addition: Agents can manually add component definitions
• Project Index: Maintains a growing index of the entire project structure, augmentable by AI
• Smart Search and Query: Find components and query project structure for orientation
• Duplicate Prevention: Detect similar components before creating new ones
• Hook-Based Automation: Leverage Claude Code hooks instead/model communication
• Zero Configuration: Works out of the box with various projects

Architecture

Core Components

component-index-mcp/
├── src/
│   ├── server.ts           # Main MCP server
│   ├── indexer.ts          # Component scanning and analysis  
│   ├── storage.ts          # File-based persistence
│   ├── search.ts           # Search and similarity engine
│   └── types.ts            # TypeScript definitions
├── hooks/                  # Claude Code hooks
│   ├── post-edit.sh        # Auto-index after file edits
│   └── pre-task.sh         # Component discovery before tasks
├── package.json
├── tsconfig.json
└── README.md

Claude Code Hooks Integration

Instead of MCP-to-MCP communication, we use Claude Code hooks:

Post-Edit Hook (hooks/post-edit.sh):

• Triggers after any file edit
• Automatically indexes new/modified components
• Updates component relationships and dependencies

Pre-Task Hook (hooks/pre-task.sh):

• Triggers before task execution
• Searches for relevant existing components
• Provides context about similar implementations

Installation

Quick Setup (Recommended)

# Install the package globally
npm install -g component-index-mcp

# Add to Claude Code
claude mcp add component-index npx component-index-mcp

Alternative: Local Installation

# Install locally in a project
npm install component-index-mcp

# Add to Claude Code (from project root)
claude mcp add component-index node node_modules/component-index-mcp/dist/server.js

Development Setup

For local development or customization:

# Clone and install
git clone https://github.com/contra13/component-index-mcp.git
cd component-index-mcp
npm install
npm run build

Manual Configuration

If you prefer manual setup, add to your Claude Code settings:

{
  "hooks": {
    "PostToolUse": {
      "Edit": "/home/contra/dev/MCP/component-index-mcp/hooks/post-edit.sh",
      "MultiEdit": "/home/contra/dev/MCP/component-index-mcp/hooks/post-edit.sh",
      "Write": "/home/contra/dev/MCP/component-index-mcp/hooks/post-edit.sh"
    },
    "PreToolUse": {
      "*": "/home/contra/dev/MCP/component-index-mcp/hooks/pre-task.sh"
    }
  },
  "mcpServers": {
    "component-index": {
      "command": "node",
      "args": ["./dist/server.js"],
      "env": {}
    }
  }
}

MCP Tools

index_component

Manually index a specific component file.

await mcp.callTool("index_component", {
  path: "/path/to/component.tsx",
  category: "ui-component"
});

add_entity

Manually add a component or entity definition.

await mcp.callTool("add_entity", {
  name: "NewEntity",
  path: "/path/to/entity",
  category: "utility",
  description: "Manually added utility"
});

update_index

Allow AI to augment the index with new info.

await mcp.callTool("update_index", {
  entityId: "entity-123",
  annotations: ["AI-augmented", "performance-optimized"]
});

query_project

Query the index for structure, entities, etc.

await mcp.callTool("query_project", {
  query: "all utilities in src/",
  filters: { category: "utility" }
});

get_project_overview

Get a comprehensive summary like enhanced ls.

await mcp.callTool("get_project_overview", {
  path: "/project/root",
  depth: 3
});

search_components

Find components by query with intelligent ranking.

await mcp.callTool("search_components", {
  query: "button component",
  category: "ui",
  includeUsage: true
});

get_component_details

Get comprehensive information about specific components.

await mcp.callTool("get_component_details", {
  id: ["component-123", "component-456"]
});

analyze_dependencies

Map component relationships and dependency chains.

await mcp.callTool("analyze_dependencies", {
  componentId: "component-123",
  depth: 3
});

suggest_similar

Find components similar to a description or existing component.

await mcp.callTool("suggest_similar", {
  description: "modal dialog with form validation",
  excludeIds: ["current-modal"]
});

Data Schema

interface ProjectEntity {
  id: string;                    // Unique identifier
  name: string;                  // Entity name  
  path: string;                  // Absolute file path
  category: EntityCategory;      // ui, service, hook, file, directory, etc.
  exports: ExportInfo[];         // Named exports and defaults
  imports: ImportInfo[];         // Dependencies
  usage: UsageMetrics;           // Access frequency, popularity
  lastModified: string;          // File modification timestamp
  quality: QualityMetrics;       // Automated assessment
  summary: string;               // Brief description
  annotations: string[];         // AI/manual additions
  isManual: boolean;             // Whether manually added
}

Workflow Integration

Automatic Indexing (via Hooks)

1. Developer edits a file
2. post-edit.sh hook triggers automatically
3. Entity is analyzed and indexed
4. Relationships are updated
5. No manual intervention required

Pre-Task Discovery (via Hooks)

1. Developer starts working on a task
2. pre-task.sh hook analyzes task description
3. Relevant existing entities are identified
4. Context is provided to prevent duplication

Manual Search and Query (via MCP Tools)

1. Developer searches or queries project structure
2. Tools like search_components, query_project find relevant matches
3. Details, overviews, and usage examples provided
4. Dependencies and relationships mapped

Manual Addition and Augmentation

1. Agent uses add_entity to manually add definitions
2. AI uses update_index to augment with annotations
3. Index grows with project, providing comprehensive overview

Benefits

✅ Prevents Code Duplication - Find existing components before creating new ones
✅ Improves Code Quality - Reuse proven, tested components
✅ Accelerates Development - Discover relevant utilities and patterns
✅ Maintains Architecture - Understand component relationships
✅ Comprehensive Project View - Queryable index for quick orientation
✅ Flexible Augmentation - Manual and AI additions to index
✅ Zero Maintenance - Automatic indexing via hooks

Development Status

Phase 1: Foundation (Target: 2 weeks)

• [x] Project structure and TypeScript setup
• [ ] Basic component indexing and storage
• [ ] Core MCP tools implementation
• [ ] Claude Code hooks integration
• [ ] Search functionality

Phase 2: Enhancement (Target: +2 weeks)

• [ ] Dependency tracking and analysis
• [ ] Usage metrics and popularity scoring
• [ ] Quality assessment automation
• [ ] Performance optimization

Phase 3: Intelligence (Target: +2 weeks)

• [ ] AI-powered component suggestions
• [ ] Semantic similarity analysis
• [ ] Pattern recognition and extraction
• [ ] Advanced search with embeddings

Contributing

This MCP follows the established patterns from other MCPs in the ecosystem:

• Pattern Store MCP for data persistence patterns
• Session MCP for progress tracking integration
• Orchestrator MCP for workflow enhancement

License

MIT License - Part of the Cracked Jacked Claude framework ecosystem.