---

✨ 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

$3

``bash


Global installation

npm install -g typeref-mcp

Or with pnpm

pnpm add -g typeref-mcp

Or with yarn

yarn global add typeref-mcp
`

$3

`bash


Install directly from GitHub


npm install -g github:Coldsewoo/typeref-mcp
`

$3

`bash


Clone and build


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

🔧 Configuration

$3

Add TypeRef-MCP to your Claude Code MCP configuration:

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

$3

Local Installation

If installed locally in your project:

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

Development Mode

For development with hot reload:

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

Custom TypeScript Config

Specify a custom tsconfig.json:

`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

$3

`typescript
// 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; }
`

$3

`typescript
// Complex generic types
function createStore>(initial: T) {
return {
state: initial,
update: (partial: Partial) => ({ ...initial, ...partial })
};
}

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

$3

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

🔧 Development

`bash


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:

$3

- 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

$3

Enable development mode for enhanced monitoring and debugging:

`bash


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

$3

- 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

TypeRef-MCP not starting

1. Check Node.js version: Ensure you're running Node.js 18+
`bash
node --version
`

2. Verify installation:
`bash
npm list -g typeref-mcp
`

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

Type inference not working

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

Performance optimization

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

For monitoring performance in development:
`bash
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.

---