✨ 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

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

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

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

🛠️ Available Tools

TypeRef-MCP provides the following tools for Claude Code:

📖 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

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.