@type-crafter/mcp 1.0.0 → 1.1.0

package/README.md

@@ -5,23 +5,70 @@ An MCP (Model Context Protocol) server that helps AI assistants write correct Ty
 [![npm version](https://badge.fury.io/js/@type-crafter%2Fmcp-server.svg)](https://www.npmjs.com/package/@type-crafter/mcp-server)
 [![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)
 
-## What This MCP Does
+## Why This MCP?
 
-This MCP server helps LLMs:
+LLMs often make mistakes when writing Type Crafter YAML specs:
 
-1. **Learn** the correct YAML specification format
-2. **Validate** YAML specs before generation
-3. **Avoid** common mistakes like `nullable: true` (which doesn't exist)
+| Common Mistake     | Why It Fails                    |
+| ------------------ | ------------------------------- |
+| `nullable: true`   | Property doesn't exist          |
+| `optional: true`   | Property doesn't exist          |
+| `name?: string`    | Syntax not supported            |
+| Top-level arrays   | Arrays must be properties       |
+| `../relative/path` | Paths must be from project root |
 
-Type generation is handled by the `type-crafter` CLI in your project.
+This MCP **teaches** LLMs the correct format and **validates** specs before generation.
+
+## Installation
+
+```bash
+# Install MCP server
+npm install -g @type-crafter/mcp-server
+
+# Also need type-crafter CLI for generation
+npm install -g type-crafter
+```
+
+## Configuration
+
+### Claude Desktop
+
+**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+
+**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "type-crafter": {
+      "command": "type-crafter-mcp"
+    }
+  }
+}
+```
+
+### From Source
+
+```json
+{
+  "mcpServers": {
+    "type-crafter": {
+      "command": "node",
+      "args": ["/path/to/type-crafter/mcp/dist/index.js"]
+    }
+  }
+}
+```
 
 ## Tools
 
 ### 1. `get-writing-guide`
 
-**CALL THIS FIRST** - Returns the writing guide and a sessionId.
+**Call this FIRST.** Returns the writing guide and a sessionId.
 
 ```
+Parameters: none
+
 Returns:
 - sessionId (pass to other tools)
 - Quick start guide
@@ -33,62 +80,76 @@ Returns:
 
 Get detailed rules for a specific topic.
 
-**Parameters:**
-
-- `sessionId` (optional): Session ID from get-writing-guide
-- `section` (required): One of:
-  - `structure` - Root structure, info section, types vs groupedTypes
-  - `types` - Objects, enums, primitives, arrays
-  - `nullable` - How `required` array controls nullability
-  - `references` - $ref syntax, top-file vs non-top-file rules
-  - `composition` - oneOf (unions), allOf (intersections)
-  - `patterns` - Common patterns with full examples
+```
+Parameters:
+- sessionId (optional): From get-writing-guide
+- section (required): One of:
+    - structure   → Root structure, info, types vs groupedTypes
+    - types       → Objects, enums, primitives, arrays
+    - nullable    → How required array controls nullability
+    - references  → $ref syntax, top-file vs non-top-file
+    - composition → oneOf (unions), allOf (intersections)
+    - patterns    → Common patterns with examples
+```
 
 ### 3. `validate-spec`
 
-Validate a YAML spec file for correctness.
-
-**Parameters:**
+Validate a YAML spec for correctness.
 
-- `sessionId` (optional): Session ID from get-writing-guide
-- `specFilePath` (required): Path to the YAML specification file
-
-**Checks:**
+```
+Parameters:
+- sessionId (optional): From get-writing-guide
+- specFilePath (required): Path to YAML file
 
+Checks:
 - Structure (info, types, groupedTypes)
 - Common mistakes (nullable, optional, wrong paths)
-- Top-file vs non-top-file reference rules
+- Reference rules (top-file vs non-top-file)
+```
 
 ### 4. `get-spec-info`
 
 Get information about an existing spec file.
 
-**Parameters:**
-
-- `specFilePath` (required): Path to the YAML specification file
-
-**Returns:**
+```
+Parameters:
+- specFilePath (required): Path to YAML file
 
+Returns:
 - Version and title
 - List of all types
 - List of all grouped types
+```
 
 ### 5. `list-languages`
 
-List supported languages for the type-crafter CLI.
+List supported languages for type-crafter CLI.
+
+```
+Parameters: none
+
+Returns:
+- typescript
+- typescript-with-decoders
+```
 
-## Recommended Workflow
+## Workflow
 
 ```
-1. Call get-writing-guide
-   ↓
-2. Write YAML spec (following the guide)
-   ↓
-3. Call validate-spec
-   ↓
-4. Fix any issues (use get-rules-section for details)
-   ↓
-5. Run type-crafter CLI in your project
+┌─────────────────────────────────────────────────────────────┐
+│  1. get-writing-guide                                       │
+│     └─→ Returns sessionId + guide                           │
+│                                                             │
+│  2. Write YAML spec (following the guide)                   │
+│                                                             │
+│  3. validate-spec(sessionId, specFilePath)                  │
+│     ├─→ Valid: "Run type-crafter generate..."               │
+│     └─→ Errors: Shows issues + suggests get-rules-section   │
+│                                                             │
+│  4. Fix issues, re-validate                                 │
+│                                                             │
+│  5. User runs: type-crafter generate typescript spec.yaml   │
+└─────────────────────────────────────────────────────────────┘
 ```
 
 ## Session Enforcement
@@ -100,120 +161,135 @@ The MCP uses sessions to encourage reading the guide first:
 - If validation fails with common mistakes AND no sessionId → suggests reading the guide
 - Sessions expire after 30 minutes
 
-## Installation
-
-### Prerequisites
+## YAML Quick Reference
 
-- Node.js >= 18.0.0
-- `type-crafter` CLI installed in your project
+```yaml
+info:
+  version: '1.0.0'
+  title: 'My Types'
 
-```bash
-npm install -g type-crafter
-# or locally
-npm install type-crafter
+types:
+  User:
+    type: object
+    required:
+      - id # Required → string
+      - email # Required → string
+    properties:
+      id: { type: string }
+      email: { type: string }
+      name: { type: string } # Not in required → string | null
 ```
 
-### Install MCP Server
+**Generated TypeScript:**
 
-```bash
-npm install -g @type-crafter/mcp-server
+```typescript
+export type User = {
+  id: string;
+  email: string;
+  name: string | null;
+};
 ```
 
-## Configuration
+## Key Rules
 
-### Claude Desktop
+| Rule                      | Correct                            | Wrong                   |
+| ------------------------- | ---------------------------------- | ----------------------- |
+| Nullable fields           | Omit from `required` array         | `nullable: true`        |
+| Optional fields           | Omit from `required` array         | `optional: true`        |
+| Arrays                    | Property inside object             | Top-level type          |
+| External refs             | `./path/from/root/file.yaml#/Type` | `../relative/path.yaml` |
+| Same-file refs (top file) | `#/types/TypeName`                 | -                       |
+| Same-file refs (non-top)  | `./this/file.yaml#/TypeName`       | `#/TypeName`            |
 
-Edit your Claude Desktop config:
+## Usage Examples
 
-**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+### Creating Types
 
-**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
-
-```json
-{
-  "mcpServers": {
-    "type-crafter": {
-      "command": "type-crafter-mcp"
-    }
-  }
-}
 ```
+User: "Create types for a user API with id, email, and optional name"
 
-### From Source
-
-```json
-{
-  "mcpServers": {
-    "type-crafter": {
-      "command": "node",
-      "args": ["/path/to/type-crafter/mcp/dist/index.js"]
-    }
-  }
-}
+LLM: [Calls get-writing-guide]
+     [Reads the guide, notes required array controls nullability]
+     [Creates YAML spec]
+     [Calls validate-spec]
+     "Here's your valid spec. Run: type-crafter generate typescript ./types.yaml ./output"
 ```
 
-## Usage Examples
-
-### Learning the Format
+### Validating Specs
 
 ```
-User: "I need to create types for a user API"
+User: "Check if my types.yaml is valid"
 
-LLM: [Calls get-writing-guide]
-LLM: "I've read the Type Crafter guide. Here's what I learned..."
-LLM: [Creates YAML following the rules]
-LLM: [Calls validate-spec to verify]
+LLM: [Calls validate-spec]
+     "Found 2 issues:
+      1. Line 15: 'nullable: true' doesn't exist - use required array
+      2. Line 23: Wrong path format - use ./path/from/root"
 ```
 
-### Validating Existing Spec
+### Learning Specific Rules
 
 ```
-User: "Check if my types.yaml is valid"
+User: "How do references work in Type Crafter?"
 
-LLM: [Calls validate-spec with the file path]
-LLM: "Found 2 issues:
-     1. Line 15: 'nullable: true' doesn't exist - use required array
-     2. Line 23: Wrong path format..."
+LLM: [Calls get-rules-section with section: "references"]
+     "References in Type Crafter work like this..."
 ```
 
-### Deep Dive on Rules
+## Troubleshooting
 
-```
-User: "How do I make a field nullable?"
+### "nullable: true" errors
+
+Type Crafter doesn't have a `nullable` property. Use the `required` array:
 
-LLM: [Calls get-rules-section with section: "nullable"]
-LLM: "In Type Crafter, nullability is controlled by the required array..."
+```yaml
+# Properties in required → non-nullable
+# Properties NOT in required → nullable (Type | null)
+required:
+  - id
+  - email
+properties:
+  id: { type: string } # string
+  email: { type: string } # string
+  name: { type: string } # string | null
 ```
 
-## YAML Quick Reference
+### Reference path errors
+
+All paths are from project root (where you run the CLI), not relative to current file:
 
 ```yaml
-info:
-  version: '1.0.0'
-  title: 'My Types'
+# Wrong
+$ref: '../common/types.yaml#/User'
 
-types:
-  User:
-    type: object
-    required:
-      - id # Required → string
-      - email # Required → string
-    properties:
-      id: { type: string }
-      email: { type: string }
-      name: { type: string } # Not in required → string | null
+# Correct
+$ref: './src/common/types.yaml#/User'
 ```
 
-**Key Rules:**
+### "Arrays cannot be top-level types"
 
-- `nullable: true` does NOT exist - use `required` array
-- `optional: true` does NOT exist - use `required` array
-- Arrays cannot be top-level types
-- Paths are from project root, not relative to current file
+Arrays must be properties within objects:
+
+```yaml
+# Wrong
+Tags:
+  type: array
+  items: { type: string }
+
+# Correct
+Post:
+  type: object
+  properties:
+    tags:
+      type: array
+      items: { type: string }
+```
 
 ## Development
 
 ```bash
+# Install dependencies
+npm install
+
 # Build
 npm run build
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@type-crafter/mcp",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "MCP server for Type Crafter - generate types from YAML specifications",
   "type": "module",
   "main": "./dist/index.js",