a5c-ai/mcp-tool-schema-generator

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

{
  "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

{
  "$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

/**
 * 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

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