@type-crafter/mcp 0.1.0

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@type-crafter/mcp",
+  "version": "0.1.0",
+  "description": "MCP server for Type Crafter - generate types from YAML specifications",
+  "type": "module",
+  "main": "./dist/index.js",
+  "bin": {
+    "type-crafter-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "src/GUIDE.md",
+    "src/SPEC_RULES.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "lint": "eslint src --ext .ts",
+    "lint:fix": "eslint src --ext .ts --fix",
+    "format": "prettier --write \"**/*.{ts,md,json}\"",
+    "format:check": "prettier --check \"**/*.{ts,md,json}\"",
+    "prepublishOnly": "npm run build",
+    "prepack": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "model-context-protocol",
+    "type-crafter",
+    "type-generation",
+    "typescript",
+    "yaml",
+    "code-generation",
+    "claude",
+    "ai-tools"
+  ],
+  "author": "Sahil Sinha",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sinha-sahil/type-crafter.git",
+    "directory": "mcp-server"
+  },
+  "bugs": {
+    "url": "https://github.com/sinha-sahil/type-crafter/issues"
+  },
+  "homepage": "https://github.com/sinha-sahil/type-crafter/tree/release/mcp-server#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "peerDependencies": {
+    "type-crafter": ">=0.11.0"
+  },
+  "peerDependenciesMeta": {
+    "type-crafter": {
+      "optional": false
+    }
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "yaml": "^2.3.2"
+  },
+  "devDependencies": {
+    "@types/node": "^20.8.4",
+    "@typescript-eslint/eslint-plugin": "^6.7.5",
+    "@typescript-eslint/parser": "^6.7.5",
+    "eslint": "^8.51.0",
+    "prettier": "^3.7.4",
+    "typescript": "^5.2.2"
+  }
+}

package/src/GUIDE.md

@@ -0,0 +1,365 @@
+# Type Crafter MCP Server - LLM Usage Guide
+
+This guide helps AI assistants understand the Type Crafter workflow and how to use the MCP server effectively.
+
+## What is Type Crafter?
+
+**Type Crafter** is a CLI tool that generates TypeScript type definitions from YAML specification files. Think of it as "OpenAPI Generator" but specifically for type definitions.
+
+**The MCP Server** exposes Type Crafter functionality through Model Context Protocol, allowing AI assistants to help users create type definitions from YAML specs.
+
+## Core Concepts
+
+### YAML Spec → TypeScript Types
+
+```
+Input (YAML):                    Output (TypeScript):
+-------------                    --------------------
+types:                          export type User = {
+  User:                           id: string;
+    type: object                  email: string;
+    required:                     name: string | null;
+      - id                      };
+      - email
+    properties:
+      id: { type: string }
+      email: { type: string }
+      name: { type: string }
+```
+
+### Key Rules (Critical!)
+
+1. **Arrays cannot be top-level types** - They must be properties within objects
+2. **Properties not in `required` become `Type | null`** - This is automatic
+3. **External paths are from project root** - Not relative to current file
+4. **Two organization modes**:
+   - `types` - Flat/top-level types
+   - `groupedTypes` - Organized into groups/namespaces
+
+## Available Tools
+
+### 1. `get-spec-rules` 📖
+
+**When to use:** ALWAYS use this FIRST before creating or modifying YAML specs
+
+**What it does:** Returns comprehensive rules for writing Type Crafter YAML specs
+
+**Workflow:**
+
+```
+User asks: "Create types for my API"
+     ↓
+1. Call get-spec-rules to learn the format
+2. Read the returned rules (nullable types, arrays, paths, etc.)
+3. Now you know how to write valid YAML specs
+```
+
+### 2. `validate-spec` ✅
+
+**When to use:** After creating or modifying a YAML spec
+
+**What it does:** Validates the spec structure without generating types
+
+**Workflow:**
+
+```
+You created: my-types.yaml
+     ↓
+1. Call validate-spec with path to my-types.yaml
+2. Check if valid or see error messages
+3. Fix errors if needed and validate again
+```
+
+### 3. `generate-types` 🔨
+
+**When to use:** After spec is validated and user wants TypeScript output
+
+**What it does:** Generates TypeScript type definitions from the YAML spec
+
+**Parameters:**
+
+- `language`: `typescript` or `typescript-with-decoders`
+- `specFilePath`: Path to YAML spec (from project root)
+- `outputDirectory`: Where to save generated .ts files
+- `typesWriterMode`: `SingleFile` or `Files` (default: SingleFile)
+- `groupedTypesWriterMode`: `FolderWithFiles` or `SingleFile` (default: SingleFile)
+
+**Workflow:**
+
+```
+Spec is valid
+     ↓
+1. Call generate-types with appropriate parameters
+2. Types are generated in outputDirectory
+3. User can now import and use them in TypeScript
+```
+
+### 4. `get-spec-info` 📊
+
+**When to use:** To understand what's in an existing spec file
+
+**What it does:** Returns version, title, and lists all defined types
+
+**Workflow:**
+
+```
+User asks: "What types are in my spec?"
+     ↓
+1. Call get-spec-info with path to spec
+2. See all top-level types and grouped types
+3. Understand the structure before modifying
+```
+
+### 5. `list-languages` 📝
+
+**When to use:** User asks what output formats are supported
+
+**What it does:** Lists supported target languages
+
+**Returns:**
+
+- `typescript` - TypeScript type definitions
+- `typescript-with-decoders` - TypeScript + runtime decoders
+
+## Complete Workflows
+
+### Workflow 1: Creating Types from Scratch
+
+```
+User: "I need types for my e-commerce cart API"
+
+Step 1: Learn the rules
+→ Call: get-spec-rules
+→ Read and understand: nullable types, arrays, structure
+
+Step 2: Gather requirements
+→ Ask user: What fields does the cart have?
+→ Ask user: What's required vs optional?
+
+Step 3: Create YAML spec
+→ Create spec file following the rules
+→ Remember: Properties not in 'required' → Type | null
+→ Remember: Arrays must be properties, not top-level
+
+Step 4: Validate
+→ Call: validate-spec with the spec path
+→ Fix any errors
+
+Step 5: Generate
+→ Call: generate-types with language and paths
+→ Types are now available in output directory
+
+Step 6: Confirm
+→ Tell user where types were generated
+→ Optionally show a snippet of generated types
+```
+
+### Workflow 2: Modifying Existing Spec
+
+```
+User: "Add a 'description' field to the Product type"
+
+Step 1: Understand current spec
+→ Call: get-spec-info to see what types exist
+→ Optionally: get-spec-rules to refresh on rules
+
+Step 2: Read the spec file
+→ Use file reading tools to see current Product type
+
+Step 3: Modify the spec
+→ Add the new field
+→ Decide if it's required or optional (Type | null)
+
+Step 4: Validate
+→ Call: validate-spec
+
+Step 5: Regenerate
+→ Call: generate-types to update TypeScript files
+```
+
+### Workflow 3: Validating User's Spec
+
+```
+User: "Can you check if my spec is valid?"
+
+Step 1: Validate
+→ Call: validate-spec with their spec path
+
+Step 2: Report results
+→ If valid: Confirm and show summary
+→ If invalid: Explain errors and suggest fixes
+
+Step 3: Optionally generate
+→ Ask if they want to generate types now
+→ Call: generate-types if yes
+```
+
+## Common Patterns
+
+### Pattern: Required vs Optional Fields
+
+```yaml
+User:
+  type: object
+  required:
+    - id # Required → id: string
+    - email # Required → email: string
+  properties:
+    id: { type: string }
+    email: { type: string }
+    name: { type: string } # Optional → name: string | null
+    age: { type: number } # Optional → age: number | null
+```
+
+**Key insight:** The `required` array controls nullability!
+
+### Pattern: Arrays as Properties
+
+```yaml
+# ❌ INVALID - Cannot do this
+Tags:
+  type: array
+  items: { type: string }
+
+# ✅ VALID - Arrays must be properties
+Post:
+  type: object
+  properties:
+    tags:
+      type: array
+      items: { type: string }
+```
+
+### Pattern: External References
+
+```yaml
+# Paths from project root (where command runs)
+Cart:
+  type: object
+  properties:
+    items:
+      type: array
+      items:
+        $ref: './src/types/cart.yaml#/CartItem'
+```
+
+**Key insight:** Paths are from project root, NOT relative to current file!
+
+### Pattern: Grouped Types
+
+```yaml
+groupedTypes:
+  # Group name
+  Auth:
+    # Types in the group
+    LoginRequest: { ... }
+    LoginResponse: { ... }
+    User: { ... }
+
+  # Reference grouped types
+  $ref: '#/groupedTypes/Auth/User'
+```
+
+## Error Handling
+
+### Common Errors
+
+1. **"Invalid specification file"**
+   - Missing `info.version` or `info.title`
+   - Neither `types` nor `groupedTypes` exists
+   - **Fix:** Add required fields
+
+2. **"Specification file not found"**
+   - Wrong path
+   - **Fix:** Use correct path from project root
+
+3. **"type-crafter command not found"**
+   - CLI not installed
+   - **Fix:** User needs: `npm install -g type-crafter`
+
+### When Things Go Wrong
+
+1. Re-read spec rules with `get-spec-rules`
+2. Validate the spec with `validate-spec`
+3. Check error messages carefully
+4. Fix one issue at a time
+5. Re-validate after each fix
+
+## Best Practices for LLMs
+
+### DO ✅
+
+- **ALWAYS** call `get-spec-rules` before creating specs
+- **ALWAYS** validate specs before generating
+- Ask user about required vs optional fields
+- Use clear, descriptive type names (PascalCase)
+- Group related types using `groupedTypes`
+- Add descriptions to complex types
+- Explain to users what was generated
+
+### DON'T ❌
+
+- Create top-level array types
+- Assume paths are relative to current file
+- Skip validation step
+- Generate types without confirming output directory
+- Forget that non-required properties become `Type | null`
+
+## Quick Reference
+
+```
+First time creating spec?
+  → get-spec-rules
+
+Created/modified spec?
+  → validate-spec
+
+Spec is valid?
+  → generate-types
+
+Need to see what's in a spec?
+  → get-spec-info
+
+User asks about supported languages?
+  → list-languages
+```
+
+## Example: Complete Session
+
+```
+User: "Create types for a shopping cart with items and total price"
+
+LLM:
+1. [Calls get-spec-rules]
+2. "I'll create a YAML spec for your shopping cart. Let me ask a few questions:
+   - Should cart items have quantity? (yes/no)
+   - Is the cart token required or optional?
+   - Any other fields needed?"
+
+User: "Yes to quantity, token is required, add a currency field too"
+
+LLM:
+3. [Creates cart.yaml with proper structure]
+4. [Calls validate-spec on cart.yaml]
+5. "Spec is valid! Where should I generate the TypeScript types?"
+
+User: "./src/types"
+
+LLM:
+6. [Calls generate-types with language: typescript, outputDirectory: ./src/types]
+7. "✅ Generated TypeScript types in ./src/types/
+   - Cart type with token, items[], totalPrice, currency
+   - Items are CartItem[] (array of cart items)
+   - All fields except currency are required (currency is string | null)"
+```
+
+## Summary
+
+The Type Crafter MCP server helps users create TypeScript types from YAML specifications. As an LLM:
+
+1. **Learn first** - Call `get-spec-rules` to understand the format
+2. **Validate always** - Use `validate-spec` before generating
+3. **Generate carefully** - Confirm paths and options with user
+4. **Remember the rules** - Arrays as properties, nullable types, root paths
+
+With these tools, you can help users maintain type-safe TypeScript projects with clean, generated type definitions! 🚀