mcp-lint

0.4.0 verified Fri May 01 auth: no javascript

Lint MCP server tool schemas for cross-client compatibility across Claude, Cursor, Gemini, VS Code Copilot, Windsurf, Cline, OpenAI Agents SDK, and Continue.dev. Current stable version: 0.4.0 (MIT). mcp-lint provides static analysis and runtime preflight checks to catch JSON Schema quirks and client-specific incompatibilities before deployment. Ships TypeScript types and supports JSON/YAML input, auto-fix, compatibility matrix output, and rule explainability. Requires Node >=20. Key differentiator: unlike generic JSON Schema validators, mcp-lint is aware of each MCP client's unique schema expectations and known limitations.

Common errors

error ERR_REQUIRE_ESM: require() of ES Module not supported ↓

cause Attempting to use mcp-lint with CommonJS require() on an ESM-only package.

fix

Switch to dynamic import() or use import statement after adding "type": "module" to package.json.

error SyntaxError: Unexpected token '??=' ↓

cause Running mcp-lint on a Node.js version below 20 that does not support modern JavaScript syntax.

fix

Upgrade Node.js to version 20 or later.

error Error: Cannot find module 'mcp-lint' ↓

cause Package not installed or not in node_modules when running via npx without install.

fix

Run npx mcp-lint@latest check tools.json or install locally with npm install mcp-lint.

Warnings

breaking Node.js >=20 is required; older versions will throw a syntax error due to ESM-only distribution. ↓

fix Upgrade to Node.js 20 or later.

gotcha ESM-only release: CommonJS require() does not work. Using require('mcp-lint') will fail. ↓

fix Use import syntax and ensure your project is configured for ESM (e.g., type: 'module' in package.json).

gotcha The `inputSchema` property name is case-sensitive. Some clients expect `inputSchema` while others accept `parameters`. mcp-lint defaults to the MCP spec's `inputSchema`. ↓

fix Ensure your tool schemas use the exact property name `inputSchema` as per the MCP specification.

Install

npm install mcp-lint

yarn add mcp-lint

pnpm add mcp-lint

Imports

mcp-lint
wrong
```
import mcpLint from 'mcp-lint'
```
correct
```
import { lint } from 'mcp-lint'
```
ESM-only package. The package exposes named exports, not a default export.
check
wrong
```
const { check } = require('mcp-lint')
```
correct
```
import { check } from 'mcp-lint'
```
Package is ESM-only and cannot be used with require() in Node <20 or without ESM configuration.
explain
```
import { explain } from 'mcp-lint'
```
Used to fetch rule documentation programmatically.

Quickstart

Shows how to programmatically lint an MCP server tool schema file with mcp-lint, filtering by clients and severity.

import { check } from 'mcp-lint';
import { readFileSync } from 'fs';

const fileContents = readFileSync('tools.json', 'utf-8');
const tools = JSON.parse(fileContents);

const results = await check(tools, {
  clients: ['claude', 'cursor', 'openai'],
  severity: 'error'
});

for (const result of results) {
  console.log(`${result.tool}: ${result.severity} - ${result.message}`);
}