Skip to main content
Glama
TypeScript Definitions MCP Server

TypeScript Definitions MCP Server

by blakeyoder

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

Related MCP server: TypeScript LSP MCP

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.

Available Tools

8 tools
check_type_compatibilityC

Check if two types are compatible/assignable

Inputs: sourceType (required), targetType (required).

find_interfacesC

Find interfaces matching a pattern

Inputs: pattern (required).

get_package_typesC

Get all type definitions from a specific package

Inputs: packageName (required).

get_project_infoB

Get information about the current TypeScript project

Inputs: no named parameters.

lookup_typeC

Look up TypeScript type definitions by name and optional package

Inputs: typeName (required), packageName.

reinitialize_indexerB

Reinitialize the type indexer (useful after package installations)

Inputs: workingDir.

validate_interface_implementationC

Validate if code correctly implements an interface

Inputs: implementation (required), interfaceName (required), interfaceDefinition (required).

validate_type_usageC

Validate TypeScript code for type correctness

Inputs: code (required), expectedType.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 8 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose with no overlap: checking type compatibility, finding interfaces, getting package types, getting project info, looking up types, reinitializing the indexer, validating interface implementation, and validating type usage. The descriptions make it easy for an agent to select the right tool without confusion.

    Naming Consistency4/5

    The naming follows a consistent verb_noun pattern (e.g., check_type_compatibility, find_interfaces, get_package_types) with one minor deviation: 'lookup_type' uses 'lookup' instead of 'look_up' or 'get', but it still fits the overall style. The pattern is predictable and readable throughout.

    Tool Count5/5

    With 8 tools, the count is well-scoped for a TypeScript definitions server. Each tool serves a specific, useful function in the domain of type checking and project management, with no redundancy. This number allows comprehensive coverage without being overwhelming.

    Completeness4/5

    The tool set covers core TypeScript definition workflows well, including type lookup, compatibility checks, interface handling, project info, and validation. A minor gap is the lack of tools for modifying or generating types (e.g., create_type or update_definition), but agents can work around this with the provided tools for most common tasks.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      Exposes TypeScript Language Server Protocol functionality to AI agents, enabling them to query types at specific positions, find definitions and references, get diagnostics, run type tests, and type-check inline code just like in an IDE.
      9
      246 npm
      3
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI assistants to generate TypeScript types, Zod schemas, TypeBox, and JSON Schema from any API endpoint or JSON.
      2 npm
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI coding agents to interact with TypeScript projects through compiler-level code intelligence, providing tools for navigation, type information, diagnostics, refactoring, and semantic search.
      29
      194 npm
      4
      Apache 2.0