mcp-lint

library0.4.0jsnpmunverified

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.

devops testing

npm install mcp-lint

github ↗package ↗

INSTALL

IMPORT

SIG · MCP-LINT

mcp-lint

devopsjavascriptv0.4.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

mcp-lint

✓ import { lint } from 'mcp-lint'

✗ import mcpLint from 'mcp-lint'

ESM-only package. The package exposes named exports, not a default export.

check

✓ import { check } from 'mcp-lint'

✗ const { check } = require('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.

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}`); }

mcp-lint --version

Debug

Known issues

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

fix

Upgrade to Node.js 20 or later.

affects: >=0.0.0

gotchaESM-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).

affects: >=0.4.0

gotchaThe `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.

affects: >=0.0.0

Errors

Common errors & fixes

ERR_REQUIRE_ESM: require() of ES Module not supported

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.

SyntaxError: Unexpected token '??='

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: Cannot find module 'mcp-lint'

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`.

Upgrade

Version history

0.4.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/robert19001-cmyk/mcp-lint ↗

packagehttps://www.npmjs.com/package/mcp-lint ↗