@type-crafter/mcp 0.6.0 → 1.1.0

package/README.md

@@ -1,323 +1,305 @@
 # Type Crafter MCP Server
 
-An MCP (Model Context Protocol) server for Type Crafter that allows AI assistants to generate type definitions from YAML specifications.
+An MCP (Model Context Protocol) server that helps AI assistants write correct Type Crafter YAML specifications.
 
 [![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)
 
-## Features
+## Why This MCP?
 
-The MCP server exposes the following tools:
+LLMs often make mistakes when writing Type Crafter YAML specs:
 
-### 1. `generate-types`
+| 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 |
 
-Generate type definitions from a YAML specification file.
+This MCP **teaches** LLMs the correct format and **validates** specs before generation.
 
-**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`)
+## Installation
 
-**Example:**
+```bash
+# Install MCP server
+npm install -g @type-crafter/mcp-server
 
-```json
-{
-  "language": "typescript",
-  "specFilePath": "./types.yaml",
-  "outputDirectory": "./generated-types",
-  "typesWriterMode": "SingleFile",
-  "groupedTypesWriterMode": "FolderWithFiles"
-}
+# Also need type-crafter CLI for generation
+npm install -g type-crafter
 ```
 
-### 2. `validate-spec`
-
-Validate a YAML specification file without generating types.
+## Configuration
 
-**Parameters:**
+### Claude Desktop
 
-- `specFilePath` (required): Path to the YAML specification file to validate
+**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
 
-**Example:**
+**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
 
 ```json
 {
-  "specFilePath": "./types.yaml"
+  "mcpServers": {
+    "type-crafter": {
+      "command": "type-crafter-mcp"
+    }
+  }
 }
 ```
 
-### 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:**
+### From Source
 
 ```json
 {
-  "specFilePath": "./types.yaml"
+  "mcpServers": {
+    "type-crafter": {
+      "command": "node",
+      "args": ["/path/to/type-crafter/mcp/dist/index.js"]
+    }
+  }
 }
 ```
 
-### 5. `get-spec-rules`
+## Tools
 
-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.
+### 1. `get-writing-guide`
 
-**Parameters:** None
+**Call this FIRST.** Returns the writing guide and a sessionId.
 
-**Use this tool when:**
+```
+Parameters: none
 
-- 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:
+- sessionId (pass to other tools)
+- Quick start guide
+- Common mistakes to avoid
+- Quick reference table
+```
 
-**Returns:** Complete specification rules documentation including:
+### 2. `get-rules-section`
 
-- 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
+Get detailed rules for a specific topic.
 
-## Prerequisites
+```
+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
+```
 
-- Node.js >= 18.0.0
-- `type-crafter` CLI installed globally or locally
+### 3. `validate-spec`
 
-Install Type Crafter CLI:
+Validate a YAML spec for correctness.
 
-```bash
-npm install -g type-crafter
+```
+Parameters:
+- sessionId (optional): From get-writing-guide
+- specFilePath (required): Path to YAML file
+
+Checks:
+- Structure (info, types, groupedTypes)
+- Common mistakes (nullable, optional, wrong paths)
+- Reference rules (top-file vs non-top-file)
 ```
 
-## Installation
-
-### Option 1: Install from npm (Recommended)
+### 4. `get-spec-info`
 
-Install the MCP server globally:
+Get information about an existing spec file.
 
-```bash
-npm install -g @type-crafter/mcp-server
 ```
+Parameters:
+- specFilePath (required): Path to YAML file
 
-Or install locally in your project:
-
-```bash
-npm install @type-crafter/mcp-server
+Returns:
+- Version and title
+- List of all types
+- List of all grouped types
 ```
 
-### Option 2: Install from Source
+### 5. `list-languages`
 
-1. Clone the repository:
+List supported languages for type-crafter CLI.
 
-```bash
-git clone https://github.com/sinha-sahil/type-crafter.git
-cd type-crafter/mcp-server
 ```
+Parameters: none
 
-2. Install dependencies:
-
-```bash
-npm install
+Returns:
+- typescript
+- typescript-with-decoders
 ```
 
-3. Build the server:
+## Workflow
 
-```bash
-npm run build
+```
+┌─────────────────────────────────────────────────────────────┐
+│  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   │
+└─────────────────────────────────────────────────────────────┘
 ```
 
-## Configuration
-
-### Using with Claude Desktop (Global Installation)
-
-After installing globally via npm:
+## Session Enforcement
 
-Edit your Claude Desktop configuration file:
+The MCP uses sessions to encourage reading the guide first:
 
-**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+- `get-writing-guide` returns a `sessionId`
+- Pass `sessionId` to other tools
+- If validation fails with common mistakes AND no sessionId → suggests reading the guide
+- Sessions expire after 30 minutes
 
-**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+## YAML Quick Reference
 
-**For global installation:**
+```yaml
+info:
+  version: '1.0.0'
+  title: 'My Types'
 
-```json
-{
-  "mcpServers": {
-    "type-crafter": {
-      "command": "type-crafter-mcp"
-    }
-  }
-}
+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
 ```
 
-**For local installation (from source):**
+**Generated TypeScript:**
 
-```json
-{
-  "mcpServers": {
-    "type-crafter": {
-      "command": "node",
-      "args": ["/absolute/path/to/type-crafter/mcp-server/dist/index.js"]
-    }
-  }
-}
+```typescript
+export type User = {
+  id: string;
+  email: string;
+  name: string | null;
+};
 ```
 
-**For project-local npm installation:**
+## Key Rules
 
-```json
-{
-  "mcpServers": {
-    "type-crafter": {
-      "command": "npx",
-      "args": ["type-crafter-mcp"],
-      "cwd": "/path/to/your/project"
-    }
-  }
-}
-```
+| 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`            |
 
 ## Usage Examples
 
-Once configured, you can use the MCP server through Claude Desktop:
+### Creating Types
 
-1. **Get specification rules (before writing specs):**
+```
+User: "Create types for a user API with id, email, and optional name"
 
-   ```
-   Show me the rules for writing Type Crafter YAML specification files
-   ```
+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"
+```
 
-2. **Generate TypeScript types:**
+### Validating Specs
 
-   ```
-   Generate TypeScript types from my spec.yaml file and save them to ./types
-   ```
+```
+User: "Check if my types.yaml is valid"
 
-3. **Validate a specification:**
+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"
+```
 
-   ```
-   Validate my types.yaml specification file
-   ```
+### Learning Specific Rules
 
-4. **Get spec information:**
+```
+User: "How do references work in Type Crafter?"
 
-   ```
-   Show me information about the types defined in my spec.yaml
-   ```
+LLM: [Calls get-rules-section with section: "references"]
+     "References in Type Crafter work like this..."
+```
 
-5. **List available languages:**
-   ```
-   What languages does Type Crafter support?
-   ```
+## Troubleshooting
 
-## YAML Specification Format
+### "nullable: true" errors
 
-The YAML specification should follow this structure:
+Type Crafter doesn't have a `nullable` property. Use the `required` array:
 
 ```yaml
-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
+# 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
 ```
 
-For more details on the specification format, see the [main Type Crafter README](../README.md).
+### Reference path errors
 
-## Development
+All paths are from project root (where you run the CLI), not relative to current file:
 
-### Build
+```yaml
+# Wrong
+$ref: '../common/types.yaml#/User'
 
-```bash
-npm run build
+# Correct
+$ref: './src/common/types.yaml#/User'
 ```
 
-### Watch mode
-
-```bash
-npm run dev
-```
+### "Arrays cannot be top-level types"
 
-### Linting
+Arrays must be properties within objects:
 
-```bash
-npm run lint
-npm run lint:fix
+```yaml
+# Wrong
+Tags:
+  type: array
+  items: { type: string }
+
+# Correct
+Post:
+  type: object
+  properties:
+    tags:
+      type: array
+      items: { type: string }
 ```
 
-## Testing the Package Locally
-
-Before publishing or to test the installed package:
+## Development
 
 ```bash
-# 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](./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
+# Install dependencies
+npm install
 
-- 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
+# Build
+npm run build
 
-## Contributing
+# Watch mode
+npm run dev
 
-Contributions are welcome! Please feel free to submit a Pull Request.
+# Lint
+npm run lint
+```
 
 ## License
 
-ISC - See [LICENSE](./LICENSE) file for details
+ISC