mcp-tool-schema-generator

What this skill does

# MCP Tool Schema Generator

Generate comprehensive JSON Schema definitions for MCP tools that are optimized for AI consumption, with clear descriptions, type constraints, and validation rules.

## Capabilities

- Generate JSON Schema for tool inputs
- Create TypeScript types from schemas
- Generate Zod validation schemas
- Produce AI-optimized descriptions
- Support complex nested structures
- Handle enums, unions, and constraints

## Usage

Invoke this skill when you need to:
- Define input schemas for MCP tools
- Create type-safe tool parameter definitions
- Generate validation logic for tool inputs
- Document tool parameters for AI consumption

## Inputs

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| toolName | string | Yes | Name of the MCP tool |
| description | string | Yes | Tool description |
| parameters | array | Yes | List of parameter definitions |
| outputFormat | string | No | json-schema, zod, or typescript (default: all) |
| examples | array | No | Example inputs for documentation |

### Parameter Definition Structure

```json
{
  "parameters": [
    {
      "name": "path",
      "type": "string",
      "description": "File path to read",
      "required": true,
      "constraints": {
        "pattern": "^[a-zA-Z0-9_/.-]+$",
        "maxLength": 255
      }
    },
    {
      "name": "encoding",
      "type": "string",
      "description": "File encoding",
      "required": false,
      "default": "utf-8",
      "enum": ["utf-8", "ascii", "base64"]
    },
    {
      "name": "options",
      "type": "object",
      "description": "Read options",
      "required": false,
      "properties": [
        { "name": "maxSize", "type": "number", "description": "Max bytes to read" },
        { "name": "follow", "type": "boolean", "description": "Follow symlinks" }
      ]
    }
  ]
}
```

## Output Structure

```
schemas/
├── <toolName>/
│   ├── schema.json           # JSON Schema definition
│   ├── schema.ts             # TypeScript types
│   ├── validation.ts         # Zod validation schema
│   ├── examples.json         # Example inputs
│   └── README.md             # Schema documentation
```

## Generated Code Patterns

### JSON Schema Output

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "mcp://tools/read_file/input",
  "title": "read_file Input Schema",
  "description": "Read contents of a file from the filesystem",
  "type": "object",
  "properties": {
    "path": {
      "type": "string",
      "description": "File path to read. Must be a valid filesystem path.",
      "pattern": "^[a-zA-Z0-9_/.-]+$",
      "maxLength": 255,
      "examples": ["/home/user/document.txt", "./config.json"]
    },
    "encoding": {
      "type": "string",
      "description": "File encoding. Defaults to UTF-8 for text files.",
      "enum": ["utf-8", "ascii", "base64"],
      "default": "utf-8"
    },
    "options": {
      "type": "object",
      "description": "Additional read options",
      "properties": {
        "maxSize": {
          "type": "integer",
          "description": "Maximum bytes to read. Use for large files.",
          "minimum": 1,
          "maximum": 10485760
        },
        "follow": {
          "type": "boolean",
          "description": "Whether to follow symbolic links",
          "default": true
        }
      }
    }
  },
  "required": ["path"],
  "additionalProperties": false
}
```

### TypeScript Types Output

```typescript
/**
 * Input parameters for the read_file tool
 * @description Read contents of a file from the filesystem
 */
export interface ReadFileInput {
  /**
   * File path to read. Must be a valid filesystem path.
   * @pattern ^[a-zA-Z0-9_/.-]+$
   * @maxLength 255
   * @example "/home/user/document.txt"
   */
  path: string;

  /**
   * File encoding. Defaults to UTF-8 for text files.
   * @default "utf-8"
   */
  encoding?: 'utf-8' | 'ascii' | 'base64';

  /**
   * Additional read options
   */
  options?: {
    /**
     * Maximum bytes to read. Use for large files.
     * @minimum 1
     * @maximum 10485760
     */
    maxSize?: number;

    /**
     * Whether to follow symbolic links
     * @default true
     */
    follow?: boolean;
  };
}
```

### Zod Validation Output

```typescript
import { z } from 'zod';

/**
 * Zod schema for read_file tool input validation
 */
export const ReadFileInputSchema = z.object({
  path: z
    .string()
    .regex(/^[a-zA-Z0-9_/.-]+$/, 'Invalid path characters')
    .max(255, 'Path too long')
    .describe('File path to read. Must be a valid filesystem path.'),

  encoding: z
    .enum(['utf-8', 'ascii', 'base64'])
    .optional()
    .default('utf-8')
    .describe('File encoding. Defaults to UTF-8 for text files.'),

  options: z
    .object({
      maxSize: z
        .number()
        .int()
        .min(1)
        .max(10485760)
        .optional()
        .describe('Maximum bytes to read. Use for large files.'),

      follow: z
        .boolean()
        .optional()
        .default(true)
        .describe('Whether to follow symbolic links'),
    })
    .optional()
    .describe('Additional read options'),
}).strict();

export type ReadFileInput = z.infer<typeof ReadFileInputSchema>;
```

## Supported Types

| Type | JSON Schema | TypeScript | Zod |
|------|-------------|------------|-----|
| string | string | string | z.string() |
| number | number | number | z.number() |
| integer | integer | number | z.number().int() |
| boolean | boolean | boolean | z.boolean() |
| array | array | T[] | z.array() |
| object | object | interface | z.object() |
| enum | enum | union | z.enum() |
| null | null | null | z.null() |
| union | oneOf | union | z.union() |

## Constraint Support

| Constraint | Types | JSON Schema | Zod |
|------------|-------|-------------|-----|
| minLength | string | minLength | .min() |
| maxLength | string | maxLength | .max() |
| pattern | string | pattern | .regex() |
| format | string | format | .email()/.url() |
| minimum | number | minimum | .min() |
| maximum | number | maximum | .max() |
| multipleOf | number | multipleOf | .multipleOf() |
| minItems | array | minItems | .min() |
| maxItems | array | maxItems | .max() |
| uniqueItems | array | uniqueItems | custom |

## AI-Optimized Descriptions

The skill generates descriptions optimized for AI consumption:

1. **Clear Purpose**: What the parameter does
2. **Valid Values**: Acceptable inputs
3. **Examples**: Concrete usage examples
4. **Constraints**: Limits and validation rules
5. **Defaults**: What happens if omitted

Example:
```
"File path to read. Must be an absolute or relative path to an existing file.
Supports Unix and Windows path formats. Maximum length: 255 characters.
Example: '/home/user/config.json'"
```

## Workflow

1. **Parse parameters** - Validate parameter definitions
2. **Infer types** - Determine TypeScript/Zod types
3. **Generate JSON Schema** - Create draft 2020-12 schema
4. **Generate TypeScript** - Create interface definitions
5. **Generate Zod schema** - Create validation code
6. **Create examples** - Generate valid example inputs
7. **Document schema** - Create README with usage

## Best Practices Applied

- JSON Schema draft 2020-12 compliance
- Strict mode (additionalProperties: false)
- Comprehensive descriptions for AI
- Type-safe TypeScript interfaces
- Runtime validation with Zod
- Example inputs for each parameter

## References

- JSON Schema Specification: https://json-schema.org/
- MCP Tool Documentation: https://modelcontextprotocol.io/docs/tools
- Zod Documentation: https://zod.dev/

## Target Processes

- mcp-tool-implementation
- mcp-tool-documentation
- argument-parser-setup