AI导哈

Shell脚本检查服务

一个通过ShellCheck提供Shell脚本检查的MCP服务器，用于分析脚本中的常见错误、风格问题和潜在缺陷。

  • by Ev3lynx727
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 Ev3lynx727/mcp-shellcheck

使用说明

ShellCheck MCP服务器

通过ShellCheck提供shell脚本linting的模型上下文协议（MCP）服务器。允许AI代理分析shell脚本的常见错误、风格问题和潜在错误。

MCP服务器配置文件

{
  "name": "mcp-shellcheck",
  "description": "A Model Context Protocol (MCP) server that provides shell script linting via ShellCheck for AI coding assistants",
  "tools": [
    {
      "name": "shellcheck",
      "description": "Run ShellCheck on a shell script to find bugs, stylistic issues, and potential errors",
      "inputSchema": {
        "type": "object",
        "properties": {
          "file_path": { "type": "string", "description": "Path to the shell script file to check" },
          "script_content": { "type": "string", "description": "Raw shell script content to check" },
          "shell": { "type": "string", "description": "Shell type to check", "enum": ["bash", "sh", "dash", "ksh", "ash"] },
          "check_sourced": { "type": "boolean", "description": "Enable checks for sourced files" },
          "enable_all": { "type": "boolean", "description": "Enable all optional checks" },
          "exclude": { "type": "string", "description": "Comma-separated list of warning codes to exclude" },
          "severity": { "type": "string", "description": "Minimum severity to report", "enum": ["error", "warning", "info", "style"] }
        }
      }
    },
    {
      "name": "shellcheck_info",
      "description": "Get information about the ShellCheck version and server capabilities",
      "inputSchema": {
        "type": "object",
        "properties": {}
      }
    }
  ]
}

快速安装

# Run via uvx from PyPI
uvx --from mcp-shellcheck shellcheck-mcp-server

# Run via uvx from GitHub release
uvx --from https://github.com/Ev3lynx727/mcp-shellcheck/releases/download/v0.1.3/mcp_shellcheck-0.1.3-py3-none-any.whl shellcheck-mcp-server

# One-liner install (install.sh)
curl -fsSL https://raw.githubusercontent.com/Ev3lynx727/mcp-shellcheck/main/install.sh | sh

# Install from PyPI
pip install mcp-shellcheck

# Clone and dev install
git clone https://github.com/Ev3lynx727/mcp-shellcheck.git
cd mcp-shellcheck && pip install -e .

特性

  • 基于文件的分析：按文件路径检查shell脚本
  • 内联脚本检查：直接分析原始shell脚本内容
  • 多壳支撑：bash、sh、dash、ksh、ash
  • 可配置检查：排除特定警告，设置严重级别
  • 结构化输出：JSON格式的结果便于解析
  • OpenCode集成：已准备好与OpenCode代理一起使用
  • 生产就绪：异步、测试、验证、记录

需求

安装ShellCheck

推荐（始终为最新）：

pip install shellcheck-py

这 shellcheck-py 包在PATH上提供了一个预构建的shellcheck v0.11.0二进制文件，没有系统依赖关系。

系统包管理器（可能附带旧版本）：

# Ubuntu/Debian
sudo apt-get install shellcheck

# macOS
brew install shellcheck

# Fedora/RHEL
sudo dnf install ShellCheck

# Arch Linux
sudo pacman -S shellcheck

工具

shellcheck

在shell脚本上运行ShellCheck以查找错误、风格问题和潜在错误。

参数：

参数 类型 必填 说明
file_path string 否* shell脚本文件的路径
script_content string 否* 原始shell脚本内容
shell string 否 外壳类型：bash、sh、dash、ksh、ash（默认：bash）
check_sourced boolean 否 启用对源文件的检查（默认值：false）
enable_all boolean 否 启用所有可选检查（默认值：false）
exclude string 否 要排除的逗号分隔代码（例如，“SC1090，SC2148”）
include string 否 要包含的逗号分隔代码（例如，“SC2086，SC2164”）
severity string 否 最小严重性：错误、警告、信息、样式

*要么 file_path 或 script_content 必须提供。

常见错误代码：

代码 描述 严重性
SC1090 无法跟踪非恒定源 信息
SC2086 双引号防止球化 警告
SC2164 使用带有
SC2006 使用$（…）而不是传统的回溯 样式

shellcheck_info

获取ShellCheck版本和服务器功能。

参数： 无

配置

开源代码

{
  "mcp": {
    "shellcheck": {
      "type": "local",
      "command": [
        "uv",
        "run",
        "--with", "mcp",
        "python3",
        "/path/to/mcp-shellcheck/shellcheck_mcp_server.py"
      ],
      "enabled": true,
      "timeout": 60000
    }
  }
}

OpenCode（来自GitHub版本的uvx）

{
  "mcp": {
    "shellcheck": {
      "type": "local",
      "command": [
        "uvx",
        "--from", "https://github.com/Ev3lynx727/mcp-shellcheck/releases/download/v0.1.3/mcp_shellcheck-0.1.3-py3-none-any.whl",
        "shellcheck-mcp-server"
      ],
      "enabled": true,
      "timeout": 60000
    }
  }
}

Claude 桌面版

{
  "mcpServers": {
    "shellcheck": {
      "command": "python3",
      "args": ["/path/to/mcp-shellcheck/shellcheck_mcp_server.py"]
    }
  }
}

光标

{
  "mcpServers": {
    "shellcheck": {
      "command": "uvx",
      "args": ["shellcheck-mcp-server"]
    }
  }
}

VS代码（副本）

增添 .vscode/mcp.json:

{
  "servers": {
    "shellcheck": {
      "command": "python3",
      "args": ["/path/to/mcp-shellcheck/shellcheck_mcp_server.py"]
    }
  }
}

示例

检查文件

// Input
{ "file_path": "/path/to/deploy.sh" }

// Output
{
  "success": false,
  "message": "Found 3 issue(s)",
  "results": [
    {
      "line": 15,
      "column": 10,
      "code": "SC2086",
      "message": "Double quote to prevent globbing",
      "severity": "warning"
    }
  ],
  "exit_code": 1
}

检查脚本内容

// Input
{ "script_content": "#!/bin/bash\ncat `ls *.txt`", "shell": "bash" }

排除特定警告

{ "file_path": "/path/to/script.sh", "exclude": "SC1090,SC2148" }

按严重性筛选

{ "file_path": "/path/to/script.sh", "severity": "error" }

故障排除

问题 解决方案
未找到ShellCheck 通过安装 pip install shellcheck-py 或系统包管理器
未安装MCP包 pip install mcp
服务器未连接 验证 shellcheck --version，测试 python3 shellcheck_mcp_server.py
超时错误 增加超时时间： "timeout": 120000 在MCP配置中

发展

pip install -e ".[dev]"
pytest
ruff check .

看 更改日志.md 发布历史和 建筑.md 用于设计文档。

许可证

麻省理工学院

相关 MCP