Type Crafter MCP Server

An MCP (Model Context Protocol) server for Type Crafter that allows AI assistants to generate type definitions from YAML specifications.

Features

The MCP server exposes the following tools:

1. generate-types

Generate type definitions from a YAML specification file.

Parameters:

• language (required): Target language - typescript or typescript-with-decoders
• specFilePath (required): Path to the YAML specification file
• outputDirectory (required): Directory where generated types will be written
• typesWriterMode (optional): SingleFile or Files (default: SingleFile)
• groupedTypesWriterMode (optional): FolderWithFiles or SingleFile (default: SingleFile)

Example:

{
  "language": "typescript",
  "specFilePath": "./types.yaml",
  "outputDirectory": "./generated-types",
  "typesWriterMode": "SingleFile",
  "groupedTypesWriterMode": "FolderWithFiles"
}

2. validate-spec

Validate a YAML specification file without generating types.

Parameters:

• specFilePath (required): Path to the YAML specification file to validate

Example:

{
  "specFilePath": "./types.yaml"
}

3. list-languages

List all supported target languages for type generation.

Parameters: None

4. get-spec-info

Get detailed information about a YAML specification file including version, title, and all defined types.

Parameters:

• specFilePath (required): Path to the YAML specification file

Example:

{
  "specFilePath": "./types.yaml"
}

5. get-spec-rules

Get comprehensive rules and guidelines for writing Type Crafter YAML specification files. This tool provides LLMs with detailed information about the YAML spec format, type mappings, nullable types, references, composition, best practices, and common patterns.

Parameters: None

Use this tool when:

• You need to create a new YAML specification file
• You want to understand the Type Crafter spec format
• You need guidance on type mappings and nullable types
• You want to learn about references, composition, and best practices

Returns: Complete specification rules documentation including:

• Root structure requirements
• Data types and TypeScript mapping
• Nullable types rules (properties not in required become Type | null)
• Type definitions (objects, enums, arrays, nested objects)
• References (local, external, cyclic)
• Composition (oneOf unions, allOf intersections)
• Best practices and common patterns
• Complete examples with YAML and TypeScript side-by-side

Prerequisites

• Node.js >= 18.0.0
• type-crafter CLI installed globally or locally

Install Type Crafter CLI:

npm install -g type-crafter

Installation

Option 1: Install from npm (Recommended)

Install the MCP server globally:

npm install -g @type-crafter/mcp-server

Or install locally in your project:

npm install @type-crafter/mcp-server

Option 2: Install from Source

1. Clone the repository:

git clone https://github.com/sinha-sahil/type-crafter.git
cd type-crafter/mcp-server

2. Install dependencies:

npm install

3. Build the server:

npm run build

Configuration

Using with Claude Desktop (Global Installation)

After installing globally via npm:

Edit your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

For global installation:

{
  "mcpServers": {
    "type-crafter": {
      "command": "type-crafter-mcp"
    }
  }
}

For local installation (from source):

{
  "mcpServers": {
    "type-crafter": {
      "command": "node",
      "args": ["/absolute/path/to/type-crafter/mcp-server/dist/index.js"]
    }
  }
}

For project-local npm installation:

{
  "mcpServers": {
    "type-crafter": {
      "command": "npx",
      "args": ["type-crafter-mcp"],
      "cwd": "/path/to/your/project"
    }
  }
}

Usage Examples

Once configured, you can use the MCP server through Claude Desktop:

1. Get specification rules (before writing specs):

   Show me the rules for writing Type Crafter YAML specification files

2. Generate TypeScript types:

   Generate TypeScript types from my spec.yaml file and save them to ./types

3. Validate a specification:

   Validate my types.yaml specification file

4. Get spec information:

   Show me information about the types defined in my spec.yaml

5. List available languages:

   What languages does Type Crafter support?

YAML Specification Format

The YAML specification should follow this structure:

info:
  version: 0.0.0
  title: Title of your specification

types:
  TypeName:
    type: object
    properties:
      propertyName:
        type: string

groupedTypes:
  GroupName:
    TypeInGroup:
      type: object
      properties:
        id:
          type: string

For more details on the specification format, see the main Type Crafter README.

Development

Build

npm run build

Watch mode

npm run dev

Linting

npm run lint
npm run lint:fix

Testing the Package Locally

Before publishing or to test the installed package:

# Create a tarball
npm pack

# Install globally from tarball
npm install -g ./type-crafter-mcp-server-0.1.0.tgz

# Test it
type-crafter-mcp

See PUBLISHING.md for detailed publishing instructions.

Troubleshooting

Server not connecting

• Global installation: Ensure type-crafter-mcp is in your PATH
• Local installation: Verify the path in your configuration is correct
• Check that the server was built successfully (npm run build)
• Restart Claude Desktop after modifying the configuration
• Check Node.js version (requires >= 18.0.0)

Type generation errors

• Ensure type-crafter CLI is installed: npm install -g type-crafter
• Validate your YAML specification using the validate-spec tool
• Check that all file paths are absolute or relative to your working directory
• Ensure the output directory exists or the server has permissions to create it

Permission denied error

• For global installation, you may need sudo: sudo npm install -g @type-crafter/mcp-server
• Or configure npm to install global packages in your home directory

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

ISC - See LICENSE file for details