Skip to content
reaatechREAATECH

@reaatech/mcp-gateway-validation

npm v1.0.0

Validates MCP protocol messages and custom tool arguments against JSON Schemas using AJV. It provides an Express middleware for JSON-RPC 2.0 request validation and a schema manager for registering and versioning tool-specific input and output schemas.

@reaatech/mcp-gateway-validation

npm version License: MIT CI

Status: Pre-1.0 — APIs may change in minor versions. Pin to a specific version in production.

JSON Schema validation for MCP protocol messages. Built on AJV (v8) with support for custom per-tool input/output schemas, schema caching, and Express middleware that validates all JSON-RPC 2.0 and MCP method payloads.

Installation

terminal
npm install @reaatech/mcp-gateway-validation
# or
pnpm add @reaatech/mcp-gateway-validation

Feature Overview

  • JSON-RPC 2.0 validation — enforces jsonrpc, id, method, params structure
  • MCP method schemas — built-in validation for tools/call, tools/list, resources/*, prompts/*, initialize, shutdown
  • Per-tool argument validation — register custom JSON Schemas per tool name for input/output checking
  • Schema caching — compiled AJV validators are cached with configurable TTL
  • Custom schema manager — runtime schema registration, retrieval, versioning, and rollback
  • Express middlewarecreateValidationMiddleware() validates every JSON-RPC request
  • Dual ESM/CJS output — works with import and require

Quick Start

typescript
import {
  createValidationMiddleware,
  getSchemaValidator,
} from "@reaatech/mcp-gateway-validation";
import express from "express";
 
const app = express();
app.use(express.json());
app.use(createValidationMiddleware());
 
app.post("/mcp", (req, res) => {
  // req.rpcBody is typed — request already validated
  console.log("Method:", req.rpcBody?.method);
});
typescript
// Register custom tool schemas
import { getCustomSchemaManager } from "@reaatech/mcp-gateway-validation";
 
const manager = getCustomSchemaManager();
manager.registerSchema("my_tool", {
  type: "object",
  properties: {
    query: { type: "string" },
    limit: { type: "number", minimum: 1, maximum: 100 },
  },
  required: ["query"],
});
 
const result = manager.validateArguments("my_tool", { query: "hello" });
// → { valid: true }

API Reference

SchemaValidator (class)

Core AJV-based validator.

MethodDescription
validateJsonRpcRequest(body)Validate JSON-RPC 2.0 request structure
validateMcpRequest(method, params)Validate MCP method params against built-in schemas
validateToolArguments(toolName, args)Validate tool arguments against registered schema
cacheToolSchema(toolName, schema)Compile and cache a custom tool schema
getToolSchema(toolName)Get cached tool schema
clearCache()Clear all cached validators

getSchemaValidator()

Returns or creates the singleton SchemaValidator instance.

resetSchemaValidator()

Reset the singleton (for testing).

CustomSchemaManager (class)

Per-tool custom schema lifecycle.

MethodDescription
registerSchema(toolName, schema)Register a new schema (auto-versions)
getSchema(toolName)Get current schema for a tool
validateArguments(toolName, args)Validate arguments against registered schema
validateOutput(toolName, output)Validate output against registered schema
hasSchema(toolName)Check if tool has a registered schema
getToolNames()List all tools with registered schemas
getVersionHistory(toolName)Get version history for a tool
rollback(toolName)Rollback to previous schema version
removeSchema(toolName)Remove schema for a tool
clear()Remove all schemas

Middleware

ExportDescription
createValidationMiddleware()Express middleware — validates JSON-RPC and MCP method params. Attaches rpcBody and validationErrors to request.

MCP Method Schemas

ExportDescription
jsonRpcRequestSchemaBase JSON-RPC 2.0 schema
toolsCallRequestSchematools/call — requires params.name
toolsListRequestSchematools/list
initializeRequestSchemainitialize
resourcesListRequestSchemaresources/list
resourcesReadRequestSchemaresources/read
promptsListRequestSchemaprompts/list
promptsGetRequestSchemaprompts/get
notificationsInitializedSchemanotifications/initialized
shutdownRequestSchemashutdown
mcpMethodSchemasMap<string, JSONSchema> of all method schemas

Types

TypeDescription
ValidationResult{ valid: boolean, errors: ValidationError[] }
ValidationError{ field: string, expected: string, received: string, message: string }
SchemaCacheEntry{ schema, cachedAt, ttl, validator? }

Standard Error Codes

CodeMeaning
-32700Parse error (invalid JSON)
-32600Invalid request (not JSON-RPC 2.0)
-32601Method not found
-32602Invalid params

Usage Patterns

Full request validation pipeline

typescript
import {
  createValidationMiddleware,
  getSchemaValidator,
} from "@reaatech/mcp-gateway-validation";
 
const validator = getSchemaValidator();
 
app.post("/mcp", createValidationMiddleware(), (req, res, next) => {
  const { method, params } = req.rpcBody!;
 
  // Additional method-level validation
  const result = validator.validateMcpRequest(method, params);
  if (!result.valid) {
    return res.status(400).json({
      jsonrpc: "2.0",
      error: {
        code: -32602,
        message: "Invalid params",
        data: { errors: result.errors },
      },
    });
  }
 
  next();
});

Custom tool schema registration

typescript
import { getCustomSchemaManager } from "@reaatech/mcp-gateway-validation";
 
const manager = getCustomSchemaManager();
 
// Register at startup from config
for (const [toolName, schema] of Object.entries(toolSchemas)) {
  manager.registerSchema(toolName, schema);
}
 
// Validate during request processing
const { valid, errors } = manager.validateArguments("my_tool", args);
if (!valid) {
  console.error("Invalid arguments:", errors);
}

License

MIT