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?

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

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.