solhint-mcp

solhint-mcp

通过 Solhint 对 Solidity 智能合约进行 lint 检查和自动修复， 可从任意 MCP 客户端使用 — Claude Code、OpenAI Codex、Cursor、Windsurf、Claude Desktop，以及 任何其他支持该协议的客户端。它不专属于任何一家供应商。

你的 Agent 可使用七种工具：lint_solidity、lint_file、lint_project、 fix_solidity、fix_file、explain_rule 和 get_config。

Solhint 的 CLI 会向用户推荐此软件包 — protofire/solhint#801，已随 Solhint 6.2.5 发布。

安装

将以下内容添加到 MCP 客户端的配置中，并将 Solidity 项目设为工作目录：

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

需要 Node.js 20 或更高版本。在原生 Windows 上，如果客户端无法启动服务，可能需要设置 "command": "cmd" 和 "args": ["/c", "npx", "-y", "solhint-mcp"]： Node 无法在不使用 shell 的情况下直接启动 npx.cmd。

一个服务进程只对一个项目执行 lint 检查：其工作目录就是项目根目录，因此 处理其他项目时，请启动另一个进程。若项目中已安装 Solhint，则优先使用该版本，而非此处捆绑的版本。

Solhint 的运行方式

服务通过 Solhint 的 JavaScript API 调用 Solhint。它不会启动 shell、运行 npx solhint、检查更新或解析 CLI 输出。

特定客户端的快捷方式

Claude Code — 在 Solidity 项目目录中运行：

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

默认的本地作用域会将服务关联到当前项目。如果配置需要提交到 .mcp.json，请在 -- 前使用 --scope project。在原生 Windows 上，如果服务无法启动，通常可以通过使用 cmd /c 包装 npx 来解决 — Node 无法在不使用 shell 的情况下直接启动 npx.cmd：

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

OpenAI Codex — Codex 使用 TOML，而非上面的 JSON 配置块，并且 Codex CLI、ChatGPT 桌面应用和 IDE 扩展共用一份 配置。 在 Solidity 项目目录中运行：

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

也可以手动将其添加到 ~/.codex/config.toml，或添加到 .codex/config.toml，以将其限定在一个项目中：

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

Cursor / Windsurf — 将上面的 JSON 配置块添加到编辑器的 MCP 设置中。

Claude Desktop — 安装方式与 Claude Code 不同。此软件包是 stdio npm 服务，而非打包好的桌面扩展（.mcpb）。 只有当客户端以 Solidity 项目作为工作目录启动它时，才能将其配置为本地开发 MCP 服务。请参阅 Anthropic 当前的 本地服务说明。

工具

工具	输入	描述
lint_solidity	{ code, config? }	检查 Solidity 源代码字符串
lint_file	{ filePath }	检查项目中的一个 .sol 文件
lint_project	{ pattern? }	检查相对于项目的 glob
fix_solidity	{ code, config? }	自动修复 Solidity 源代码字符串
fix_file	{ filePath, write? }	自动修复一个 .sol 文件
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，它会发出警告， 然后仍然继续检查——检查的内容少于项目要求的内容。如果工具结果只显示检查结果， 就会被误认为是基于有问题的配置通过了检查。

这些警告会被捕获，并显示在检查结果上方：

⚠️ 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.

get_config 会通过一次临时检查触发相同的诊断信息，因为 Solhint 只有在加载规则时才会 发出这些信息，而用户会通过 get_config 查看配置是否有效。

fix_* 工具会应用 Solhint 自带的自动修复，然后重新检查，因此它们报告的剩余问题 确实是修复后仍未解决的问题，而不是修复前的检查结果。fix_solidity 会返回修正后的源代码，不会改动磁盘上的内容。fix_file 默认只预览，只有在调用时传入 write: true 才会写入——Solhint 的 CLI 在执行 --fix 前会要求备份，而 MCP 客户端也不应 在未经请求的情况下改写他人的合约。

explain_rule 会读取 Solhint 随每条规则提供的文档，因此涵盖整个规则注册表，并且始终说明 项目运行的版本：描述、类别、默认严重级别、可配置选项、备注，以及规则定义时提供的 正例和反例。

如果代码库已记录检查命令

Agent 会优先遵循代码库中的明确指令，而不是工具描述。 例如，如果 AGENTS.md、CLAUDE.md、.cursorrules 或类似的 Agent 指南说明了如何 运行检查：

- Solidity lint: `npm run lint:sol`

Agent 就会运行该命令，而不会使用这些工具。这是合理的行为，并非配置错误，但这意味着 除非你告知 Agent 存在这些工具，否则服务不会被使用。请在命令旁边提及这些工具：

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

两者相辅相成。命令供人和 CI 运行，工具供 Agent 运行；工具的优势在于调用方式不会偏离预期： 不会因为未加引号的 ** 只匹配一层目录，不会忘记配置，也不会多出无关标志。手动编写的 Shell glob 可能悄无声息地只覆盖项目的一部分；lint_project 则不会。

配置

lint_solidity 按以下顺序使用配置：

1. 提供给工具的完整 config 对象。
2. 项目根目录中的配置。
3. { "extends": "solhint:recommended" }。

显式配置会替代项目配置，不会与之合并。文件和项目检查使用 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() 解析可共享配置和插件。因此，此版本支持每个进程处理一个项目。检查期间，第三方插件同步写入 stdout 的内容会被重定向到 stderr，以免破坏 MCP 通道。完整的插件隔离、取消操作和检查超时功能将推迟到基于 worker 的版本。

Docker

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

服务会检查其启动时所在目录中的内容，因此 Solidity 项目会挂载到 /project，也就是镜像的工作目录。由于服务通过 stdio 进行 MCP 通信，因此必须使用 -i；不会暴露任何端口。挂载项目中安装的 Solhint 优先于镜像自带的版本。

MCP Registry

列名为 io.github.vschernoff/solhint-mcp。此仓库中的 server.json 是 Registry 清单；其 name 必须与 package.json 中的 mcpName 完全相同，并且两个版本字段都必须与已发布的 npm 版本一致，否则 Registry 发布会被拒绝。

致谢与许可

MIT。此处使用的检查运行器、工具接口和测试套件由 Diego Bale（@dbale-arg）实现，并经其同意依据 MIT 许可使用。文件级明细请参阅 NOTICE。

Solhint 由 Protofire 维护。本软件包依赖 Solhint，但不属于 Solhint。