What is Mcp Schemas

mcp-schemas is a library that provides TypeScript types and Zod schemas for the Model Context Protocol (MCP), which is a JSON-RPC 2.0-based protocol designed for robust client/server communication in LLM and AI-assisted environments.

Use cases

Use cases for mcp-schemas include building AI tools that communicate using MCP, ensuring type safety in client-server interactions, and validating requests and responses in real-time to maintain protocol compliance.

How to use

To use mcp-schemas, install it via npm with ‘npm install mcp-schemas’. You can then import the necessary schemas and types in your TypeScript code to ensure type safety and runtime validation for your MCP requests and responses.

Key features

Key features of mcp-schemas include strong static typing for all protocol interactions, runtime validation using Zod, type-safe request/response definitions, and support for evolving schema specifications (currently MCP v2025-03-26).

Where to use

mcp-schemas can be used in any application that implements the Model Context Protocol, particularly in AI clients and servers that require reliable communication and data validation.

MCP Schemas

Type-safe TypeScript + Zod schemas for the Model Context Protocol (MCP)

🧠 Overview

mcp-schemas provides a suite of TypeScript types and Zod schemas for the Model Context Protocol (MCP)—a JSON-RPC 2.0-based protocol for robust client/server communication in LLM and AI-assisted environments.

• Strong static typing for all protocol interactions
• Runtime validation with Zod
• Type-safe request/response definitions
• Support for evolving schema specs (currently MCP v2025-03-26)

If you’re building tools or AI clients/servers that speak MCP, this library handles protocol compliance for you.

📦 Installation

npm install mcp-schemas

🚀 Usage

import { initializeRequestSchema, type InitializeRequest } from 'mcp-schemas';

// Type-safe usage
const request: InitializeRequest = {
  method: 'initialize',
  params: {
    protocolVersion: '2025-03-26',
    capabilities: {},
    clientInfo: { name: 'MyClient', version: '1.0.0' },
  },
};

// Runtime validation
initializeRequestSchema.parse(request);

All schemas are available as named exports:

import {
  listResourcesRequestSchema,
  callToolResultSchema,
  // ...etc
} from 'mcp-schemas';

Subpath Exports

Individual schemas can be imported directly via subpath exports to optimize bundle size:

// Import only what you need
import { initializeRequestSchema } from 'mcp-schemas/initialize-request';
import { callToolResultSchema } from 'mcp-schemas/call-tool-result';

Available subpaths include all schema names in kebab-case, such as:

• mcp-schemas/client-request
• mcp-schemas/server-result
• mcp-schemas/jsonrpc-error
• mcp-schemas/resource-template
• And many more

📚 Features

✅ Complete Protocol Coverage

• Supports all request/response/notification types in MCP
• Includes JSON-RPC 2.0 constructs: batch, error, notification, etc.

🧪 Runtime Validation

• Zod-based runtime validation for every protocol structure
• Use schema.safeParse(...) or .parse(...) to validate data

🔧 Type-safe Extensibility

• Modular and type-driven
• Compose new request types easily with withRequest() and withNotification()

🛠️ Development

All scripts use Bun:

# Install deps
bun install

# Type check
bun run typecheck

# Format code
bun run format

# Lint with autofix
bun run lint

# Run all verifications (format, lint, typecheck)
bun run verify

# Build the project
bun run build

🤝 Contributing

1. Fork the repo
2. Create a new branch
3. Add or modify schema files under src/schemas
4. Run bun run verify
5. Submit a pull request

Schema changes should align with the MCP specification and include type + Zod coverage.

💬 Attribution

Protocol spec © Model Context Protocol authors. This package provides typed tooling for protocol consumers.

MCP Schemas

Type-safe TypeScript & Zod schemas for the Model Context Protocol (MCP)
Version: 0.0.4 | Author: Steve Kinney | License: MIT

Peer Dependencies: typescript ^5
Runtime Dependencies: zod ^3.24.4

Table of Contents

• Overview
• Installation
• Usage
• Exports
• Features
• Development
• Contributing
• License

Overview

mcp-schemas provides a comprehensive suite of TypeScript types and Zod schemas for the Model Context Protocol (MCP) (currently spec version v2025-03-26). MCP is a JSON-RPC 2.0-based protocol for robust client/server communication in AI/LLM environments.

This library ensures:

• Strong static typing for all protocol interactions
• Runtime validation with Zod
• Type-safe request/response/notification definitions
• Ease of extensibility via withRequest() and withNotification() helpers

Installation

npm install mcp-schemas

Or with Bun:

bun install mcp-schemas

Usage

Import from the root:

import { initializeRequestSchema, type InitializeRequest } from 'mcp-schemas';

const request: InitializeRequest = {
  method: 'initialize',
  params: {
    protocolVersion: '2025-03-26',
    capabilities: {},
    clientInfo: { name: 'MyClient', version: '1.0.0' },
  },
};

initializeRequestSchema.parse(request);

Tree‑shakeable subpath imports (optimize bundle size):

import { initializeRequestSchema } from 'mcp-schemas/initialize-request';
import { callToolResultSchema } from 'mcp-schemas/call-tool-result';

Exports

• Root index (mcp-schemas): re‑exports all schemas from src/schemas
• Subpath exports: each schema under mcp-schemas/<schema-name>
• Entry points: main, module, and types all point to dist/index.js / dist/index.d.ts

Features

• ✅ Complete Protocol Coverage: All MCP request, response, and notification types (e.g., initialize, ping, completion/complete, batch operations, resources, prompts, tools, logging).
• 🧪 Runtime Validation: Zod schemas for every message—use .safeParse() or .parse() to validate.
• 🔧 Type-safe Extensibility: Utilities to compose new request/notification types.
• 📦 Modular Exports: Tree‑shakeable subpath imports for minimal bundle sizes.

Development

All scripts use Bun:

bun install
bun run typecheck      # TypeScript type checking
bun run format         # Prettier formatting
bun run lint           # ESLint with autofix
bun run verify         # format, lint, typecheck
bun run build          # Build dist artifacts

Contributing

1. Fork the repository
2. Create a feature branch
3. Add or update schema files under src/schemas
4. Run bun run verify
5. Submit a pull request

Ensure changes align with the MCP specification and include both TypeScript and Zod schema updates.