TypeScript Project Indexer MCP

A powerful MCP (Model Context Protocol) server that indexes and analyzes TypeScript/JavaScript projects, providing intelligent code exploration, dependency tracking, method discovery, and project structure analysis for AI assistants and development tools.

🚀 Features

🔍 Project Analysis: Deep analysis of TypeScript/JavaScript codebases
📊 Method Discovery: Find functions, classes, interfaces, and types across your project
🔗 Dependency Tracking: Track imports, exports, and module dependencies
📁 File Indexing: Comprehensive file structure analysis with metadata
🔎 Smart Search: Powerful search capabilities for code elements
⚡ Performance Optimized: Efficient caching and batch processing
🌐 Cross-Platform: Works on Windows, macOS, and Linux
🤖 AI-Ready: Perfect integration with AI assistants and development tools

📦 Installation

Via npm (Recommended)

npm install -g ts-project-indexer-mcp

Via Git

git clone https://github.com/ugorur/ts-project-indexer-mcp.git
cd ts-project-indexer-mcp
npm install
npm run build

🛠️ Configuration

MCP Settings for Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "typescript-project-indexer": {
      "command": "npx",
      "args": [
        "-y",
        "ts-project-indexer-mcp"
      ],
      "env": {}
    }
  }
}

MCP Settings for Cline

Add to your MCP configuration:

{
  "typescript-project-indexer": {
    "autoApprove": [
      "analyze_project",
      "search_methods", 
      "get_project_files",
      "get_project_stats",
      "find_usages"
    ],
    "disabled": false,
    "timeout": 60,
    "type": "stdio",
    "command": "npx",
    "args": [
      "-y", 
      "ts-project-indexer-mcp"
    ]
  }
}

Alternative: Local Installation

If you prefer to install globally:

npm install -g ts-project-indexer-mcp

Then use:

{
  "mcpServers": {
    "typescript-project-indexer": {
      "command": "ts-project-indexer",
      "args": [],
      "env": {}
    }
  }
}

⚠️ Important Change in v1.1.0: Project paths are no longer passed as command line arguments. Instead, use the analyze_project tool with an absolute projectPath parameter.

🎯 Usage Examples

Basic Project Analysis

// Analyze a specific project (absolute path required)
await mcp.callTool('analyze_project', {
  projectPath: '/home/user/my-project',
  includePatterns: ['**/*.ts', '**/*.js'],
  excludePatterns: ['node_modules/**', 'dist/**']
});

// Windows example
await mcp.callTool('analyze_project', {
  projectPath: 'C:\\Users\\user\\my-project',
  includePatterns: ['**/*.ts', '**/*.js'],
  excludePatterns: ['node_modules/**', 'dist/**']
});

Search for Methods

// Find all functions containing 'config'
await mcp.callTool('search_methods', {
  query: 'config',
  type: 'function',
  includeUsages: true
});

Find Usage Locations

// Find where a file is imported
await mcp.callTool('find_usages', {
  filePath: 'src/config.ts',
  searchType: 'imports',
  includeDetails: true
});

Get Project Statistics

// Get comprehensive project stats
await mcp.callTool('get_project_stats', {});

🔧 Available Tools

`analyze_project`

Analyzes and indexes the entire project structure.

Parameters:

projectPath (string, required): Absolute path to project root (e.g., /home/user/project or C:\Users\user\project)
includePatterns (array): File patterns to include (default: ['**/*.ts', '**/*.js', '**/*.json'])
excludePatterns (array): File patterns to exclude (default: ['node_modules/**', 'dist/**', '**/*.d.ts'])
forceReindex (boolean): Force full reindexing (default: false)

⚠️ Important: The projectPath parameter is required and must be an absolute path. Relative paths are not supported for security and reliability reasons.

`search_methods`

Search for methods, functions, and classes in the project.

Parameters:

query (string): Search query (required)
type (string): Type filter (method, function, class, interface, type, all)
includeUsages (boolean): Include usage locations (default: false)

`find_usages`

Find where a file, method, or class is imported or used.

Parameters:

filePath (string): Path to file to find imports/usages for
methodName (string): Name of method/function to find usages for
className (string): Name of class to find usages for
searchType (string): Search type (imports, usages, both)
includeDetails (boolean): Include detailed context (default: true)

`get_project_files`

Get list of all indexed project files with metadata.

`get_project_stats`

Get comprehensive project statistics.

`debug_dependencies`

Debug dependencies to see what is being indexed.

Parameters:

limit (number): Maximum dependencies to show (default: 20)
filterBy (string): Filter dependencies by string match

📚 Resources

`project://files`

List of all indexed project files with metadata.

`project://methods`

Index of all methods, functions, and classes.

💡 Use Cases

For AI Assistants

Code Understanding: Help AI understand project structure and relationships
Intelligent Refactoring: Find all usages before making changes
Documentation Generation: Extract comprehensive project information
Code Review: Analyze dependencies and method relationships

For Development Tools

IDE Integration: Enhance code navigation and search
Build Tools: Analyze project dependencies for optimization
Documentation Tools: Generate API documentation automatically
Testing Tools: Find test coverage gaps

For Project Management

Complexity Analysis: Understand codebase complexity
Dependency Mapping: Visualize project dependencies
Code Metrics: Generate comprehensive code statistics
Architecture Analysis: Understand project structure

🏗️ Architecture

TypeScript Project Indexer MCP
├── Core Engine
│   ├── Project Indexer    # Main analysis engine
│   ├── Code Parser        # AST parsing and analysis
│   ├── Path Resolver      # Import/export resolution
│   └── Type System        # TypeScript type analysis
├── Caching Layer
│   ├── Memory Cache       # Fast in-memory storage
│   └── Persistent Cache   # Disk-based caching
├── MCP Server
│   ├── Tool Handlers      # MCP tool implementations
│   ├── Resource Handlers  # MCP resource providers
│   └── Protocol Layer     # MCP communication
└── Utilities
    ├── File System        # Cross-platform file operations
    ├── Pattern Matching   # Glob pattern support
    └── Error Handling     # Robust error management

🔄 Performance & Caching

Smart Caching: Intelligent caching system with 24-hour retention
Batch Processing: Processes files in optimized batches
Incremental Analysis: Only re-analyzes changed files
Memory Management: Efficient memory usage for large projects
Cross-Platform: Optimized path handling for all operating systems

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Development Setup

git clone https://github.com/ugorur/ts-project-indexer-mcp.git
cd ts-project-indexer-mcp
npm install
npm run dev

Running Tests

npm test

Building

npm run build

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

👨‍💻 Author

Ugur Orur

GitHub: @ugorur
Project: ts-project-indexer-mcp

🙏 Acknowledgments

Built with Model Context Protocol (MCP)
Powered by TypeScript AST analysis
Inspired by the need for better AI-code integration

📈 Roadmap

[ ] Language Support: JavaScript ES6+, JSX/TSX
[ ] IDE Plugins: VSCode extension
[ ] Advanced Analysis: Cyclomatic complexity metrics
[ ] Export Formats: JSON, XML, YAML export options
[ ] Real-time Updates: File watcher integration
[ ] Cloud Integration: Remote project analysis
[ ] Team Features: Shared analysis results
[ ] Performance: Even faster analysis for large codebases

Made with ❤️ for the developer community

ts-project-indexer-mcp

TypeScript Project Indexer MCP

🚀 Features

📦 Installation

Via npm (Recommended)

Via Git

🛠️ Configuration

MCP Settings for Claude Desktop

MCP Settings for Cline

Alternative: Local Installation

🎯 Usage Examples

Basic Project Analysis

Search for Methods

Find Usage Locations

Get Project Statistics

🔧 Available Tools

analyze_project

search_methods

find_usages

get_project_files

get_project_stats

debug_dependencies

📚 Resources

project://files

project://methods

💡 Use Cases

For AI Assistants

For Development Tools

For Project Management

🏗️ Architecture

🔄 Performance & Caching

🤝 Contributing

Development Setup

Running Tests

Building

📄 License

👨‍💻 Author

🙏 Acknowledgments

📈 Roadmap

Readme

Keywords

Package Sidebar

Install

Repository

Homepage

DownloadsWeekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators

`analyze_project`

`search_methods`

`find_usages`

`get_project_files`

`get_project_stats`

`debug_dependencies`

`project://files`

`project://methods`

Weekly Downloads