# TypeScript Definitions MCP Server

> **Supercharge your test mocking with intelligent TypeScript type definitions**

## The Problem

When writing unit and integration tests with AI assistance, you've probably experienced this frustration:

```typescript
// You ask Claude Code: "Help me mock this API response"
// But Claude doesn't know the exact shape of your types...

const mockUserResponse = {
  id: 1,
  name: "John", 
  // ❌ What other properties should this have?
  // ❌ What's the exact type structure from my packages?
  // ❌ Am I missing required fields?
};
```

Before this tool, I found myself constantly:
- **Copy-pasting type definitions** from `node_modules` into prompts
- **Manually looking up package types** to write proper mocks  
- **Getting incomplete test mocks** because AI couldn't see the full type structure
- **Wasting time** on back-and-forth to get the types right

## The Solution

This MCP (Model Context Protocol) server gives Claude Code **instant access** to your project's TypeScript definitions—no more hunting through `node_modules` or incomplete mocks.

**Works with ANY TypeScript project:** React, Vue, Angular, Node.js, whatever you're building. Just point it at your project directory and it automatically discovers all your dependencies.

**Now your AI assistant can:**
✅ **See exact type structures** from any package in your project  
✅ **Generate complete, type-safe mocks** for your tests  
✅ **Understand your project's interfaces** automatically  
✅ **Validate mock data** against real type definitions  
✅ **Work with your specific package versions** - no generic examples  

## Quick Example

**Before** (manual type hunting):
```typescript
// You: "Help me mock an axios response"
// Claude: "Here's a basic mock..." (incomplete, might be wrong)

const mockResponse = {
  data: { /* ??? what goes here? */ },
  status: 200
  // Missing properties? Wrong structure?
};
```

**After** (with this MCP server):
```typescript
// You: "Help me mock an axios response for a User type"
// Claude automatically knows the full AxiosResponse<T> structure:

const mockResponse: AxiosResponse<User> = {
  data: {
    id: 1,
    name: "John Doe",
    email: "john@example.com",
    createdAt: "2023-01-01T00:00:00Z"
  },
  status: 200,
  statusText: "OK",
  headers: {},
  config: {} as InternalAxiosRequestConfig,
  request: {}
};
```

## Installation & Setup

### Step 1: Clone and Build

```bash
git clone https://github.com/blake-yoder/typescript-definitions-mcp.git
cd typescript-definitions-mcp
npm install
npm run build
```

### Step 2: Install Globally

```bash
npm install -g .
```

This makes the `typescript-definitions-mcp` command available globally.

### Step 3: Install in Claude Code

The easiest way to install is using the Claude Code MCP command:

```bash
claude mcp add typescript-definitions -- typescript-definitions-mcp
```

This automatically configures the MCP server for use in Claude Code.

#### Alternative Configuration Options

If you prefer manual configuration:

**Option A: User-Wide (Works in all projects)**

Create or edit `~/.claude/mcp_servers.json`:

**macOS/Linux:**
```json
{
  "typescript-definitions": {
    "command": "typescript-definitions-mcp",
    "args": []
  }
}
```

**Windows:**
Edit `%APPDATA%\claude\mcp_servers.json`:
```json
{
  "typescript-definitions": {
    "command": "typescript-definitions-mcp.cmd",
    "args": []
  }
}
```

**Option B: Project-Specific**

In your TypeScript project root, create `.mcp.json`:

```json
{
  "mcpServers": {
    "typescript-definitions": {
      "command": "typescript-definitions-mcp",
      "args": []
    }
  }
}
```

**Or if using local build:**
```json
{
  "mcpServers": {
    "typescript-definitions": {
      "command": "node",
      "args": ["/absolute/path/to/typescript-definitions-mcp/build/index.js"]
    }
  }
}
```

### Step 4: Restart Claude Code

**Completely quit and restart Claude Code** for the MCP server to load.

### Step 5: Test It Out

Open Claude Code in any TypeScript project and try:

> *"Help me create a mock for a React component that uses these props: ButtonProps from my UI library"*

> *"What's the exact structure of an AxiosResponse? I need to mock it for testing"*

> *"Show me all the interfaces in this project that end with 'Config'"*

## Real-World Usage Examples

### 🧪 **Test Mocking Made Easy**

**You:** *"I need to mock a jest.SpyInstance for testing. What's the exact type structure?"*

**Claude Code with MCP:** Instantly knows `jest.SpyInstance<ReturnType, Args>` and helps you create:

```typescript
const mockFn = jest.fn() as jest.SpyInstance<Promise<User>, [number]>;
mockFn.mockResolvedValue({
  id: 1,
  name: "Test User",
  email: "test@example.com"
});
```

### 🔌 **API Response Mocking**

**You:** *"Help me mock a complete axios error response for my error handling tests"*

**Claude Code:** Now sees the full `AxiosError` structure and creates proper mocks:

```typescript
const mockAxiosError: AxiosError = {
  message: "Network Error",
  name: "AxiosError",
  code: "NETWORK_ERROR",
  config: {} as InternalAxiosRequestConfig,
  request: {},
  response: {
    data: { error: "Service unavailable" },
    status: 503,
    statusText: "Service Unavailable",
    headers: {},
    config: {} as InternalAxiosRequestConfig,
    request: {}
  },
  isAxiosError: true,
  toJSON: () => ({})
};
```

### ⚛️ **React Component Testing**

**You:** *"I'm testing a component that takes complex props. Help me create comprehensive test data."*

**Claude Code:** Analyzes your component's prop interface and generates complete mock data:

```typescript
// Claude knows your exact ButtonProps interface
const mockProps: ButtonProps = {
  variant: "primary",
  size: "medium", 
  disabled: false,
  loading: false,
  onClick: jest.fn(),
  children: "Test Button",
  className: "test-class",
  "data-testid": "button-test"
};
```

### 🏗 **Complex Library Integration**

**You:** *"I'm using react-hook-form and need to mock the useForm return value. What's the complete structure?"*

**Claude Code:** Understands `UseFormReturn<T>` and creates accurate mocks:

```typescript
const mockUseForm: UseFormReturn<FormData> = {
  register: jest.fn(),
  handleSubmit: jest.fn(),
  formState: {
    errors: {},
    isValid: true,
    isSubmitting: false,
    isDirty: false,
    dirtyFields: {},
    touchedFields: {},
    isSubmitted: false,
    submitCount: 0
  },
  control: {} as Control<FormData>,
  // ... all other UseFormReturn properties
};
```

## Why This Matters

### Before: Manual Type Hunting
- 🕐 **Time wasted** digging through `node_modules`
- 😤 **Frustrating** copy-paste workflows  
- ❌ **Incomplete mocks** that break tests
- 🐛 **Type mismatches** in test data

### After: AI-Powered Type Intelligence
- ⚡ **Instant** type lookup and mock generation
- 🎯 **Accurate** test data that matches real types
- 🛡 **Type-safe** mocks prevent runtime errors  
- 🚀 **Faster** test development workflow

## Available Tools

The MCP server provides these tools to Claude Code:

- **`lookup_type`** - Find specific interfaces, types, or classes
- **`find_interfaces`** - Search for interfaces using patterns (e.g., `*Props`, `User*`)  
- **`get_package_types`** - Get all exported types from a specific package
- **`validate_type_usage`** - Check if your code matches expected types
- **`check_type_compatibility`** - Verify if two types are compatible

## Advanced Configuration

### Team Setup

For teams, commit the project-specific configuration to your repository so everyone gets the same setup:

```bash
# In your project root
cat > .mcp.json << EOF
{
  "mcpServers": {
    "typescript-definitions": {
      "command": "typescript-definitions-mcp",
      "args": []
    }
  }
}
EOF

# Commit to your repo
git add .mcp.json
git commit -m "Add TypeScript Definitions MCP server for team"
```

Now everyone on your team will have TypeScript intelligence when they open the project in Claude Code.

### Performance Optimization

For large codebases:

```json
{
  "typescript-definitions": {
    "command": "typescript-definitions-mcp",
    "args": ["--exclude-patterns", "**/*.test.ts,**/dist/**"],
    "env": {
      "NODE_OPTIONS": "--max-old-space-size=4096"
    }
  }
}
```

## Troubleshooting

**MCP server not connecting?**
1. Verify the JSON syntax in `mcp_servers.json`
2. Check that `typescript-definitions-mcp` is in your PATH
3. Restart Claude Code completely
4. Test with: `typescript-definitions-mcp --version`

**Not finding types in your project?**
- Make sure you're running Claude Code from your TypeScript project directory
- Check that `tsconfig.json` exists in your project
- Verify your project builds with `npx tsc --noEmit`

## Contributing

Built with ❤️ by [Blake Yoder](blakeyoder.com)

Found a bug or have a feature request? Open an issue or submit a PR!

## License

MIT License - see LICENSE file for details.

---

**Transform your TypeScript testing workflow today.** No more manual type hunting, no more incomplete mocks. Just intelligent, type-safe test development with Claude Code.