内容
# ShellCheck MCP 服务器
[](https://github.com/Ev3lynx727/mcp-shellcheck/actions/workflows/tests.yml)
[](https://pypi.org/project/mcp-shellcheck/)
[](./LICENSE)
一个模型上下文协议（MCP）服务器，通过 ShellCheck 提供 shell 脚本 linting 功能。允许 AI 代理分析 shell 脚本中的常见错误、样式问题和潜在错误。
## MCP 服务器配置文件
```json
{
"name": "mcp-shellcheck",
"description": "一个模型上下文协议（MCP）服务器，通过 ShellCheck 为 AI 编码助手提供 shell 脚本 linting 功能",
"tools": [
{
"name": "shellcheck",
"description": "对 shell 脚本运行 ShellCheck 以查找错误、样式问题和潜在错误",
"inputSchema": {
"type": "object",
"properties": {
"file_path": { "type": "string", "description": "要检查的 shell 脚本文件路径" },
"script_content": { "type": "string", "description": "要检查的原始 shell 脚本内容" },
"shell": { "type": "string", "description": "要检查的 shell 类型", "enum": ["bash", "sh", "dash", "ksh", "ash"] },
"check_sourced": { "type": "boolean", "description": "启用对 sourced 文件的检查" },
"enable_all": { "type": "boolean", "description": "启用所有可选检查" },
"exclude": { "type": "string", "description": "要排除的警告代码的逗号分隔列表" },
"severity": { "type": "string", "description": "要报告的最低严重级别", "enum": ["error", "warning", "info", "style"] }
}
}
},
{
"name": "shellcheck_info",
"description": "获取 ShellCheck 版本和服务器功能信息",
"inputSchema": {
"type": "object",
"properties": {}
}
}
]
}
```
## 快速安装
```bash
# 使用 uvx 从 PyPI 运行
uvx --from mcp-shellcheck shellcheck-mcp-server
# 使用 uvx 从 GitHub 发布版本运行
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
# 一键安装（install.sh）
curl -fsSL https://raw.githubusercontent.com/Ev3lynx727/mcp-shellcheck/main/install.sh | sh
# 从 PyPI 安装
pip install mcp-shellcheck
# 克隆并开发安装
git clone https://github.com/Ev3lynx727/mcp-shellcheck.git
cd mcp-shellcheck && pip install -e .
```
## 功能特点
- **基于文件的分析**：按文件路径检查 shell 脚本
- **内联脚本检查**：直接分析原始 shell 脚本内容
- **支持多种 shell**：bash, sh, dash, ksh, ash
- **可配置的检查**：排除特定警告、设置严重级别
- **结构化输出**：JSON 格式的结果，易于解析
- **OpenCode 集成**：准备好与 OpenCode 代理一起使用
- **生产就绪**：异步、测试、验证、记录
## 要求
- Python 3.10+
- [ShellCheck](https://www.shellcheck.net/) 已安装在系统上
### 安装 ShellCheck
**推荐（始终是最新的）：**
```bash
pip install shellcheck-py
```
`shellcheck-py` 包提供了一个预构建的 shellcheck v0.11.0 二进制文件在您的 PATH 上，无需系统依赖。
**系统包管理器（可能提供较旧的版本）：**
```bash
# 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` | 字符串 | 否* | shell 脚本文件路径 |
| `script_content` | 字符串 | 否* | 原始 shell 脚本内容 |
| `shell` | 字符串 | 否 | shell 类型：bash, sh, dash, ksh, ash（默认：bash） |
| `check_sourced` | 布尔值 | 否 | 启用对 sourced 文件的检查（默认：false） |
| `enable_all` | 布尔值 | 否 | 启用所有可选检查（默认：false） |
| `exclude` | 字符串 | 否 | 要排除的警告代码的逗号分隔列表（例如，“SC1090,SC2148”） |
| `include` | 字符串 | 否 | 要包含的警告代码的逗号分隔列表（例如，“SC2086,SC2164”） |
| `severity` | 字符串 | 否 | 最低严重级别：error, warning, info, style |
*必须提供 `file_path` 或 `script_content` 之一。
**常见错误代码：**
| 代码 | 描述 | 严重级别 |
|------|-------------|----------|
| SC1090 | 无法跟踪非常数源 | info |
| SC2086 | 使用双引号防止 globbing | warning |
| SC2164 | 使用 cd 和 \|\| exit | warning |
| SC2006 | 使用 $(...) 代替传统反引号 | style |
### `shellcheck_info`
获取 ShellCheck 版本和服务器功能信息。
**参数：** 无
## 配置
### OpenCode
```jsonc
{
"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）
```jsonc
{
"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 Desktop
```json
{
"mcpServers": {
"shellcheck": {
"command": "python3",
"args": ["/path/to/mcp-shellcheck/shellcheck_mcp_server.py"]
}
}
}
```
### Cursor
```json
{
"mcpServers": {
"shellcheck": {
"command": "uvx",
"args": ["shellcheck-mcp-server"]
}
}
}
```
### VS Code（Copilot）
将以下内容添加到 `.vscode/mcp.json`：
```json
{
"servers": {
"shellcheck": {
"command": "python3",
"args": ["/path/to/mcp-shellcheck/shellcheck_mcp_server.py"]
}
}
}
```
## 示例
### 检查文件
```json
// 输入
{ "file_path": "/path/to/deploy.sh" }
// 输出
{
"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
}
```
### 检查脚本内容
```json
// 输入
{ "script_content": "#!/bin/bash\ncat `ls *.txt`", "shell": "bash" }
```
### 排除特定警告
```json
{ "file_path": "/path/to/script.sh", "exclude": "SC1090,SC2148" }
```
### 按严重级别过滤
```json
{ "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 配置中 |
## 开发
```bash
pip install -e ".[dev]"
pytest
ruff check .
```
参见 [CHANGELOG.md](./CHANGELOG.md) 获取发布历史和 [ARCHITECTURE.md](docs/ARCHITECTURE.md) 获取设计文档。
## 许可证
MIT
