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 의 매우 작고 오버헤드 없음의 구현체입니다. 이는 AI 에이전트 클라이언트에 get_weather, list_files 와 같은 tool 함수를, 대규모 MCP 서버가 사용하는 것과 동일한 JSON-RPC 스타일의 요청/응답 형식으로 노출할 수 있게 해주지만, Node나 Python과 같은 무거운 런타임을 도입할 필요가 없습니다.

🎯 핵심 아이디어

상태 없는, 요청 단위 프로토콜 – 2026-07-28 버전은 핸드셰이크와 세션을 제거했기 때문에 각 요청은 단일 JSON 라인으로, 간단한 read-loop에서 처리할 수 있습니다.
하나의 코드베이스, 두 가지 전송 방식 – 동일한 Bash 스크립트가 stdio (LLM 에이전트가 하위 프로세스를 시작하는 일반적인 방식) 또는 로컬 HTTP POST 엔드포인트 (socat/netcat 사용)를 통해 요청을 처리할 수 있습니다.
이름 기반 도구 탐지 – tool_으로 시작하는 이름의 Bash 함수는 자동으로 server/discover 응답에 포함되며, tools/call로 호출할 수 있습니다.

🛠️ 주요 구성 요소 (README에 설명됨)

파일 / 디렉터리	역할
`mcpserver_core.sh`	JSON-RPC 프레임워크, MCP 메서드 디스패치, 버전 협상, 공식 JSON 스키마(예: `jq` 및 선택적 `jsonschema`) 기반 출력 검증을 처리합니다.
`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, 파일 서버의 4개 실행 가능한 서버 데모와 함께, "자신만의 서버 만들기"를 위한 단계별 가이드입니다.
`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).
mcpserver_core.sh를 source하기 전에 설정 경로(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

AI 에이전트에 간단한 도구를 노출해야 하는 경우(예: 프로토타이핑, 로컬 개발, Node/Python 설치가 바람직하지 않은 환경), 이 리포지토리는 stdio와 로컬 HTTP 양방향 바인딩을 갖춘, 사양 준수된 구현체를 제공합니다. 철저한 테스트와 사용자 정의 도구 함수 추가를 위한 명확한 안내도 포함되어 있습니다.