🔍 TypeRef-MCP

Professional TypeScript Type Inference & Symbol Navigation for Claude Code

Bringing IDE-grade TypeScript intelligence to your AI coding assistant

✨ Features

• 🎯 Precise Type Inference: Get exact TypeScript type information using the compiler API
• 🧭 Symbol Navigation: Find definitions, references, and usages with full type context
• 💡 IntelliSense Intelligence: Professional IDE-grade type analysis and suggestions
• ⚡ Real-time Analysis: Live type checking and diagnostics as you code
• 🏗️ Extensible Architecture: Designed to support multiple typed languages
• 🔄 Hot Reload Support: Watches for file changes and updates analysis automatically

🚀 Installation

Prerequisites: Node.js 18+ required

Option 1: NPM (Recommended)

# Global installation
npm install -g typeref-mcp

# Or with pnpm
pnpm add -g typeref-mcp

# Or with yarn
yarn global add typeref-mcp

Option 2: From GitHub

# Install directly from GitHub
npm install -g github:Coldsewoo/typeref-mcp

Option 3: From Source

# Clone and build
git clone https://github.com/Coldsewoo/typeref-mcp.git
cd typeref-mcp
npm install
npm run build
npm link

🔧 Configuration

Claude Code Setup

Add TypeRef-MCP to your Claude Code MCP configuration:

{
  "mcpServers": {
    "typeref": {
      "command": "typeref-mcp",
      "args": [],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

Alternative Configurations

If installed locally in your project:

{
  "mcpServers": {
    "typeref": {
      "command": "node",
      "args": ["./node_modules/.bin/typeref-mcp"],
      "env": {}
    }
  }
}

For development with hot reload:

{
  "mcpServers": {
    "typeref": {
      "command": "typeref-mcp",
      "args": ["--watch"],
      "env": {
        "NODE_ENV": "development",
        "DEBUG": "typeref:*"
      }
    }
  }
}

Specify a custom tsconfig.json:

{
  "mcpServers": {
    "typeref": {
      "command": "typeref-mcp", 
      "args": ["--config", "./custom-tsconfig.json"],
      "env": {}
    }
  }
}

🛠️ Available Tools

TypeRef-MCP provides the following tools for Claude Code:

| Tool | Description | Usage | |------|-------------|-------| | infer_type | Get precise type information for any TypeScript expression | Analyze variable types, function signatures, complex expressions | | find_definition | Navigate to symbol definitions with type context | Jump to function/class/interface definitions | | find_references | Locate all usages of a symbol | Find where variables, functions, types are used | | analyze_project | Get comprehensive project analysis | Overview of modules, exports, dependencies | | check_diagnostics | Get real-time type checking errors | Identify compilation errors and warnings |

📖 Usage Examples

Basic Type Inference

// Ask Claude: "What's the type of this variable?"
const user = { name: "John", age: 30, active: true };

// TypeRef-MCP will return:
// Type: { name: string; age: number; active: boolean; }

Advanced Type Analysis

// Complex generic types
function createStore<T extends Record<string, any>>(initial: T) {
  return {
    state: initial,
    update: (partial: Partial<T>) => ({ ...initial, ...partial })
  };
}

// TypeRef-MCP provides complete generic resolution and return types

Symbol Navigation

// Find all references to a function across your project
export function calculateTax(amount: number): number {
  return amount * 0.1;
}

// TypeRef-MCP will show all imports and usages with context

🏗️ Architecture

graph TB
    A[Claude Code] --> B[TypeRef-MCP Server]
    B --> C[Language Adapters]
    C --> D[TypeScript Adapter]
    D --> E[ts-morph + TS Compiler API]
    
    B --> F[Core Services]
    F --> G[Project Indexer]
    F --> H[Type Resolver] 
    F --> I[Symbol Navigator]
    F --> J[Cache Manager]
    
    B --> K[MCP Tools]
    K --> L[infer_type]
    K --> M[find_definition]
    K --> N[find_references]
    K --> O[analyze_project]
    K --> P[check_diagnostics]

🔧 Development

# Development mode with hot reload
npm run dev

# Watch mode for file changes
npm run watch

# Build for production
npm run build

# Code quality
npm run lint
npm run format

# Testing
npm test
npm run test:watch

⚡ Performance Features

TypeRef-MCP includes advanced performance optimizations for handling large TypeScript projects:

🚀 Automatic Optimizations

• Smart Exclusions: Automatically excludes node_modules, test files, and build directories
• Incremental Compilation: Uses TypeScript's incremental mode with .tsbuildinfo caching
• Memory Management: Automatic cleanup of idle projects and memory monitoring
• Intelligent Caching: Multi-level caching with TTL and pattern-based invalidation

🔧 Development Mode Features

Enable development mode for enhanced monitoring and debugging:

# Enable development monitoring
NODE_ENV=development typeref-mcp

# Or with debug output
DEBUG=typeref:* typeref-mcp

Development Features:

• 📊 Performance metrics every 5 minutes
• ⚠️ Slow operation warnings (>1s)
• 🔍 Memory usage tracking
• 📈 Tool call statistics and timing

🧹 Automatic Cleanup

• Idle Projects: Removes unused projects after 20 minutes of inactivity
• Memory Limits: Cleans up projects exceeding 100MB memory usage
• Cache Expiration: Intelligent cache cleanup every 5 minutes
• Graceful Shutdown: Proper resource cleanup on server stop

🐛 Troubleshooting

1. Check Node.js version: Ensure you're running Node.js 18+

   node --version

2. Verify installation:

   npm list -g typeref-mcp

3. Check TypeScript project: Ensure your project has a valid tsconfig.json

1. Project indexing: TypeRef-MCP automatically indexes your project on first use
2. Large projects: Initial analysis is optimized but may take a few moments
3. TypeScript errors: The server handles most compilation errors gracefully

TypeRef-MCP handles performance issues automatically with built-in optimizations.

For monitoring performance in development:

DEBUG=typeref:* NODE_ENV=development typeref-mcp

🤝 Contributing

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

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📜 License

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

Made with ❤️ by Coldsewoo

If you find TypeRef-MCP useful, please consider giving it a ⭐ on GitHub!