Shell Proxy MCP

shell-proxy-mcp 翻译为中文是：“Shell 代理 MCP”（其中，MCP 通常代表某种特定的管理控制协议或组件，具体含义需根据上下文确定）。不过，需要注意的是，“MCP”在这里可能是一个特定于某个系统或应用的缩写，如果没有具体上下文，直接翻译可能无法完全准确表达其含义。在实际应用中，应根据具体情况来确定其准确翻译

一个提供Shell代理功能的模型上下文协议（MCP）服务器。您可以在YAML中定义您的Shell工具，并通过MCP将其暴露给大型语言模型（LLMs）。

特点/功能

• YAML 配置以简单的YAML格式定义带有参数、类型和描述的shell工具
• 类型验证使用Zod模式自动验证运行时参数（字符串、数字、布尔值）
• 模板支持使用Mustache模板{{param}}) 用于动态命令生成
• 安全内置参数验证、可配置的超时设置以及错误处理
• 跨平台在Linux、macOS和Windows系统上均可运行，支持各平台特定的shell
• 灵活执行为每个工具或全局配置shell类型和超时时间
• 丰富输出可选的输出前缀和结构化错误报告

要求

• Node.js 20.x 或 22.x

安装

与Claude桌面版的使用

添加到您的Claude桌面配置中：

{
  "mcpServers": {
    "shell-proxy": {
      "command": "npx",
      "args": ["-y", "@mileschou/shell-proxy-mcp", "/path/to/tools.yaml"],
      "env": {
        "PWD": "/Users/you/projects/myproject",
        "PROJECT_ROOT": "/Users/you/projects/myproject",
        "HOME": "/Users/you",
        "SHELL_PROXY_MCP_TIMEOUT_MS": "60000",
        "SHELL_PROXY_MCP_UNIX_SHELL": "/bin/zsh"
      }
    }
  }
}

配置

创建一个 tools.yaml 文件用于定义您的shell工具和资源：

mcp:
  description: My shell tools
  run:
    shell: /bin/bash
    timeout: 30000  # milliseconds

  resources:
    # Project documentation
    - name: readme
      description: Project README file
      uri: ${PWD}/README.md
      mimeType: text/markdown

    # Configuration file
    - name: app_config
      description: Application configuration
      uri: /etc/myapp/config.json
      mimeType: application/json

    # User-specific settings
    - name: user_settings
      description: User settings file
      uri: file://${HOME}/.myapp/settings.yaml
      mimeType: application/x-yaml

  tools:
    - name: list_files
      description: List files in a directory
      params:
        directory:
          type: string
          description: Directory path to list
          required: true
        pattern:
          type: string
          description: File pattern to match
          required: false
          default: "*"
      run:
        command: ls -la "{{directory}}" | grep "{{pattern}}"
      output:
        prefix: "Files in {{directory}}:"

    - name: disk_usage
      description: Show disk usage
      params:
        directory:
          type: string
          required: true
        max_depth:
          type: number
          required: false
          default: 1
      run:
        command: du -h --max-depth={{max_depth}} "{{directory}}"

配置参考

参数类型：

• string文本值
• number数值
• boolean真/假值

参数选项：

• required该参数是否为必填项
• default如果未提供，则为默认值
• description大型语言模型（LLMs）的参数说明

工具选项：

• run.command带有Mustache模板的Shell命令
• run.shell覆盖默认shell（可选）
• run.timeout覆盖默认超时时间（毫秒）（可选）
• output.prefix为命令输出添加前缀（可选）

环境变量

以下环境变量可用于自定义服务器行为：

• SHELL_PROXY_MCP_TIMEOUT_MS - 默认命令超时时间（以毫秒为单位）（默认： 30000）
• SHELL_PROXY_MCP_MAX_BUFFER - 最大输出缓冲区大小（以字节为单位）（默认： 10485760）
• SHELL_PROXY_MCP_TIMEOUT_EXIT_CODE - 超时错误的退出代码（默认： 124)
• SHELL_PROXY_MCP_UNIX_SHELL - Unix/Linux/macOS 的默认 shell（默认： /bin/bash）
• SHELL_PROXY_MCP_WIN32_SHELL - Windows的默认Shell（默认： cmd.exe)

请参阅上文的“安装”部分，了解如何在Claude Desktop配置中进行这些设置。

资源

资源提供静态文件和数据，供大型语言模型（LLMs）读取以获取上下文信息。与工具（执行操作）不同，资源是只读的，用于提供信息。

配置

在你的YAML配置中定义资源：

mcp:
  resources:
    - name: resource_name
      description: Resource description
      uri: /absolute/path/to/file
      mimeType: text/plain  # optional

URI 格式

资源支持以下URI格式：

绝对路径：

resources:
  - name: hosts_file
    uri: /etc/hosts
    mimeType: text/plain

文件URI：

resources:
  - name: config
    uri: file:///etc/app/config.json
    mimeType: application/json

使用环境变量：

resources:
  - name: user_config
    uri: ${HOME}/.config/myapp/config.json
    mimeType: application/json

要求

• URI 必须解析为绝对路径
• 相对路径是 不支持
• 在路径解析之前，环境变量会被展开
• 文件必须存在且可读

示例

该 例子 目录包含全面的工具配置：

• 示例/工具.yaml6款即用型工具，展示不同图案
• 示例/README.md（或“说明文件/README.md”，具体翻译取决于上下文，但“examples”通常翻译为“示例”或“例子”）详细的文档，包括参数参考、使用示例、最佳实践以及安全注意事项

发展

# Install dependencies
npm install

# Build
npm run build

# Watch mode for development
npm run watch

# Run tests (32 tests covering config, validator, executor)
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with UI
npm run test:ui

# Generate coverage report
npm run test:coverage

用例

这个MCP服务器使大型语言模型（LLMs）能够安全地执行各种任务的系统命令：

• 系统管理检查磁盘使用情况，列出文件，监控进程
• 发展Git操作、行数统计、文件搜索
• 数据分析日志解析、文件统计、目录分析
• 自动化为重复性的shell任务创建自定义工具
• 监测系统信息、资源使用情况、服务状态

灵感

这个项目是受……启发而来的 MCPShell （Go语言实现）并提供了一个Node.js/TypeScript的替代方案，其中包括：

• 原生 TypeScript 支持
• 基于Zod的验证
• Vitest 测试框架
• 跨平台兼容性

许可证

MIT 许可证 - 详见 许可证 详情如下。

贡献；做出贡献

欢迎贡献！改进方向：

• 额外的示例工具
• 增强的安全特性（类似CEL的约束）
• 更友好的错误提示
• 针对特定平台的优化
• 文档改进

请随时提交拉取请求或提出问题。

支持

• 文档检查 示例/README.md 用于详细指南
• 问题报告错误至
• MCP Resources（公司名，可译为）“MCP资源公司”访问 模型上下文协议 如需更多信息