muthuishere/mcp-server-bash-sdk

MCP server SDK/example implemented entirely in bash — build a Model Context Protocol server with no runtime dependency beyond a POSIX shell.

📦 什么是 mcp-server-bash-sdk？

一个完全用 Bash 编写的、Model Context Protocol (MCP) 2026-07-28 的极小、零开销 实现。它允许你通过与大型 MCP 服务器相同的 JSON-RPC 风格请求/响应格式，将 tool 函数（例如 get_weather、list_files）暴露给 AI 代理客户端，而无需引入 Node 或 Python 等重型运行时。

🎯 核心理念

无状态、按请求协议 – 2026-07-28 版本移除了握手和会话，因此每个请求都是单行 JSON，可在简单的读循环中处理。
一个代码库，两种传输方式 – 同一个 Bash 脚本可同时通过 stdio（LLM 代理启动子进程的典型方式）或通过 本地 HTTP POST 端点（使用 socat/netcat）提供服务。
命名发现工具 – 任何以 tool_ 开头的 Bash 函数都会自动列在 server/discover 响应中，并可通过 tools/call 调用。

🛠️ 主要组件（如 README 所述）

文件 / 目录	作用
`mcpserver_core.sh`	处理 JSON-RPC 封装、MCP 方法分发、版本协商，并使用 `jq` 和可选的 `jsonschema` 对输出进行官方 JSON 模式验证。
`mcpserver_http.sh`	轻量级包装器，将核心转换为可流式传输的 HTTP 监听器（仅支持 POST，仅限回环）。
`moviemcpserver.sh`（及其他示例）	具体的服务器脚本，`source` 核心后定义包含业务逻辑的 `tool_*` 函数。
`assets/`	描述服务器（`discover` 负载）和工具列表（`tools` 负载）的 JSON 文件。
`spec/`	由合规性测试套件使用的第三方 MCP 模式。
`docs/adr/` 与 `docs/spikes/`	架构决策记录（ADR）和实验脚本，用于验证 macOS、Debian、Alpine 等系统上的特定 Bash 行为。
`examples/`	四个可直接运行的服务器演示（电影目录、git 包装器、天气 API、文件服务器）以及一个“从零构建”指南。
`test_*.sh` 与 `scripts/test-linux.sh`	覆盖核心逻辑、发现结构、模式合规性以及在多个 Linux 发行版上两种传输方式的单元与集成测试。

🚀 快速入门（快速启动流程）

克隆并设为可执行

git clone https://github.com/muthuishere/mcp-server-bash-sdk
cd mcp-server-bash-sdk
chmod +x mcpserver_core.sh moviemcpserver.sh

通过 stdio 运行请求

echo '{"jsonrpc":"2.0","id":1,"method":"server/discover","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28"}}}' |
./moviemcpserver.sh

作为本地 HTTP 端点运行

./moviemcpserver.sh --http   # 在 http://127.0.0.1:3000/mcp 上监听

运行测试套件（需要 jq；可选 python + jsonschema 用于模式测试）

./test_mcpserver_core.sh          # 31 个单元测试
./test_http_transport.sh          # 19 个 HTTP 测试
./scripts/test-linux.sh all       # 通过 Docker 在 Debian、Ubuntu、Alpine 上验证

🧩 如何用 Bash 构建你自己的 MCP 服务器

创建一个包装脚本（例如 weatherserver.sh）。
在 source mcpserver_core.sh 之前设置配置路径（MCP_CONFIG_FILE、MCP_TOOLS_LIST_FILE、MCP_LOG_FILE）。
定义 tool_* 函数 – 每个函数接收一个 JSON 字符串参数，成功时 echo 结果并返回 0；出错时 echo 说明信息并返回 1；核心会将其转换为 isError: true 的 JSON 响应（HTTP/stdio 通信仍视为成功）。
选择传输方式 – 无参数运行脚本以使用 stdio，或使用 --http（可选 MCP_HTTP_PORT、MCP_HTTP_BIND、MCP_ALLOWED_ORIGINS）使用 HTTP。
将服务器添加到 MCP 客户端配置中 – 例如，在 LLM 助手的 mcp.servers JSON 中，将 type 设为 stdio，command 设为你的脚本。

📌 限制（作者列出）

仅限本地 HTTP – 无 TLS，无认证；公开暴露需反向代理。
无 SSE / 流式响应 – 2026-07-28 规范移除了基于会话的流，因此不支持进度通知。
单客户端 stdio – 一个进程一次处理一个客户端（约 30 req/s）。
功能缺失 – 无 resources、prompts、MRTR 输入或“tasks”扩展。
版本锁定 – 仅实现 2026-07-28 版本；旧版 MCP 版本被拒绝。

📚 文档与社区

完整文档网站 – https://muthuishere.github.io/mcp-server-bash-sdk/
架构决策记录 – docs/adr/ 解释了 SDK 设计的原因。
Discord 社区 – AgentNexus（https://discord.gg/V9C2kvHC8D）设有 #mcp-bash-sdk 频道，用于提问和展示。
作者 – 由 deemwar（https://examples.deemwar.com）维护；生产支持请联系 io@deemwar.com。

✅ TL;DR

如果你需要一个轻量级、纯 Bash 的 MCP 服务器，用于向 AI 代理暴露简单工具（例如原型设计、本地开发，或无法安装 Node/Python 的环境），这个仓库提供了现成的、符合规范的实现，支持 stdio 和本地 HTTP 绑定，拥有全面测试和清晰的指南，可轻松添加自定义工具函数。