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:

// 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):

// 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):

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

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

Step 2: Install Globally

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:

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:

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

Windows: Edit %APPDATA%\claude\mcp_servers.json:

{
  "typescript-definitions": {
    "command": "typescript-definitions-mcp.cmd",
    "args": []
  }
}

Option B: Project-Specific

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

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

Or if using local build:

{
  "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:

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:

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:

// 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:

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:

# 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:

{
  "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?

Verify the JSON syntax in mcp_servers.json
Check that typescript-definitions-mcp is in your PATH
Restart Claude Code completely
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

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.

TypeScript Definitions MCP Server