README.md•9.16 kB
# 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.