@type-crafter/mcp 0.5.0 → 1.0.0

package/README.md

@@ -1,162 +1,134 @@
 # 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
+## What This MCP Does
 
-The MCP server exposes the following tools:
+This MCP server helps LLMs:
 
-### 1. `generate-types`
+1. **Learn** the correct YAML specification format
+2. **Validate** YAML specs before generation
+3. **Avoid** common mistakes like `nullable: true` (which doesn't exist)
 
-Generate type definitions from a YAML specification file.
+Type generation is handled by the `type-crafter` CLI in your project.
 
-**Parameters:**
+## Tools
 
-- `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`)
+### 1. `get-writing-guide`
 
-**Example:**
+**CALL THIS FIRST** - Returns the writing guide and a sessionId.
 
-```json
-{
-  "language": "typescript",
-  "specFilePath": "./types.yaml",
-  "outputDirectory": "./generated-types",
-  "typesWriterMode": "SingleFile",
-  "groupedTypesWriterMode": "FolderWithFiles"
-}
+```
+Returns:
+- sessionId (pass to other tools)
+- Quick start guide
+- Common mistakes to avoid
+- Quick reference table
 ```
 
-### 2. `validate-spec`
+### 2. `get-rules-section`
 
-Validate a YAML specification file without generating types.
+Get detailed rules for a specific topic.
 
 **Parameters:**
 
-- `specFilePath` (required): Path to the YAML specification file to validate
-
-**Example:**
-
-```json
-{
-  "specFilePath": "./types.yaml"
-}
-```
-
-### 3. `list-languages`
+- `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
 
-List all supported target languages for type generation.
+### 3. `validate-spec`
 
-**Parameters:** None
-
-### 4. `get-spec-info`
-
-Get detailed information about a YAML specification file including version, title, and all defined types.
+Validate a YAML spec file for correctness.
 
 **Parameters:**
 
+- `sessionId` (optional): Session ID from get-writing-guide
 - `specFilePath` (required): Path to the YAML specification file
 
-**Example:**
-
-```json
-{
-  "specFilePath": "./types.yaml"
-}
-```
+**Checks:**
 
-### 5. `get-spec-rules`
+- Structure (info, types, groupedTypes)
+- Common mistakes (nullable, optional, wrong paths)
+- Top-file vs non-top-file reference 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.
+### 4. `get-spec-info`
 
-**Parameters:** None
+Get information about an existing spec file.
 
-**Use this tool when:**
+**Parameters:**
 
-- 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
+- `specFilePath` (required): Path to the YAML specification file
 
-**Returns:** Complete specification rules documentation including:
+**Returns:**
 
-- 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
+- Version and title
+- List of all types
+- List of all grouped types
 
-## Prerequisites
+### 5. `list-languages`
 
-- Node.js >= 18.0.0
-- `type-crafter` CLI installed globally or locally
+List supported languages for the type-crafter CLI.
 
-Install Type Crafter CLI:
+## Recommended Workflow
 
-```bash
-npm install -g type-crafter
 ```
-
-## Installation
-
-### Option 1: Install from npm (Recommended)
-
-Install the MCP server globally:
-
-```bash
-npm install -g @type-crafter/mcp-server
+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
 ```
 
-Or install locally in your project:
+## Session Enforcement
 
-```bash
-npm install @type-crafter/mcp-server
-```
+The MCP uses sessions to encourage reading the guide first:
 
-### Option 2: Install from Source
+- `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
 
-1. Clone the repository:
+## Installation
 
-```bash
-git clone https://github.com/sinha-sahil/type-crafter.git
-cd type-crafter/mcp-server
-```
+### Prerequisites
 
-2. Install dependencies:
+- Node.js >= 18.0.0
+- `type-crafter` CLI installed in your project
 
 ```bash
-npm install
+npm install -g type-crafter
+# or locally
+npm install type-crafter
 ```
 
-3. Build the server:
+### Install MCP Server
 
 ```bash
-npm run build
+npm install -g @type-crafter/mcp-server
 ```
 
 ## Configuration
 
-### Using with Claude Desktop (Global Installation)
+### Claude Desktop
 
-After installing globally via npm:
-
-Edit your Claude Desktop configuration file:
+Edit your Claude Desktop config:
 
 **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
 
 **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
 
-**For global installation:**
-
 ```json
 {
   "mcpServers": {
@@ -167,28 +139,14 @@ Edit your Claude Desktop configuration file:
 }
 ```
 
-**For local installation (from source):**
+### From Source
 
 ```json
 {
   "mcpServers": {
     "type-crafter": {
       "command": "node",
-      "args": ["/absolute/path/to/type-crafter/mcp-server/dist/index.js"]
-    }
-  }
-}
-```
-
-**For project-local npm installation:**
-
-```json
-{
-  "mcpServers": {
-    "type-crafter": {
-      "command": "npx",
-      "args": ["type-crafter-mcp"],
-      "cwd": "/path/to/your/project"
+      "args": ["/path/to/type-crafter/mcp/dist/index.js"]
     }
   }
 }
@@ -196,142 +154,76 @@ Edit your Claude Desktop configuration file:
 
 ## Usage Examples
 
-Once configured, you can use the MCP server through Claude Desktop:
-
-1. **Get specification rules (before writing specs):**
+### Learning the Format
 
-   ```
-   Show me the rules for writing Type Crafter YAML specification files
-   ```
-
-2. **Generate TypeScript types:**
+```
+User: "I need to create types for a user API"
 
-   ```
-   Generate TypeScript types from my spec.yaml file and save them to ./types
-   ```
+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]
+```
 
-3. **Validate a specification:**
+### Validating Existing Spec
 
-   ```
-   Validate my types.yaml specification file
-   ```
+```
+User: "Check if my types.yaml is valid"
 
-4. **Get spec information:**
+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..."
+```
 
-   ```
-   Show me information about the types defined in my spec.yaml
-   ```
+### Deep Dive on Rules
 
-5. **List available languages:**
-   ```
-   What languages does Type Crafter support?
-   ```
+```
+User: "How do I make a field nullable?"
 
-## YAML Specification Format
+LLM: [Calls get-rules-section with section: "nullable"]
+LLM: "In Type Crafter, nullability is controlled by the required array..."
+```
 
-The YAML specification should follow this structure:
+## YAML Quick Reference
 
 ```yaml
 info:
-  version: 0.0.0
-  title: Title of your specification
+  version: '1.0.0'
+  title: 'My Types'
 
 types:
-  TypeName:
+  User:
     type: object
+    required:
+      - id # Required → string
+      - email # Required → string
     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](../README.md).
-
-## Development
-
-### Build
-
-```bash
-npm run build
+      id: { type: string }
+      email: { type: string }
+      name: { type: string } # Not in required → string | null
 ```
 
-### Watch mode
+**Key Rules:**
 
-```bash
-npm run dev
-```
+- `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
 
 ## Development
 
-### Building from Source
-
 ```bash
+# Build
 npm run build
-```
-
-### Watch Mode
 
-```bash
+# Watch mode
 npm run dev
-```
-
-### Linting
 
-```bash
+# Lint
 npm run lint
-npm run lint:fix
-```
-
-## Testing the Package Locally
-
-Before publishing or to test the installed package:
-
-```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
-
-- 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](./LICENSE) file for details
+ISC