mcp-lint 0.2.0 → 0.4.0

package/README.md

@@ -3,11 +3,11 @@
 [![npm version](https://img.shields.io/npm/v/mcp-lint?color=crimson)](https://www.npmjs.com/package/mcp-lint)
 [![npm downloads](https://img.shields.io/npm/dm/mcp-lint)](https://www.npmjs.com/package/mcp-lint)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
-[![Node.js ≥18](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
+[![Node.js ≥20](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](https://nodejs.org)
 
 **Lint MCP server tool schemas for cross-client compatibility.**
 
-MCP servers expose tool schemas consumed by **Claude**, **Cursor**, **Gemini**, and **VS Code Copilot**. Each client has different JSON Schema support and quirks — a schema that works in Claude may silently break in Cursor. `mcp-lint` catches these issues before your users do.
+MCP servers expose tool schemas consumed by **Claude**, **Cursor**, **Gemini**, **VS Code Copilot**, **Windsurf**, **Cline**, **OpenAI Agents SDK**, and **Continue.dev**. Each client has different JSON Schema support and quirks — a schema that works in Claude may silently break in Cursor or OpenAI. `mcp-lint` catches these issues before your users do.
 
 ```
 $ npx mcp-lint check tools.json
@@ -41,21 +41,80 @@ npm install --save-dev mcp-lint
 ## Quick Start
 
 ```bash
-# Generate a config file
-mcp-lint init
-
 # Check a JSON or YAML file
 mcp-lint check tools.json
-mcp-lint check tools.yaml
 
-# Check a live MCP server (stdio)
-mcp-lint check --server stdio -- node my-server.js
+# See compatibility across all clients at a glance
+mcp-lint compat tools.json
 
-# Check a live MCP server (SSE)
-mcp-lint check --server sse --url http://localhost:3000/sse
+# Learn what a rule does
+mcp-lint explain openai/no-additional-properties
 
 # Auto-fix what can be fixed
 mcp-lint fix tools.json --in-place
+
+# Generate a config file
+mcp-lint init
+```
+
+---
+
+## `mcp-lint compat` — Compatibility Matrix
+
+See exactly which tools work with which clients:
+
+```
+$ mcp-lint compat tools.json
+
+                    claude    cursor    gemini    vscode    windsurf  cline     openai    continue
+search-tool         ✓         ✗         ✓         ✓         ✓         ✓         ✓         ✓
+file-reader         ✓         ✓         ✗         ✓         ✓         ✓         ✓         ✗
+database-query      ✓         ✓         ✓         ✓         ✓         ✓         ✗         ✓
+
+2 tools have compatibility issues. Run `mcp-lint check` for details.
+```
+
+```bash
+mcp-lint compat tools.json --format markdown         # for PRs and GitHub Step Summary
+mcp-lint compat tools.json --format json             # machine-readable
+mcp-lint compat tools.json --client openai           # single client column
+mcp-lint compat --server stdio -- node server.js
+```
+
+---
+
+## `mcp-lint explain` — Rule Documentation
+
+```
+$ mcp-lint explain openai/no-additional-properties
+
+Rule: openai/no-additional-properties
+Severity:  error
+Clients:   openai
+Fixable:   yes
+
+Description
+OpenAI Agents SDK strict mode requires `additionalProperties: false` on the root inputSchema.
+
+Why
+OpenAI's strict function calling mode rejects schemas that don't explicitly set
+`additionalProperties: false` at the root level.
+
+Bad example
+{
+  "type": "object",
+  "properties": { "q": { "type": "string" } }
+}
+
+Good example
+{
+  "type": "object",
+  "properties": { "q": { "type": "string" } },
+  "additionalProperties": false
+}
+
+Auto-fix
+Add `"additionalProperties": false` to the root inputSchema.
 ```
 
 ---
@@ -73,15 +132,21 @@ mcp-lint check tools.json --format json       # machine-readable (CI/CD)
 mcp-lint check tools.json --format markdown   # for PRs and GitHub summaries
 
 # Filters
-mcp-lint check tools.json --clients claude,cursor    # only these clients' rules
-mcp-lint check tools.json --severity error           # errors only
-mcp-lint check tools.json --quiet                    # same as --severity error
+mcp-lint check tools.json --clients claude,cursor,openai   # only these clients' rules
+mcp-lint check tools.json --severity error                 # errors only
+mcp-lint check tools.json --quiet                          # same as --severity error
 mcp-lint check tools.json --ignore "debug-tool,internal-tool"
 
 # Config
 mcp-lint check tools.json --config path/to/.mcplintrc.json
 mcp-lint check tools.json --no-color
 
+# Quality score (0–100 per tool with A-F grades)
+mcp-lint check tools.json --score
+
+# Watch mode (re-lints on file change)
+mcp-lint check tools.json --watch
+
 # Live servers
 mcp-lint check --server stdio -- node my-server.js
 mcp-lint check --server stdio -- python my_server.py arg1 arg2
@@ -98,6 +163,20 @@ mcp-lint check --server sse --url http://localhost:3000/sse
 
 ---
 
+### `mcp-lint diff <before> <after>`
+
+Compare lint results between two versions of your schema — useful in CI to catch regressions.
+
+```bash
+mcp-lint diff tools-v1.json tools-v2.json
+mcp-lint diff tools-v1.json tools-v2.json --format markdown >> $GITHUB_STEP_SUMMARY
+mcp-lint diff tools-v1.json tools-v2.json --format json
+```
+
+**Exit codes:** `0` = no new errors introduced, `1` = new errors found, `2` = error
+
+---
+
 ### `mcp-lint fix [input]`
 
 Auto-fixes issues that are safe to fix automatically (no semantic changes).
@@ -163,6 +242,31 @@ mcp-lint init --force  # overwrite existing
 |------|----------|---------|-------------|
 | `vscode/max-params` | 🟡 warning | ❌ | VS Code Copilot performance degrades with more than 15 parameters |
 
+### Windsurf-specific
+
+| Rule | Severity | Fixable | Description |
+|------|----------|---------|-------------|
+| `windsurf/no-union-types` | 🟡 warning | ❌ | `anyOf` with more than 2 variants not supported |
+
+### Cline-specific
+
+| Rule | Severity | Fixable | Description |
+|------|----------|---------|-------------|
+| `cline/description-max-length` | 🟡 warning | ✅ | Descriptions over 200 characters are truncated by Cline |
+
+### OpenAI Agents SDK-specific
+
+| Rule | Severity | Fixable | Description |
+|------|----------|---------|-------------|
+| `openai/no-additional-properties` | 🔴 error | ✅ | Strict mode requires `additionalProperties: false` on root inputSchema |
+| `openai/strict-types` | 🔴 error | ❌ | Only `string`, `number`, `boolean`, `object`, `array`, `null` allowed |
+
+### Continue.dev-specific
+
+| Rule | Severity | Fixable | Description |
+|------|----------|---------|-------------|
+| `continue/no-default-values` | 🟡 warning | ❌ | Continue.dev ignores `default` fields — document defaults in descriptions instead |
+
 ---
 
 ## Configuration
@@ -171,29 +275,79 @@ mcp-lint init --force  # overwrite existing
 
 ```json
 {
-  "$schema": "https://raw.githubusercontent.com/robert19001-cmyk/mcp-lint/main/config-schema.json",
   "rules": {
     "no-required-false": "error",
     "description-exists": "warning",
     "max-depth": "off",
     "claude/no-type-array": "error"
   },
-  "clients": ["claude", "cursor", "gemini", "vscode"],
+  "clients": ["claude", "cursor", "gemini", "vscode", "windsurf", "cline", "openai", "continue"],
   "ignore": ["internal-debug-tool"],
   "maxDepth": 5
 }
 ```
 
+### Presets
+
+Use `"extends"` to start from a built-in preset:
+
+```json
+{ "extends": "recommended" }
+```
+
+```json
+{
+  "extends": "strict",
+  "rules": {
+    "description-exists": "warning"
+  }
+}
+```
+
+| Preset | Description |
+|--------|-------------|
+| `recommended` | All 8 clients enabled, default severities |
+| `strict` | All rules set to `error`, `maxDepth: 3` |
+
 Rule severities: `"error"` | `"warning"` | `"info"` | `"off"`
 
 ---
 
 ## CI/CD — GitHub Actions
 
+### Using the official Action
+
 ```yaml
 name: MCP Schema Lint
 on: [push, pull_request]
 
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: robert19001-cmyk/mcp-lint@v0.3.0
+        with:
+          input: tools.json
+          severity: warning
+          score: 'true'
+          fail_on: error
+```
+
+**Action inputs:**
+
+| Input | Default | Description |
+|-------|---------|-------------|
+| `input` | _(required)_ | Path to MCP tools JSON file |
+| `format` | `terminal` | `terminal\|json\|markdown` |
+| `severity` | `info` | Minimum severity to report |
+| `clients` | all | Comma-separated client filter |
+| `fail_on` | `error` | Fail CI when issues at this severity found |
+| `score` | `false` | Show quality score |
+
+### Manual workflow
+
+```yaml
 jobs:
   lint:
     runs-on: ubuntu-latest
@@ -205,17 +359,61 @@ jobs:
       # Fail the build on errors
       - run: npx mcp-lint check ./src/tools.json
 
-      # Post a summary to the PR
-      - run: npx mcp-lint check ./src/tools.json --format markdown >> $GITHUB_STEP_SUMMARY
+      # Post compatibility matrix to PR summary
+      - run: npx mcp-lint compat ./src/tools.json --format markdown >> $GITHUB_STEP_SUMMARY
         if: always()
 
-      # Save JSON results as artifact
-      - run: npx mcp-lint check ./src/tools.json --format json > lint-results.json || true
-      - uses: actions/upload-artifact@v4
+      # Diff against previous version
+      - run: npx mcp-lint diff tools-before.json tools-after.json --format markdown >> $GITHUB_STEP_SUMMARY
         if: always()
-        with:
-          name: mcp-lint-results
-          path: lint-results.json
+```
+
+---
+
+## Plugin API
+
+Share and reuse rule sets via npm packages.
+
+### Using a plugin
+
+```bash
+npm install mcp-lint-config-nextjs
+```
+
+```json
+{
+  "plugins": ["mcp-lint-config-nextjs"],
+  "extends": "recommended"
+}
+```
+
+### Writing a plugin
+
+A plugin is an npm package that exports a `rules` array of `Rule` objects:
+
+```typescript
+// mcp-lint-config-myserver/index.ts
+import type { Rule } from 'mcp-lint';
+
+const myRule: Rule = {
+  id: 'myserver/no-large-params',
+  severity: 'warning',
+  description: 'My server limits param count to 10',
+  clients: ['claude', 'cursor'],
+  check(tool) {
+    const count = Object.keys(tool.inputSchema.properties ?? {}).length;
+    if (count > 10) return [{
+      toolName: tool.name,
+      ruleId: 'myserver/no-large-params',
+      severity: 'warning',
+      message: `Too many params (${count})`,
+      path: 'inputSchema.properties',
+    }];
+    return [];
+  },
+};
+
+export const rules = [myRule];
 ```
 
 ---
@@ -231,7 +429,7 @@ import { applyFixes } from 'mcp-lint/fixer';
 // Check
 const tools = await loadFile('tools.json');
 const engine = new LintEngine(allRules, {
-  clients: ['claude', 'cursor'],
+  clients: ['claude', 'cursor', 'openai'],
   ignore: ['debug-tool'],
 });
 const diagnostics = engine.lint(tools);
@@ -242,39 +440,113 @@ const fixed = applyFixes(tools, diagnostics);
 
 ---
 
-## Adding a Custom Rule
+## `mcp-lint preflight` — Runtime Decision Firewall
+
+**Lint catches bad schemas. Preflight catches bad actions.**
+
+At runtime, your agent is about to call a tool — delete a file, send a request, charge a card. Preflight sits between the agent and the action and answers:
 
-Create `src/rules/my-rule.ts`:
+- Is it allowed?
+- How risky is it? (0.0–1.0 deterministic score)
+- Is it reversible?
+- Does it need human approval?
+- Is there a safer alternative?
+
+```bash
+$ mcp-lint preflight action.json --policy preflight.yml
+
+Preflight Decision
+────────────────────────────────────────
+Decision:      DENY
+Risk score:    1.00
+Reversibility: irreversible
+Policies:      block-destructive-prod
+Reasons:       base_shell, destructive_pattern, sensitive_target, irreversible_operation
+```
+
+### Action format
+
+```json
+{
+  "tool_type": "shell",
+  "tool_name": "bash",
+  "action": "rm -rf /prod/data",
+  "target": "/prod/data",
+  "context": { "environment": "prod" }
+}
+```
+
+### Policy file (YAML)
+
+```yaml
+version: 1
+defaults:
+  approval_threshold: 0.70
+  block_threshold: 0.92
+
+rules:
+  - id: block-prod-delete
+    when:
+      tool_type: shell
+      action_matches: ["rm -rf"]
+      target_matches: ["/prod", "/etc"]
+    effect: deny
+
+  - id: rewrite-tmp-delete
+    when:
+      tool_type: shell
+      action_matches: ["rm -rf ./tmp"]
+    effect: allow_with_rewrite
+    rewrite:
+      tool_type: file_delete
+      action: move_to_trash
+      target: ./tmp
+
+  - id: approval-payments
+    when:
+      tool_type: payment
+    effect: require_approval
+```
+
+Sample policies in `examples/policies/`: `default.yml`, `strict.yml`, `permissive-dev.yml`.
+
+### SDK — embed in your MCP server or agent runtime
 
 ```typescript
-import type { Rule } from 'mcp-lint/core/rule';
+import { preflight, loadPolicy } from 'mcp-lint/preflight';
 
-export const myRule: Rule = {
-  id: 'my-rule',
-  severity: 'warning',
-  description: 'What this rule checks',
-  clients: ['claude', 'cursor', 'gemini', 'vscode'],
-
-  check(tool, context) {
-    const diagnostics = [];
-
-    if (someCondition(tool.inputSchema)) {
-      diagnostics.push({
-        ruleId: 'my-rule',
-        severity: 'warning',
-        message: 'Human-readable explanation',
-        toolName: tool.name,
-        path: 'inputSchema.properties.something',
-        clients: this.clients,
-      });
-    }
-
-    return diagnostics;
+const policy = await loadPolicy('./preflight.yml');
+
+const decision = preflight(
+  {
+    tool_type: 'shell',
+    tool_name: 'bash',
+    action: 'rm -rf /tmp',
+    target: '/tmp',
   },
-};
+  policy,
+);
+
+if (decision.decision === 'deny') {
+  throw new Error(`Blocked: ${decision.reasons.join(', ')}`);
+}
+if (decision.decision === 'require_approval') {
+  await askUser(decision);
+}
+if (decision.decision === 'allow_with_rewrite') {
+  return executeSafer(decision.safe_alternative);
+}
 ```
 
-Register it in `src/rules/index.ts` and add tests in `tests/rules/my-rule.test.ts`.
+### Exit codes
+
+| Code | Meaning |
+|------|---------|
+| `0`  | allow / allow_with_rewrite |
+| `1`  | require_approval |
+| `2`  | deny / error |
+
+Use them directly in shell wrappers or CI gates.
 
 ---
 

package/dist/cli/commands/check.js

@@ -1,3 +1,4 @@
+import { watch } from 'node:fs';
 import { loadFile } from '../../loaders/file-loader.js';
 import { loadStdio } from '../../loaders/stdio-loader.js';
 import { loadSSE } from '../../loaders/sse-loader.js';
@@ -7,6 +8,10 @@ import { formatTerminal } from '../formatters/terminal.js';
 import { formatJson } from '../formatters/json.js';
 import { formatMarkdown } from '../formatters/markdown.js';
 import { loadConfig } from '../../config/config.js';
+import { loadPluginRules } from '../../config/plugin-loader.js';
+import { writeFile } from 'fs/promises';
+import chalk from 'chalk';
+import { computeQualityReport } from '../../core/quality-score.js';
 const SEVERITY_ORDER = { error: 3, warning: 2, info: 1 };
 function filterBySeverity(diagnostics, min) {
     return diagnostics.filter((d) => SEVERITY_ORDER[d.severity] >= SEVERITY_ORDER[min]);
@@ -24,65 +29,106 @@ export function registerCheckCommand(program) {
         .option('--quiet', 'Only output errors (no warnings/info)')
         .option('--server <type>', 'Server transport: stdio|sse')
         .option('--url <url>', 'SSE server URL (use with --server sse)')
+        .option('--output-file <path>', 'Write results to a file instead of stdout')
+        .option('--watch', 'Re-lint on file change (only works with file input)')
+        .option('--score', 'Show quality score (0–100) per tool')
         .allowExcessArguments(true)
         .action(async (input, options) => {
-        try {
-            const fileConfig = await loadConfig(options.config);
-            const cliClients = options.clients
-                ? options.clients.split(',').map((s) => s.trim())
-                : undefined;
-            const config = {
-                ...fileConfig,
-                ...(cliClients ? { clients: cliClients } : {}),
-                ignore: [
-                    ...(fileConfig.ignore ?? []),
-                    ...(options.ignore ? options.ignore.split(',').map((s) => s.trim()) : []),
-                ],
-            };
-            let tools;
-            if (options.server === 'stdio') {
-                // Get everything after '--' in process.argv
-                const rawArgv = process.argv;
-                const sepIdx = rawArgv.indexOf('--');
-                if (sepIdx === -1 || sepIdx >= rawArgv.length - 1) {
-                    throw new Error('--server stdio requires a command after --, e.g.: mcp-lint check --server stdio -- node server.js');
+        async function runLint() {
+            try {
+                const fileConfig = await loadConfig(options.config);
+                const cliClients = options.clients
+                    ? options.clients.split(',').map((s) => s.trim())
+                    : undefined;
+                const config = {
+                    ...fileConfig,
+                    ...(cliClients ? { clients: cliClients } : {}),
+                    ignore: [
+                        ...(fileConfig.ignore ?? []),
+                        ...(options.ignore ? options.ignore.split(',').map((s) => s.trim()) : []),
+                    ],
+                };
+                let tools;
+                if (options.server === 'stdio') {
+                    // Get everything after '--' in process.argv
+                    const rawArgv = process.argv;
+                    const sepIdx = rawArgv.indexOf('--');
+                    if (sepIdx === -1 || sepIdx >= rawArgv.length - 1) {
+                        throw new Error('--server stdio requires a command after --, e.g.: mcp-lint check --server stdio -- node server.js');
+                    }
+                    const [cmd, ...cmdArgs] = rawArgv.slice(sepIdx + 1);
+                    tools = await loadStdio(cmd, cmdArgs);
                 }
-                const [cmd, ...cmdArgs] = rawArgv.slice(sepIdx + 1);
-                tools = await loadStdio(cmd, cmdArgs);
-            }
-            else if (options.server === 'sse') {
-                if (!options.url)
-                    throw new Error('--server sse requires --url <url>');
-                tools = await loadSSE(options.url);
-            }
-            else {
-                if (!input)
-                    throw new Error('Specify an input file or use --server stdio|sse');
-                tools = await loadFile(input);
-            }
-            const engine = new LintEngine(allRules, config);
-            let diagnostics = engine.lint(tools);
-            const minSeverity = options.quiet
-                ? 'error'
-                : options.severity ?? 'info';
-            diagnostics = filterBySeverity(diagnostics, minSeverity);
-            let output;
-            if (options.format === 'json') {
-                output = formatJson(diagnostics);
+                else if (options.server === 'sse') {
+                    if (!options.url)
+                        throw new Error('--server sse requires --url <url>');
+                    tools = await loadSSE(options.url);
+                }
+                else {
+                    if (!input)
+                        throw new Error('Specify an input file or use --server stdio|sse');
+                    tools = await loadFile(input);
+                }
+                const pluginRules = await loadPluginRules(fileConfig);
+                const engine = new LintEngine([...allRules, ...pluginRules], config);
+                let diagnostics = engine.lint(tools);
+                const minSeverity = options.quiet
+                    ? 'error'
+                    : options.severity ?? 'info';
+                diagnostics = filterBySeverity(diagnostics, minSeverity);
+                let output;
+                if (options.format === 'json') {
+                    output = formatJson(diagnostics);
+                }
+                else if (options.format === 'markdown') {
+                    output = formatMarkdown(diagnostics);
+                }
+                else {
+                    output = formatTerminal(diagnostics, !options.color);
+                }
+                if (options.outputFile) {
+                    await writeFile(options.outputFile, output, 'utf8');
+                }
+                else {
+                    process.stdout.write(output);
+                }
+                if (options.score) {
+                    const report = computeQualityReport(tools, diagnostics);
+                    const gradeColor = (g) => g === 'A' ? chalk.green(g) : g === 'B' ? chalk.cyan(g) : g === 'C' ? chalk.yellow(g) : chalk.red(g);
+                    process.stdout.write(chalk.bold('\nQuality Score\n'));
+                    for (const t of report.tools) {
+                        process.stdout.write(`  ${t.toolName.padEnd(30)} ${String(t.score).padStart(3)}/100  ${gradeColor(t.grade)}  (${t.errors} errors, ${t.warnings} warnings)\n`);
+                    }
+                    process.stdout.write(`\n  Overall: ${chalk.bold(String(report.overall))}/100  ${gradeColor(report.grade)}\n\n`);
+                }
+                const hasErrors = diagnostics.some((d) => d.severity === 'error');
+                return hasErrors;
             }
-            else if (options.format === 'markdown') {
-                output = formatMarkdown(diagnostics);
+            catch (err) {
+                process.stderr.write(`Error: ${err.message}\n`);
+                return true;
             }
-            else {
-                output = formatTerminal(diagnostics, !options.color);
+        }
+        if (options.watch) {
+            if (!input || options.server) {
+                process.stderr.write('Error: --watch only works with file input\n');
+                process.exit(2);
             }
-            process.stdout.write(output);
-            const hasErrors = diagnostics.some((d) => d.severity === 'error');
-            process.exit(hasErrors ? 1 : 0);
+            process.stdout.write(chalk.dim(`Watching ${input} for changes...\n\n`));
+            await runLint();
+            let debounce = null;
+            watch(input, () => {
+                if (debounce)
+                    clearTimeout(debounce);
+                debounce = setTimeout(async () => {
+                    process.stdout.write(chalk.dim(`\n[${new Date().toLocaleTimeString()}] File changed — re-linting...\n\n`));
+                    await runLint();
+                }, 100);
+            });
         }
-        catch (err) {
-            process.stderr.write(`Error: ${err.message}\n`);
-            process.exit(2);
+        else {
+            const hasErrors = await runLint();
+            process.exit(hasErrors ? 1 : 0);
         }
     });
 }