# MCP Tool Schema Generator & Zod Validator (Claude, Cursor) (`nizantei/mcp-dev-utility`) Actor

A high-performance MCP server, Claude Desktop tool generator, and JSON schema validator that lets developers write, generate, and validate MCP tools with ease.

- **URL**: https://apify.com/nizantei/mcp-dev-utility.md
- **Developed by:** [Nitsan Teichholtz](https://apify.com/nizantei) (community)
- **Categories:** Developer tools, MCP servers
- **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.01 / actor start

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## MCP Developer Utility - Schema Generator & Zod Validator for Claude & Cursor

A high-performance **MCP server**, **Claude Desktop tool generator**, and **JSON schema validator** that empowers developers to instantly design, validate, and convert Model Context Protocol tools. Effortlessly generate robust JSON schemas, type-safe Zod TS definitions, and complete template servers from samples, OpenAPI definitions, Postman collections, JSON schemas, or cURL commands.

***

### ⚡ 30-Second Quickstart

Get up and running instantly with **Claude Desktop** or **Cursor** by linking this server to your configuration.

#### 1. Configure Claude Desktop

Add this server to your local `claude_desktop_config.json`:

- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "mcp-dev-utility": {
      "command": "node",
      "args": [
        "/absolute/path/to/mcp-dev-utility/dist/index.js"
      ]
    }
  }
}
```

*(Make sure to build the project first with `npm run build` and replace `/absolute/path/to/mcp-dev-utility` with the actual absolute path of this workspace.)*

#### 2. Worked Copy-Paste Example: Infer Zod & Schema From Sample

Ask Claude or use the MCP Inspector to run the `infer-schema-from-sample` tool:

**Input Parameters:**

- `toolName`: `"create-user"`
- `description`: `"Creates a new system user"`
- `sample`:
  ```json
  {
    "username": "johndoe",
    "email": "john@example.com",
    "age": 30,
    "settings": {
      "theme": "dark",
      "notifications": true
    }
  }
  ```

**Instant Generated Output (Zod Schema & MCP Template):**

```json
{
  "toolName": "create-user",
  "description": "Creates a new system user",
  "jsonSchema": {
    "type": "object",
    "properties": {
      "username": {
        "type": "string"
      },
      "email": {
        "type": "string"
      },
      "age": {
        "type": "number"
      },
      "settings": {
        "type": "object",
        "properties": {
          "theme": {
            "type": "string"
          },
          "notifications": {
            "type": "boolean"
          }
        },
        "required": [
          "theme",
          "notifications"
        ]
      }
    },
    "required": [
      "username",
      "email",
      "age",
      "settings"
    ]
  },
  "zodCode": "z.object({\n  username: z.string(),\n  email: z.string(),\n  age: z.number(),\n  settings: z.object({\n    theme: z.string(),\n    notifications: z.boolean()\n  })\n})",
  "serverTemplate": "import { McpServer } from \"@modelcontextprotocol/server\";\nimport { StdioServerTransport } from \"@modelcontextprotocol/server/stdio\";\nimport { z } from \"zod\";\n\nconst server = new McpServer({\n  name: \"custom-mcp-server\",\n  version: \"1.0.0\",\n});\n\nserver.registerTool(\n  \"create-user\",\n  {\n    description: \"Creates a new system user\",\n    inputSchema: z.object({\n      username: z.string(),\n      email: z.string(),\n      age: z.number(),\n      settings: z.object({\n        theme: z.string(),\n        notifications: z.boolean()\n      })\n    })\n  },\n  async (args) => { ... }\n);"
}
```

***

### 🛠️ Features & Tools

The server registers seven primary developer utility tools:

#### 1. `generate-mcp-tool-code`

Generates standard MCP input schema (`inputSchema`), Zod TypeScript validation code, and a fully functional, runnable `@modelcontextprotocol/server` TypeScript template based on a list of parameter definitions.

- **Inputs**:
  - `name` (string): The name of your custom tool (e.g. `get-weather` or `query-db`).
  - `description` (string): Human-readable prompt describing what the tool does (used by the model to call it).
  - `parameters` (array): A list of objects containing:
    - `name` (string)
    - `type` (`"string" | "number" | "boolean" | "array" | "object"`)
    - `description` (string)
    - `required` (boolean, optional)

- **Outputs**:
  - `jsonSchema`: The fully structured JSON schema for MCP.
  - `zodCode`: Type-safe Zod TS code.
  - `serverTemplate`: Complete TypeScript file template showing how to register the tool.

***

#### 2. `infer-schema-from-sample`

Instantly infers a complete JSON schema, Zod TS validation code, and standard MCP server template from a sample JSON arguments object. This allows you to draft tool definitions by simply supplying examples of what the arguments should look like!

- **Inputs**:
  - `toolName` (string): The name of the tool (e.g., `update-user`).
  - `description` (string): Description of what the tool does.
  - `sample` (object or JSON string): A sample JSON arguments payload (e.g., `{ "id": 101, "payload": { "name": "Alice" } }`).

- **Outputs**:
  - Inferred JSON schema.
  - Inferred Zod TS validation block.
  - Ready-to-go `@modelcontextprotocol/server` template.

***

#### 3. `validate-tool-arguments`

Validates a set of tool arguments (either a JSON object or raw string) against a provided JSON Schema to test if they conform to expectations. This is extremely useful for verifying mock client requests during local development.

- **Inputs**:
  - `schema` (object or string): The JSON Schema definition.
  - `arguments` (object or string): The payload/arguments to validate.

- **Outputs**:
  - `valid` (boolean): `true` if conforming.
  - `errors` (array of strings): High-fidelity error list detailing schema violations (paths and messages) if invalid.

***

#### 4. `convert-openapi-to-mcp`

Converts an OpenAPI 3.x operation schema (including path/query parameters and requestBody schemas) directly to a standard MCP tool schema, Zod validation code, and ready-to-run `@modelcontextprotocol/server` TypeScript template. This allows you to instantly migrate your existing REST API endpoints into fully-featured MCP tools.

- **Inputs**:
  - `operation` (object or JSON string): The OpenAPI operation object (containing `parameters` and/or `requestBody`).
  - `toolName` (string, optional): Override for the generated tool name (defaults to `operationId`).
  - `toolDescription` (string, optional): Override for the generated tool description (defaults to operation `description` or `summary`).

- **Outputs**:
  - `toolName`: The normalized name of the generated tool.
  - `description`: The prompt description.
  - `jsonSchema`: Combined MCP tool input JSON Schema.
  - `zodCode`: Unified Zod TS validation code (with query/body/path indicators).
  - `serverTemplate`: Complete TypeScript file template illustrating the tool registration.

***

#### 5. `convert-postman-to-mcp`

Converts a complete Postman collection (v2/v2.1) containing API requests (including query/path parameters, headers, urlencoded body, or raw JSON body) directly to standard MCP tool definitions (schemas + Zod code) and generates a combined runnable multi-tool MCP server template! This is highly effective for converting an entire Postman collection into a fully functioning multi-tool MCP server.

- **Inputs**:
  - `collection` (object or JSON string): The Postman Collection object or JSON string (v2/v2.1).

- **Outputs**:
  - `collectionName`: Name of the Postman Collection.
  - `description`: Description of the collection.
  - `tools`: An array of generated tools, each containing:
    - `toolName`: Normalized tool name.
    - `description`: Tool prompt description.
    - `jsonSchema`: MCP tool JSON Schema.
    - `zodCode`: Zod TS validation code.
  - `serverTemplate`: A complete combined `@modelcontextprotocol/server` TypeScript template registering and exporting all these tools.

***

#### 6. `convert-curl-to-mcp`

Converts a standard cURL command (including HTTP method, URL, headers, query parameters, and JSON or raw request body) to a standard MCP tool schema, Zod validation definitions, and a fully functional, runnable API client MCP server template! This allows developers to instantly turn any third-party API endpoint curl example into a fully-functional, runnable MCP tool with automatic argument mapping and secure Authorization setup.

- **Inputs**:
  - `curlCommand` (string): The full cURL command string to parse and convert.

- **Outputs**:
  - `toolName`: Normalized tool name.
  - `description`: Tool prompt description.
  - `jsonSchema`: MCP tool JSON Schema mapping curl parameters/body fields to arguments.
  - `zodCode`: Zod TS validation code.
  - `serverTemplate`: A complete runnable `@modelcontextprotocol/server` TypeScript template that uses native `fetch` to actually execute the API request dynamically mapping input arguments.

***

#### 7. `convert-jsonschema-to-mcp`

Converts a standard JSON Schema (v4/v6/v7/draft-07 or similar) to a standard MCP tool schema, Zod validation definitions, and a fully functional, runnable `@modelcontextprotocol/server` TypeScript template! This allows developers to instantly turn any existing JSON Schema representation of a tool or data structure into a complete, type-safe, and fully documented MCP tool definition.

- **Inputs**:
  - `schema` (object or string): The JSON Schema object or JSON string to parse and convert.
  - `toolName` (string, optional): Override for the generated tool name (defaults to schema `title` or `my-schema-tool`).
  - `toolDescription` (string, optional): Override for the generated tool description (defaults to schema `description`).

- **Outputs**:
  - `toolName`: Normalized tool name.
  - `description`: Tool prompt description.
  - `jsonSchema`: The parsed and validated MCP-compliant JSON Schema.
  - `zodCode`: Zod TS validation code.
  - `serverTemplate`: Complete TypeScript file template registering the schema-validated tool.

***

### 🚀 Getting Started

#### Prerequisites

- Node.js (v18+)
- npm

#### Installation

Clone or navigate to the workspace, then install dependencies:

```bash
npm install
```

#### Build & Test

- **Compile TypeScript**:
  ```bash
  npm run build
  ```
- **Run Unit Tests**:
  ```bash
  npm test
  ```

***

### 🔌 Running & Debugging the Server

Since MCP servers communicate over standard I/O (stdio) transport, you can run and test them using either the **MCP Inspector** or by adding them to your **Claude Desktop** config.

#### A. Testing with the MCP Inspector (Recommended)

Launch the official MCP Inspector web UI to interactively view and trigger your developer utility tools:

```bash
npx @modelcontextprotocol/inspector npx tsx src/index.ts
```

#### B. Integrating with Claude Desktop

Add `mcp-dev-utility` to your local `claude_desktop_config.json`:

- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

Add the server to the `mcpServers` section:

```json
{
  "mcpServers": {
    "mcp-dev-utility": {
      "command": "node",
      "args": [
        "/absolute/path/to/mcp-dev-utility/dist/index.js"
      ]
    }
  }
}
```

Restart Claude Desktop to make these developer utility tools accessible to the AI.

#### C. Apify Platform Self-Test Mode

When running on the Apify platform with no connected MCP client (or with `{"selfTest": true}` as input), the server automatically performs a quick self-test of the seven utility tools, writes the summary results to the default dataset, and exits cleanly (0) within seconds.

# Actor input Schema

## Actor input object example

```json
{}
```

# Actor output Schema

## `note` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {};

// Run the Actor and wait for it to finish
const run = await client.actor("nizantei/mcp-dev-utility").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {}

# Run the Actor and wait for it to finish
run = client.actor("nizantei/mcp-dev-utility").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{}' |
apify call nizantei/mcp-dev-utility --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,nizantei/mcp-dev-utility"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/Zf0kCQ2z5JGhs82Bk/builds/dByGMp3MtY3ms6n8V/openapi.json