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.