MCP Shellcheck

ShellCheck MCP服务器

 ](./CHANGELOG.md)

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

✨ v0.1.2亮点

• 异步安全 --不再阻止MCP服务器
• 强大的解析 --使用ShellCheck JSON输出（脆弱文本解析）
• 输入验证 --文件检查、大小限制、外壳类型验证
• 结构化日志记录 --可观察性的调试/信息/警告级别
• 已测试 --22项测试通过，覆盖率>90%
• 经得起未来考验 --用于多后端支持的Linter抽象

升级说明： v0.1.2向后兼容。无需更改MCP客户端配置。

特性

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

需求

• Python 3.10+
• ShellCheck 安装在系统上

安装ShellCheck

# Ubuntu/Debian
sudo apt-get install shellcheck

# macOS
brew install shellcheck

# Fedora/RHEL
sudo dnf install ShellCheck

# Arch Linux
sudo pacman -S shellcheck

# From source
git clone https://github.com/koalaman/shellcheck.git
cd shellcheck
cabal build
sudo cabal install

安装

选项1：克隆并安装

cd /home/ev3lynx/Project/local-mcp-server
git clone https://github.com/your-repo/mcp-shellcheck.git
cd mcp-shellcheck
pip install -e .

选项2：直接执行Python

pip install mcp
python3 shellcheck_mcp_server.py

选项3：本地构建

# Clone and build
git clone https://github.com/ev3lynx727/mcp-shellcheck.git
cd mcp-shellcheck
uv build

# Install locally
uv pip install -e . --system

# Or run directly
uv run --with mcp python3 shellcheck_mcp_server.py

选项4：从GitHub发布

创建GitHub版本后，您可以直接从wheel文件中使用uvx：

uvx --from https://github.com/Ev3lynx727/mcp-shellcheck/releases/download/v0.1.0/mcp_shellcheck-0.1.0-py3-none-any.whl shellcheck-mcp-server

注意：将URL中的版本号替换为所需的版本。

OpenCode配置

推荐：使用uv run

添加或更新shellcheck MCP服务器配置：

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

替代方案：直接Python（需要安装mcp）

{
  "mcp": {
    "shellcheck": {
      "type": "local",
      "command": [
        "python3",
        "/home/ev3lynx/Project/local-mcp-server/mcp-shellcheck/shellcheck_mcp_server.py"
      ],
      "enabled": true,
      "timeout": 60000
    }
  }
}

代理工具配置

工具 shellcheck_shellcheck 已在这些代理中启用：

• builder-pro
• deep-research
• lint
• docker-config
• analyze

用法

作为MCP服务器

配置后，以下工具可用：

shellcheck 工具

检查shell脚本文件或内容是否存在问题。

参数：

\*要么 file_path 或 script_content 必须提供。

shellcheck_info 工具

获取ShellCheck版本和服务器信息。

参数： 无

直接CLI使用

# Check a file
shellcheck /path/to/script.sh

# Check stdin
cat script.sh | shellcheck -s bash -

# With specific options
shellcheck -e SC1090,SC2148 -s bash script.sh

例子

示例1：检查文件

# 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",
      "raw": "path/to/script.sh:15:10: warning: Double quote to prevent globbing..."
    }
  ],
  "exit_code": 1
}

示例2：检查脚本内容

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

# Output
{
  "success": false,
  "message": "Found 2 issue(s)",
  "results": [
    {
      "line": 2,
      "column": 5,
      "code": "SC2010",
      "message": "Don't read ls output with backticks",
      "severity": "warning"
    }
  ],
  "exit_code": 1
}

示例3：排除特定警告

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

示例4：使用严重性筛选器进行检查

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

常见ShellCheck错误代码

MCP客户端配置示例

克劳德桌面

{
  "mcpServers": {
    "shellcheck": {
      "command": "python3",
      "args": ["/home/ev3lynx/Project/local-mcp-server/mcp-shellcheck/shellcheck_mcp_server.py"]
    }
  }
}

光标

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

VS代码与副本

增添 .vscode/mcp.json:

{
  "servers": {
    "shellcheck": {
      "command": "python3",
      "args": ["/home/ev3lynx/Project/local-mcp-server/mcp-shellcheck/shellcheck_mcp_server.py"]
    }
  }
}

故障排除

“未找到ShellCheck”

在您的系统上安装ShellCheck。请参阅“要求”部分。

“未安装mcp包”

pip install mcp
# or
uvx shellcheck-mcp-server

MCP服务器未连接

1. 验证是否安装了ShellCheck： shellcheck --version
2. 手动测试服务器： python3 shellcheck_mcp_server.py
3. 检查MCP客户端日志中的连接错误

超时错误

增加MCP配置中的超时时间：

{
  "mcp": {
    "shellcheck": {
      "timeout": 120000
    }
  }
}

发展

安装开发依赖项

pip install -e ".[dev]"

运行测试

pytest

Lint代码

ruff check .

文件结构

mcp-shellcheck/
├── shellcheck_mcp_server.py  # Main MCP server script
├── requirements.txt           # Python dependencies
├── pyproject.toml            # Package configuration
├── README.md                 # This documentation
├── CONFIG_EXAMPLES.md        # Configuration examples
└── tests/                    # Test files (optional)

发布到PyPI

先决条件

1. 在以下位置创建PyPI帐户https://pypi.org
2. 在创建API令牌https://pypi.org/manage/account/

选项1：手动发布

# Build the package
uv build

# Publish to PyPI
uv publish

# Or test first with Test PyPI
uv publish --test

选项2:GitHub操作（推荐）

1. 创建GitHub存储库
2. 将您的PyPI令牌添加为机密：

- 前往设置→ 秘密与变量→ 行动 - 添加 PYPI_API_TOKEN 使用您的PyPI令牌

1. 在GitHub上创建发布或手动触发工作流

选项3：使用令牌进行本地发布

# Set up token
uv publish --token your-api-token

许可证

MIT许可证

学分

• ShellCheck -底层shell脚本linting工具

- 原作者： 维克托·埃里克森 - 来源：https://github.com/koalaman/shellcheck

• MCP-SDK -MCP的Python SDK