mcp-lint

mcp-lint

MCP サーバーのツールスキーマをリントし、クライアント間の互換性を確認します。

MCP サーバーは、Claude、Cursor、Gemini、VS Code Copilot、Windsurf、Cline、OpenAI Agents SDK、Continue.dev などが利用するツールスキーマを公開します。クライアントごとに JSON Schema の対応状況や特有の挙動が異なるため、Claude で動作するスキーマが Cursor や OpenAI では気付かないうちに動作しなくなることがあります。mcp-lint は、ユーザーが問題に遭遇する前にこれらの問題を検出します。

$ npx mcp-lint check tools.json

search-tool
  ✖ Schema node at "inputSchema.properties.query" has `required: false` which is not valid JSON Schema.
    inputSchema.properties.query  [no-required-false]
  ⚠ Parameter "limit" in tool "search-tool" is missing a description.
    inputSchema.properties.limit  [description-exists]

1 error, 1 warning

---

インストール

# One-time use (no install)
npx mcp-lint check tools.json

# Global
npm install -g mcp-lint

# Per-project dev dependency
npm install --save-dev mcp-lint

---

クイックスタート

# Check a JSON or YAML file
mcp-lint check tools.json

# See compatibility across all clients at a glance
mcp-lint compat tools.json

# 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

# Run as an MCP server
mcp-lint-server

---

mcp-lint compat — 互換性マトリックス

どのツールがどのクライアントで動作するかを確認できます。

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

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 — ルールのドキュメント

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

---

CLI リファレンス

mcp-lint check [input]

mcp-lint check tools.json

# Output formats
mcp-lint check tools.json --format terminal   # default, colored output
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,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
mcp-lint check --server sse --url http://localhost:3000/sse

終了コード：

コード	意味
0	エラーなし（警告はカウントされません）
1	1 つ以上のエラーが見つかりました
2	入力が無効、または設定エラー

---

mcp-lint diff <before> <after>

スキーマの 2 つのバージョン間でリント結果を比較します。CI でリグレッションを検出するのに便利です。

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

終了コード： 0 = 新たなエラーなし、1 = 新たなエラーが見つかりました、2 = エラー

---

mcp-lint fix [input]

意味的な変更を加えずに安全に修正できる問題を自動修正します。

mcp-lint fix tools.json                            # fixed output to stdout
mcp-lint fix tools.json --output fixed-tools.json  # write to file
mcp-lint fix tools.json --in-place                 # overwrite original
mcp-lint fix tools.json --dry-run                  # show what would be fixed
mcp-lint fix tools.json --rules no-required-false,no-empty-enum  # specific rules only

---

mcp-lint init

現在のディレクトリにデフォルトの .mcplintrc.json を作成します。

mcp-lint init          # fails if file already exists
mcp-lint init --force  # overwrite existing

---

ルール

共通（すべてのクライアント）

ルール	重要度	修正可能	説明
no-required-false	🔴 error	✅	プロパティの required: false は有効な JSON Schema ではありません
no-content-encoding	🔴 error	✅	contentEncoding は MCP クライアントでサポートされていません
no-empty-enum	🔴 error	✅	空の enum: [] は、パラメーターを満たすことを不可能にします
no-recursive-refs	🔴 error	❌	循環する $ref は、ほとんどのクライアントでクラッシュを引き起こします
valid-json-schema-subset	🔴 error	❌	サポートされていないキーワード：oneOf、anyOf、allOf、if/then/else、not、patternProperties…
description-exists	🟡 warning	❌	ツールとパラメーターには説明を付けてください
max-depth	🟡 warning	❌	スキーマのネストが 5 階層を超えると、LLM の理解を妨げます
no-unsupported-formats	🟡 warning	✅	あまり一般的でない format の値（iri、json-pointer、regex…）は広くサポートされていません

Claude 固有

ルール	重要度	修正可能	説明
claude/no-type-array	🟡 warning	✅	"type": ["string", "null"] の配列構文は Claude で正しく動作しない場合があります

Cursor 固有

ルール	重要度	修正可能	説明
cursor/no-default-without-type	🔴 error	✅	default 値がある場合、Cursor では明示的な type が必要です
cursor/no-missing-title	🟡 warning	❌	Cursor はツール選択画面にツール名とパラメーター名を表示します

Gemini 固有

ルール	重要度	修正可能	説明
gemini/no-optional-without-default	🟡 warning	❌	default を明示すると、Gemini はオプションのパラメーターをより適切に処理できます
gemini/no-nested-objects	🟡 warning	❌	Gemini は 2 階層を超えるネストしたオブジェクトプロパティのサポートが限定的です

VS Code Copilot 固有

ルール	重大度	修正可能	説明
vscode/max-params	🟡 警告	❌	パラメーターが15個を超えると、VS Code Copilot のパフォーマンスが低下します

Windsurf 固有

ルール	重大度	修正可能	説明
windsurf/no-union-types	🟡 警告	❌	2つを超えるバリアントを持つ anyOf はサポートされません

Cline 固有

ルール	重大度	修正可能	説明
cline/description-max-length	🟡 警告	✅	200文字を超える説明は Cline によって切り詰められます

OpenAI Agents SDK 固有

ルール	重大度	修正可能	説明
openai/no-additional-properties	🔴 エラー	✅	Strict モードでは、ルートの inputSchema に additionalProperties: false が必要です
openai/strict-types	🔴 エラー	❌	string、number、boolean、object、array、null のみ使用できます

Continue.dev 固有

ルール	重大度	修正可能	説明
continue/no-default-values	🟡 警告	❌	Continue.dev は default フィールドを無視するため、代わりに説明にデフォルト値を記載してください

---

設定

mcp-lint は、現在のディレクトリからホームフォルダーまで .mcplintrc.json を自動検出します。--config で上書きできます。

{
  "rules": {
    "no-required-false": "error",
    "description-exists": "warning",
    "max-depth": "off",
    "claude/no-type-array": "error"
  },
  "clients": ["claude", "cursor", "gemini", "vscode", "windsurf", "cline", "openai", "continue"],
  "ignore": ["internal-debug-tool"],
  "maxDepth": 5
}

プリセット

組み込みプリセットをベースにするには、"extends" を使用します。

{ "extends": "recommended" }

{
  "extends": "strict",
  "rules": {
    "description-exists": "warning"
  }
}

プリセット	説明
recommended	8つすべてのクライアントを有効化し、デフォルトの重大度を使用します
strict	すべてのルールを error に設定し、maxDepth: 3 にします

ルールの重大度："error" | "warning" | "info" | "off"

---

CI/CD — GitHub Actions

公式 Action の使用

name: MCP Schema Lint
on: [push, pull_request]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: robert19001-cmyk/[email protected]
        with:
          input: tools.json
          severity: warning
          score: 'true'
          fail_on: error

Action の入力項目：

入力	デフォルト	説明
input	(必須)	MCP ツールの JSON ファイルへのパス
format	terminal	terminal|json|markdown
severity	info	報告する最小重大度
clients	all	クライアントをカンマ区切りで指定するフィルター
fail_on	error	この重大度の問題が見つかった場合に CI を失敗させます
score	false	品質スコアを表示します

手動ワークフロー

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 20 }

      # Fail the build on errors
      - run: npx mcp-lint check ./src/tools.json

      # Post compatibility matrix to PR summary
      - run: npx mcp-lint compat ./src/tools.json --format markdown >> $GITHUB_STEP_SUMMARY
        if: always()

      # Diff against previous version
      - run: npx mcp-lint diff tools-before.json tools-after.json --format markdown >> $GITHUB_STEP_SUMMARY
        if: always()

---

プラグイン API

npm パッケージを通じてルールセットを共有、再利用できます。

プラグインの使用

npm install mcp-lint-config-nextjs

{
  "plugins": ["mcp-lint-config-nextjs"],
  "extends": "recommended"
}

プラグインの作成

プラグインは、Rule オブジェクトの配列 rules をエクスポートする npm パッケージです。

// 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];

---

プログラム API

import { LintEngine } from 'mcp-lint';
import { allRules } from 'mcp-lint/rules';
import { loadFile } from 'mcp-lint/loaders';
import { applyFixes } from 'mcp-lint/fixer';

// Check
const tools = await loadFile('tools.json');
const engine = new LintEngine(allRules, {
  clients: ['claude', 'cursor', 'openai'],
  ignore: ['debug-tool'],
});
const diagnostics = engine.lint(tools);

// Fix
const fixed = applyFixes(tools, diagnostics);

---

mcp-lint preflight — 実行時の判断ファイアウォール

Lint は不正なスキーマを検出します。Preflight は不適切なアクションを検出します。

実行時に、エージェントがファイルの削除、リクエストの送信、カードへの課金など、ツールを呼び出そうとしています。Preflight はエージェントとアクションの間に入り、次の点を判定します。

• 許可されていますか？
• リスクはどの程度ですか？（0.0～1.0 の決定論的スコア）
• 元に戻せますか？
• 人による承認が必要ですか？
• より安全な代替手段はありますか？

$ 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

アクション形式

{
  "tool_type": "shell",
  "tool_name": "bash",
  "action": "rm -rf /prod/data",
  "target": "/prod/data",
  "context": { "environment": "prod" }
}

ポリシーファイル（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

examples/policies/ にサンプルポリシーがあります：default.yml、strict.yml、permissive-dev.yml。

SDK — MCP サーバーまたはエージェントのランタイムに組み込む

import { preflight, loadPolicy } from 'mcp-lint/preflight';

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

終了コード

コード	意味
0	allow / allow_with_rewrite
1	require_approval
2	deny / error

シェルラッパーや CI ゲートで、そのまま使用できます。

---

MCP サーバー

mcp-lint は、Claude Desktop、Claude Code、Cursor、VS Code、Glama などのレジストリスキャナー向けに、stdio MCP サーバーとしても提供されています。

npx -y mcp-lint@latest mcp-lint-server

クライアント設定：

{
  "mcpServers": {
    "mcp-lint": {
      "command": "npm",
      "args": ["exec", "--yes", "--package", "mcp-lint@latest", "--", "mcp-lint-server"]
    }
  }
}

利用可能な MCP ツール：

ツール	用途
mcp_lint_list_rules	組み込みルール、クライアント、重大度、自動修正の可否を一覧表示します
mcp_lint_explain_rule	1 つのルールを例と自動修正に関する補足とともに説明します
mcp_lint_check_tools	JSON として渡された MCP ツールのスキーマを lint します
mcp_lint_fix_tools	ファイルを書き込まずに、安全に自動修正されたツールスキーマを返します
mcp_lint_preflight_action	提案されたエージェントのアクションを評価し、許可／拒否／承認／書き換えの判断を返します

サーバーのすべてのツールは、ホスト側から見て読み取り専用です。診断結果、修正済み JSON、またはポリシー上の判断を返し、評価対象のアクションを実行することはありません。

Docker

docker build -t mcp-lint-server .
docker run --rm -i mcp-lint-server

リポジトリには glama.json と本番用 Dockerfile が含まれているため、MCP ディレクトリからサーバーをビルド、起動し、情報を取得できます。

---

ライセンス

MIT © Robert