bash MCP

MCP Bash服务器团队

最小的、动态的 模型上下文协议 （MCP）服务器在便携式Bash中实现（用macOS默认Bash 3.2测试）。它发现放置在 tools/ 并按照MCP工具契约通过JSON-RPC 2.0接口公开它们。

______________________________________________________________________

先决条件

• Bash shell\

测试方法： - macOS默认Bash 3.2 - Windows上的Git Bash - 如果你还没有 "C:\Program Files\Git\bin\bash.exe",\ 从以下位置安装Git for Windows：\

- 应该在Linux上工作

• jq 命令行JSON处理器：

- Linux/macOS： - 填写您的\并运行：\ install jq\ 例如，对于macOS： brew install jq - 窗户： 1. 首选 jq GitHub发布页面：\

1. 在“资产”下，下载 jq-win64.exe\ 注： 如果看不到，请单击“显示所有##资产”以首先展开完整列表。 1. 将文件重命名为 jq.exe 并将其精确地放置在：\ C:\Program Files\Git\usr\bin\jq.exe

______________________________________________________________________

主要特点

• Bash（无关联数组；可移植到旧shell）。

- 但不是“纯bash”：依赖于 jq 用于JSON解析/验证。

• 动态工具发现：中的任何可执行文件 tools/ 支持a list 子命令已加载。
• 重复工具名称检测，错误报告清晰。
• 使用JSON-RPC错误代码的结构化错误响应。
• 从工具执行中稳健地捕获stdout/stderr/exit代码。
• 使用以下工具验证JSON输出 jq 为了正确。
• 将活动记录到 /tmp/mcp_server.log.
• 与MCP协议版本兼容 2025-06-18.

______________________________________________________________________

使用

修改您的MCP JSON。

1. 对于JetBrains IDE：

1. 在CoPilot聊天中，选择代理模式，然后单击“设置”齿轮图标。 1. 单击“添加更多工具…”

1. 对于VS代码：

1. 打开命令面板，搜索“MCP:添加服务器…”。 1. 选择“命令（stdio）”。 1. 选择bash_mcp.sh的完整路径。

1. 对于Visual Studio：

1. 点击打开顶部菜单“查看”下拉菜单，然后点击“GitHub Copilot聊天”。 1. 在“GitHub Copilot Chat”窗格的底部提示框中，单击扳手图标。 1. 在右上角的“选择工具”模式弹出窗口中，单击“+”按钮。 1. 在“配置MCP服务器”窗口中，填写： 1. 目的地：确保 Global ... 已选择（默认） 1. 服务器ID:输入 team 1. 类型：确保 stdio 已选择（默认） 1. 命令（带可选参数）：enter

         "C:\Program Files\Git\bin\bash.exe" "/full/path/to/bash_mcp.sh"

例子： Windows样式路径的转换 C:\Users\MyName\bash_mcp\bash_mcp.sh 转换为MinGW目录样式： /c/Users/MyName/bash_mcp/bash_mcp.sh 1. 点击 Save.

确保 "servers" JSON数组包含如下条目：

{
  "name": "team",
  "command": ["/full/path/to/bash_mcp.sh"],
  "args": []
}

• 注： 除了在Windows中，shebang.sh脚本需要显式bash：

  ...
  "command": "C:\\Program Files\\Git\\bin\\bash.exe",
  "args": [
    "/full/path/to/bash_mcp.sh"
  ],
  ...

然后，在代理模式下，从CoPilot聊天中检查设置齿轮图标是否显示“团队”服务器已连接 可用工具。

______________________________________________________________________

缺少功能

• 没有资源或提示支持（占位符返回空列表）。
• 文件系统更改时不热重新加载工具（TODO：需要发送工具更改通知）。

______________________________________________________________________

文件布局

• bash_mcp.sh –MCP服务器主循环和工具运行时。
• tools/test.sh –工具提供商实施示例 echo 和 add.
• README.md –本文件。
• （您可以向添加更多可执行文件 tools/).

______________________________________________________________________

协议摘要

服务器从stdin读取换行符分隔的JSON-RPC 2.0请求，并将响应写入stdout。

主 methods

• initialize
• tools/list
• tools/call

每个工具的名称 N 发现于 tools/ 支持：

• list （列出支持的任何其他主要论点）
• X args （调用工具 X 使用JSON arg文件）
• 备注：如果两个不同的可执行文件宣传同一个工具 name，服务器将拒绝 tools/list 并返回

复制错误。

还有一些方法返回占位符或空列表（例如，与资源和提示相关的方法） 为了满足MCP合规性：

• notifications/initialized （除日志记录外忽略）
• resources/list （返回空列表）
• resources/templates/list （返回空列表）
• prompts/list （返回空列表）

______________________________________________________________________

示例工具提供程序已包含(tools/test.sh)

list 输出（两个对象）：

{ "name": "echo", "title": "Echo Tool", "description": "Echoes the input text.", "inputSchema": { "type": "object", "properties": { "text": { "type": "string" } }, "required": ["text"] } }
{ "name": "add", "title": "Addition Tool", "description": "Adds two numbers.", "inputSchema": { "type": "object", "properties": { "a": { "type": "number" }, "b": { "type": "number" } }, "required": ["a","b"] } }

直接运行工具：

./tools/test.sh echo '{"text":"Hello"}'
./tools/test.sh add '{"a":4,"b":4}'

成功调用将返回MCP工具结果形状，例如：

{
  "jsonrpc": "2.0",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "8"
      }
    ],
    "isError": false
  },
  "id": 1
}

错误的请求示例（缺少参数）：

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32603,
    "message": "Tool 'add' failed (exit 1): >"
  },
  "id": 1
}

您还可以通过完整的MCP规范调用该工具：

jq -cn '{
  jsonrpc: "2.0",
  method: "tools/call",
  params: {
    name: "add",
    arguments: {
      a: 40,
      b: 2
    }
  },
  id: 1
}' | ./bash_mcp.sh

使用的错误代码：

• -32700 解析错误（JSON行无效）
• -32600 请求结构无效
• -32601 找不到方法或工具
• -32602 参数无效（JSON参数格式错误）
• -32603 内部/工具执行/重复/工具JSON无效

______________________________________________________________________

日志记录

操作日志和stderr副本将附加到 /tmp/mcp_server.log。工具stderr也记录为级别1。

______________________________________________________________________

添加新工具

1. 在中创建可执行文件 tools/ （脚本或二进制）并使其可执行(chmod +x).
2. 实施a list 每个工具定义行打印一个JSON对象的子命令。
3. 为每个广告实现一个子命令 name.
4. 确保每次工具调用都将有效的JSON打印到stdout（工具结果）。非零退出代码会触发服务器错误包装。
5. 必须在所有工具中使用唯一的工具名称 全部 /工具；重复项将被阻止 tools/list.

模板最小化工具：

#!/usr/bin/env bash
set -Eeuom pipefail
case "$1" in
  list)
    jq -cn '{name:"mytool",description:"Does X",inputSchema:{type:"object",properties:{},required:[]}}'
    ;;
  mytool)
    jq -cn '{content:[{type:"text",text:"done"}],isError:false}'
    ;;
  *) echo '{"error":{"message":"Unknown"}}' ; exit 1 ;;
 esac

______________________________________________________________________

重复工具处理

如果两个可执行文件通告相同 name, tools/list 返回错误：

{"jsonrpc":"2.0","error":{"code":-32603,"message":"Duplicate tool names: name:fileNew,fileExisting"},"id":2}

通过重命名或删除一个定义进行修复。

______________________________________________________________________

开发说明

• 用途 jq 广泛；确保已安装(brew install jq 在macOS上）。
• 避免3.2不支持的抨击（例如，关联数组）。取而代之的是使用并行数组。
• set -Eeuom pipefail 用于严格的错误处理。
• JSON验证发生在接受工具输出之前。

______________________________________________________________________

未来改进（想法）

• 文件系统更改时的热重新加载（inotify/polling）。
• 可选资源和即时支持。
• 限制工具输出大小，允许参数限制N个顶部/尾部结果。
• 刀具执行超时控制。
• 安全沙盒（二进制文件的chroot/seccomp）。