@type-crafter/mcp 0.1.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2024 Sahil Sinha
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,337 @@
+# Type Crafter MCP Server
+
+An MCP (Model Context Protocol) server for Type Crafter that allows AI assistants to generate type definitions from 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
+
+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:**
+
+```json
+{
+  "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:**
+
+```json
+{
+  "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:**
+
+```json
+{
+  "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:
+
+```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
+```
+
+Or install locally in your project:
+
+```bash
+npm install @type-crafter/mcp-server
+```
+
+### Option 2: Install from Source
+
+1. Clone the repository:
+
+```bash
+git clone https://github.com/sinha-sahil/type-crafter.git
+cd type-crafter/mcp-server
+```
+
+2. Install dependencies:
+
+```bash
+npm install
+```
+
+3. Build the server:
+
+```bash
+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:**
+
+```json
+{
+  "mcpServers": {
+    "type-crafter": {
+      "command": "type-crafter-mcp"
+    }
+  }
+}
+```
+
+**For local installation (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"
+    }
+  }
+}
+```
+
+## 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:
+
+```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
+```
+
+For more details on the specification format, see the [main Type Crafter README](../README.md).
+
+## Development
+
+### Build
+
+```bash
+npm run build
+```
+
+### Watch mode
+
+```bash
+npm run dev
+```
+
+## Development
+
+### Building from Source
+
+```bash
+npm run build
+```
+
+### Watch Mode
+
+```bash
+npm run dev
+```
+
+### Linting
+
+```bash
+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

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,354 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import fs from 'fs/promises';
+import path from 'path';
+import { parse as parseYaml } from 'yaml';
+import { exec } from 'child_process';
+import { promisify } from 'util';
+const execAsync = promisify(exec);
+// Helper function to read YAML files
+async function readYaml(filePath) {
+    const fileContent = await fs.readFile(filePath, 'utf-8');
+    return parseYaml(fileContent);
+}
+// Helper function to validate spec structure
+function validateSpecData(data) {
+    if (typeof data !== 'object' || data === null) {
+        return { valid: false };
+    }
+    const spec = data;
+    // Check for required info
+    if (typeof spec.info !== 'object' || spec.info === null) {
+        return { valid: false };
+    }
+    const info = spec.info;
+    if (typeof info.version !== 'string' || typeof info.title !== 'string') {
+        return { valid: false };
+    }
+    // At least one of types or groupedTypes must exist
+    const hasTypes = typeof spec.types === 'object' && spec.types !== null;
+    const hasGroupedTypes = typeof spec.groupedTypes === 'object' && spec.groupedTypes !== null;
+    if (!hasTypes && !hasGroupedTypes) {
+        return { valid: false };
+    }
+    return {
+        valid: true,
+        info: { version: info.version, title: info.title },
+        types: hasTypes ? spec.types : undefined,
+        groupedTypes: hasGroupedTypes ? spec.groupedTypes : undefined,
+    };
+}
+// Create server instance
+const server = new McpServer({
+    name: 'type-crafter-mcp-server',
+    version: '0.1.0',
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+// Register generate-types tool
+server.registerTool('generate-types', {
+    description: 'Generate type definitions from a YAML specification file. Supports TypeScript and TypeScript with decoders. ' +
+        'The YAML spec should follow the Type Crafter format with info, types, and/or groupedTypes sections.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            language: {
+                type: 'string',
+                description: 'Target language for type generation',
+                enum: ['typescript', 'typescript-with-decoders'],
+            },
+            specFilePath: {
+                type: 'string',
+                description: 'Path to the YAML specification file',
+            },
+            outputDirectory: {
+                type: 'string',
+                description: 'Directory where generated types will be written',
+            },
+            typesWriterMode: {
+                type: 'string',
+                description: 'Writer mode for types: SingleFile or Files',
+                enum: ['SingleFile', 'Files'],
+            },
+            groupedTypesWriterMode: {
+                type: 'string',
+                description: 'Writer mode for grouped types: FolderWithFiles or SingleFile',
+                enum: ['FolderWithFiles', 'SingleFile'],
+            },
+        },
+        required: ['language', 'specFilePath', 'outputDirectory'],
+    },
+}, async (args) => {
+    const { language, specFilePath, outputDirectory, typesWriterMode = 'SingleFile', groupedTypesWriterMode = 'SingleFile', } = args;
+    // Validate language
+    if (!['typescript', 'typescript-with-decoders'].includes(language.toLowerCase())) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Error: Unsupported language "${language}". Supported languages: typescript, typescript-with-decoders`,
+                },
+            ],
+            isError: true,
+        };
+    }
+    // Resolve paths
+    const resolvedSpecPath = path.resolve(specFilePath);
+    const resolvedOutputPath = path.resolve(outputDirectory);
+    // Check if spec file exists
+    try {
+        await fs.access(resolvedSpecPath);
+    }
+    catch {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Error: Specification file not found at ${resolvedSpecPath}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+    // Use the type-crafter CLI to generate types
+    const cliCommand = `type-crafter generate ${language} "${resolvedSpecPath}" "${resolvedOutputPath}" ${typesWriterMode} ${groupedTypesWriterMode}`;
+    try {
+        const { stdout, stderr } = await execAsync(cliCommand);
+        const warningText = typeof stderr !== 'undefined' && stderr.length > 0 ? '\nWarnings:\n' + stderr : '';
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Successfully generated ${language} types from ${specFilePath}\nOutput saved to: ${outputDirectory}\n\n${stdout}${warningText}`,
+                },
+            ],
+        };
+    }
+    catch (error) {
+        const err = error;
+        const errorDetails = err.stderr ?? err.stdout ?? '';
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Error generating types: ${err.message}\n${errorDetails}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+// Register validate-spec tool
+server.registerTool('validate-spec', {
+    description: 'Validate a YAML specification file without generating types. ' +
+        'Checks if the spec file is valid and can be processed by Type Crafter.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            specFilePath: {
+                type: 'string',
+                description: 'Path to the YAML specification file to validate',
+            },
+        },
+        required: ['specFilePath'],
+    },
+}, async (args) => {
+    const { specFilePath } = args;
+    // Resolve path
+    const resolvedSpecPath = path.resolve(specFilePath);
+    // Check if spec file exists
+    try {
+        await fs.access(resolvedSpecPath);
+    }
+    catch {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Error: Specification file not found at ${resolvedSpecPath}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+    // Try to read and validate the spec
+    const specFileData = await readYaml(resolvedSpecPath);
+    const validation = validateSpecData(specFileData);
+    if (!validation.valid || typeof validation.info === 'undefined') {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: 'Error: Invalid specification file. Neither types nor groupedTypes found!',
+                },
+            ],
+            isError: true,
+        };
+    }
+    const typesCount = typeof validation.types !== 'undefined' ? Object.keys(validation.types).length : 0;
+    const groupedTypesCount = typeof validation.groupedTypes !== 'undefined'
+        ? Object.keys(validation.groupedTypes).length
+        : 0;
+    return {
+        content: [
+            {
+                type: 'text',
+                text: `✓ Specification file is valid!\n\nInfo:\n  Version: ${validation.info.version}\n  Title: ${validation.info.title}\n  Types: ${typesCount}\n  Grouped Types: ${groupedTypesCount}`,
+            },
+        ],
+    };
+});
+// Register list-languages tool
+server.registerTool('list-languages', {
+    description: 'List all supported target languages for type generation',
+    inputSchema: {
+        type: 'object',
+        properties: {},
+    },
+}, async () => {
+    return {
+        content: [
+            {
+                type: 'text',
+                text: 'Supported Languages:\n\n1. typescript - Generate TypeScript type definitions\n2. typescript-with-decoders - Generate TypeScript types with runtime decoders',
+            },
+        ],
+    };
+});
+// Register get-spec-info tool
+server.registerTool('get-spec-info', {
+    description: 'Get information about a YAML specification file including version, title, ' +
+        'and counts of types and grouped types defined in the spec.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            specFilePath: {
+                type: 'string',
+                description: 'Path to the YAML specification file',
+            },
+        },
+        required: ['specFilePath'],
+    },
+}, async (args) => {
+    const { specFilePath } = args;
+    // Resolve path
+    const resolvedSpecPath = path.resolve(specFilePath);
+    // Check if spec file exists
+    try {
+        await fs.access(resolvedSpecPath);
+    }
+    catch {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Error: Specification file not found at ${resolvedSpecPath}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+    // Read and validate the spec
+    const specFileData = await readYaml(resolvedSpecPath);
+    const validation = validateSpecData(specFileData);
+    if (!validation.valid || typeof validation.info === 'undefined') {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: 'Error: Invalid specification file format',
+                },
+            ],
+            isError: true,
+        };
+    }
+    const typesCount = typeof validation.types !== 'undefined' ? Object.keys(validation.types).length : 0;
+    const groupedTypesCount = typeof validation.groupedTypes !== 'undefined'
+        ? Object.keys(validation.groupedTypes).length
+        : 0;
+    let infoText = 'Specification Info:\n\n';
+    infoText += `Version: ${validation.info.version}\n`;
+    infoText += `Title: ${validation.info.title}\n`;
+    infoText += `Types: ${typesCount}\n`;
+    infoText += `Grouped Types: ${groupedTypesCount}\n\n`;
+    if (typeof validation.types !== 'undefined' && typesCount > 0) {
+        infoText += 'Top-level Types:\n';
+        Object.keys(validation.types).forEach((typeName) => {
+            infoText += `  - ${typeName}\n`;
+        });
+        infoText += '\n';
+    }
+    if (typeof validation.groupedTypes !== 'undefined' && groupedTypesCount > 0) {
+        infoText += 'Grouped Types:\n';
+        Object.keys(validation.groupedTypes).forEach((groupName) => {
+            const group = validation.groupedTypes?.[groupName];
+            if (typeof group !== 'undefined' && group !== null && typeof group === 'object' && !('$ref' in group)) {
+                const typeNames = Object.keys(group);
+                infoText += `  ${groupName} (${typeNames.length} types):\n`;
+                typeNames.forEach((typeName) => {
+                    infoText += `    - ${typeName}\n`;
+                });
+            }
+            else {
+                infoText += `  ${groupName} (reference)\n`;
+            }
+        });
+    }
+    return {
+        content: [
+            {
+                type: 'text',
+                text: infoText,
+            },
+        ],
+    };
+});
+// Register get-spec-rules tool
+server.registerTool('get-spec-rules', {
+    description: 'Get comprehensive rules and guidelines for writing Type Crafter YAML specification files. ' +
+        'This provides LLMs with detailed information about the YAML spec format, type mappings, nullable types, ' +
+        'references, composition, best practices, and common patterns. Use this before creating or modifying spec files.',
+    inputSchema: {
+        type: 'object',
+        properties: {},
+    },
+}, async () => {
+    try {
+        // Read the SPEC_RULES.md file from src directory
+        const rulesPath = path.join(__dirname, '..', 'src', 'SPEC_RULES.md');
+        const rulesContent = await fs.readFile(rulesPath, 'utf-8');
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: rulesContent,
+                },
+            ],
+        };
+    }
+    catch (error) {
+        const err = error;
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Error reading spec rules: ${err.message}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+// Start the server
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error('Type Crafter MCP Server running on stdio');
+}
+main().catch((error) => {
+    console.error('Server error:', error);
+    process.exit(1);
+});