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:

Clear Purpose: What the parameter does
Valid Values: Acceptable inputs
Examples: Concrete usage examples
Constraints: Limits and validation rules
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

Parse parameters - Validate parameter definitions
Infer types - Determine TypeScript/Zod types
Generate JSON Schema - Create draft 2020-12 schema
Generate TypeScript - Create interface definitions
Generate Zod schema - Create validation code
Create examples - Generate valid example inputs
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