solhint-mcp

solhint-mcp

Solhintを使って、あらゆる MCP クライアント（Claude Code、OpenAI Codex、Cursor、Windsurf、Claude Desktop など、プロトコルに対応するもの）から Solidity スマートコントラクトのリントと自動修正を行えます。特定のベンダーに依存する機能はありません。

エージェントには、lint_solidity、lint_file、lint_project、fix_solidity、fix_file、explain_rule、get_config の7つのツールが提供されます。

Solhint の CLI からこのパッケージが案内されています — protofire/solhint#801。Solhint 6.2.5 に含まれています。

インストール

Solidity プロジェクトを作業ディレクトリとして、MCP クライアントの設定に以下を追加します。

{
  "mcpServers": {
    "solhint": {
      "command": "npx",
      "args": ["-y", "solhint-mcp"]
    }
  }
}

Node.js 20 以降が必要です。ネイティブ Windows でサーバーを起動できないクライアントでは、"command": "cmd" と "args": ["/c", "npx", "-y", "solhint-mcp"] が必要になる場合があります。Node はシェルを介さずに npx.cmd を直接起動できません。

1つのサーバープロセスでリントするプロジェクトは1つです。作業ディレクトリがプロジェクトのルートになるため、別のプロジェクトでは別のプロセスを起動してください。そのプロジェクトにインストールされている Solhint が、ここにバンドルされているものより優先されます。

Solhint の実行方法

サーバーは JavaScript API を通じて Solhint を呼び出します。シェルを起動したり、npx solhint を実行したり、更新を確認したり、CLI の出力を解析したりすることはありません。

クライアント別の簡単な設定方法

Claude Code — Solidity プロジェクトのディレクトリで実行します。

claude mcp add solhint -- npx -y solhint-mcp

デフォルトのローカルスコープでは、サーバーが現在のプロジェクトに関連付けられます。設定を .mcp.json に含めてコミットする場合は、-- の前に --scope project を指定してください。ネイティブ Windows でサーバーを起動できない場合、通常は npx を cmd /c でラップすれば解決します。Node はシェルを介さずに npx.cmd を直接起動できません。

claude mcp add solhint -- cmd /c npx -y solhint-mcp

OpenAI Codex — Codex は上記の JSON ブロックではなく TOML を使い、Codex CLI、ChatGPT デスクトップアプリ、IDE 拡張機能で設定を共有します。Solidity プロジェクトのディレクトリで実行します。

codex mcp add solhint -- npx -y solhint-mcp

または、~/.codex/config.toml に手動で追加するか、1つのプロジェクトにスコープを限定する場合は .codex/config.toml に追加します。

[mcp_servers.solhint]
command = "npx"
args = ["-y", "solhint-mcp"]

Cursor / Windsurf — 上記の JSON ブロックをエディターの MCP 設定に追加します。

Claude Desktop — Claude Code とは別途インストールが必要です。このパッケージは stdio npm サーバーであり、パッケージ化された Desktop Extension（.mcpb）ではありません。クライアントが Solidity プロジェクトを作業ディレクトリとして起動する場合にのみ、ローカル開発用 MCP サーバーとして設定してください。Anthropic の最新のローカルサーバーの手順を参照してください。

ツール

ツール	入力	説明
lint_solidity	{ code, config? }	Solidity のソース文字列を lint します
lint_file	{ filePath }	プロジェクト内の .sol ファイルを1つ lint します
lint_project	{ pattern? }	プロジェクト相対の glob を lint します
fix_solidity	{ code, config? }	Solidity のソース文字列を自動修正します
fix_file	{ filePath, write? }	.sol ファイルを1つ自動修正します
explain_rule	{ ruleId }	linter に含まれる任意のルールを説明します
get_config	{}	プロジェクトの Solhint 設定を表示します

lint_project は、まず contracts/**/*.sol、次に src/**/*.sol、最後に **/*.sol を自動検出します。プロジェクトのルート外を指すパスとパターンは拒否されます。

省略可能な config 引数では、ルールマップと組み込みの solhint:recommended および solhint:all プリセットを指定できます。extends のパス、共有可能な設定 パッケージ名、または plugins は指定できません。Solhint はこれらを require で読み込むため、 ツール引数からそれらを受け入れると、ツールを呼び出せるものなら誰でもサーバープロセスで コードを実行できてしまいます。これらはプロジェクト独自の .solhint.json で宣言してください。 このファイルは、そのディレクトリで npx solhint を実行するのと同じ信頼レベルです。

実行の健全性

Solhint は、読み込めないプラグインや認識できないルール ID を警告として報告したうえで、 そのまま lint を実行します。つまり、プロジェクトが要求したチェックの一部が行われません。 検出結果だけを表示するツールの出力は、壊れた設定でも問題なくチェックできたものとして 受け取られてしまいます。

そこで、これらの警告は検出結果の前に捕捉して報告されます。

⚠️ This run was degraded — Solhint checked less than the project asked for.
- Could not load solhint-plugin-foo, make sure it's installed and exports valid rules. Ignoring it.
- Rule 'no-such-rule' doesn't exist

Treat the result below as incomplete until this is fixed. A finding that is absent may
only mean the rule never ran.

Solhint はルールを読み込むときにしか警告を出さないため、get_config は使い捨ての lint を実行して 同じ診断を引き出します。設定が妥当かどうかを確認したい人が参照するのは get_config だからです。

fix_* ツールは Solhint 独自の自動修正を適用してから再度 lint を実行するため、 報告される残りの問題は修正前の結果ではなく、実際に残っているものです。fix_solidity は 修正済みのソースを返し、ディスク上のファイルには触れません。fix_file はデフォルトでは プレビューのみを行い、write: true を指定して呼び出した場合にのみ書き込みます。 Solhint の CLI は --fix の前にバックアップを求めます。同様に、MCP クライアントも 依頼なしに誰かのコントラクトを書き換えるべきではありません。

explain_rule は Solhint に同梱されている各ルールのドキュメントを読み込むため、 レジストリ全体を網羅し、常にこのプロジェクトが実行するバージョンについて説明します。 説明、カテゴリ、デフォルトの重大度、設定可能なオプション、注記、およびルールで定義されている 場合は適切な例と不適切な例が含まれます。

リポジトリに lint コマンドがすでに記載されている場合

エージェントは、ツールの説明よりもリポジトリ内の明示的な指示に従います。 たとえば、AGENTS.md、CLAUDE.md、.cursorrules などのエージェント向け手順書に lint の方法が記載されている場合は、次のようになります。

- Solidity lint: `npm run lint:sol`

エージェントはそのコマンドを実行し、これらのツールには目もくれません。これは妥当な動作であり、 設定ミスではありませんが、ツールが使えることを伝えるまではサーバーが使われないということです。 コマンドとあわせて、ツールについても記載してください。

- Solidity lint: prefer the `solhint` MCP tools (`lint_file`, `lint_project`,
  `fix_file`, `explain_rule`, `get_config`) when that server is configured; they run this project's
  own Solhint with its config. Fall back to `npm run lint:sol` when the server is
  unavailable.

この2つは互いに補完し合います。コマンドは人と CI が実行するものです。ツールはエージェントが 実行するもので、呼び出し方法がぶれないことが利点です。引用符で囲まれていない ** が 1階層だけに展開されたり、設定を忘れたり、余計なフラグが付いたりすることはありません。 手書きのシェル glob ではプロジェクトの一部しか対象にならないことがありますが、 lint_project ではそのようなことは起こりません。

設定

lint_solidity は、次の順序で設定を使用します。

1. ツールに渡された config オブジェクト全体。
2. プロジェクトルートで見つかった設定。
3. { "extends": "solhint:recommended" }。

明示的に指定した設定はプロジェクトの設定を置き換え、マージはされません。ファイル単位およびプロジェクト単位の lint では、Solhint のファイルごとの設定階層を使用し、設定がない場合は同じ推奨設定にフォールバックします。

サーバーは、プロジェクトにインストールされた互換性のある solhint（>=6.1.0 <7.0.0）を優先します。該当するものがない場合は、同梱のテスト済みバージョンを使用します。互換性のないバージョンがプロジェクトにインストールされている場合は、明示的なエラーが発生します。同梱バージョンを意図的に使用する場合に限り、--bundled-solhint を渡してください。

Solhint 6.0.x は対象外です。設定されたプラグインを読み込めない場合、そのプラグインローダーがホストプロセスを終了させることがあり、インプロセスの MCP サーバーにとって安全ではないためです。

プロトコルと現在の制限事項

サーバーは、stdio 経由で @modelcontextprotocol/server 2.x を使用します。現在の 2026-07-28 のライフサイクルと、SDK のレガシー互換パスをサポートしています。

Solhint は現在、共有可能な設定とプラグインを process.cwd() を基準に解決します。そのため、このリリースでは 1 プロセスにつき 1 つのプロジェクトをサポートします。標準出力に同期的に書き込むサードパーティ製プラグインは、lint 中に標準エラー出力へリダイレクトされるため、MCP チャネルを破損させることはありません。プラグインの完全な隔離、キャンセル、lint のタイムアウトは、ワーカーベースのリリースまで保留されています。

Docker

docker build -t solhint-mcp .
docker run -i --rm -v "$PWD":/project solhint-mcp

サーバーは起動したディレクトリを lint するため、Solidity プロジェクトは、イメージの作業ディレクトリである /project にマウントします。サーバーは stdio 経由で MCP を使用するため、-i が必要です。ポートは公開されません。マウントしたプロジェクトにインストールされている Solhint は、イメージに含まれる Solhint より優先されます。

MCP Registry

io.github.vschernoff/solhint-mcp として登録されています。このリポジトリの server.json はレジストリマニフェストです。その name は package.json の mcpName と同一である必要があり、両方のバージョンフィールドは公開されている npm バージョンと一致していなければなりません。一致しない場合、レジストリへの公開は拒否されます。

クレジットとライセンス

MIT。lint ランナー、ツールのインターフェース、テストスイートは Diego Bale（@dbale-arg）による実装で、本人の同意のもと、MIT ライセンスに基づいてここで使用しています。ファイル単位の内訳については、NOTICE を参照してください。

Solhint は Protofire によって保守されています。このパッケージは Solhint に依存していますが、Solhint の一部ではありません。