Haru VPS MCP

ChatGPT용 미니 컴퓨터로 가는 미니 터널.

Haru VPS MCP는 격리된 VPS 작업 공간을 위한 소규모 자체 호스팅 MCP 게이트웨이입니다. 호스트 자체를 작업 공간으로 만들지 않고 MCP 클라이언트에 제한된 파일 시스템 및 셸 기능을 제공합니다.

MCP client / authenticated tunnel
              |
              v
      Haru MCP gateway
        127.0.0.1:8765
              |
       +------+------+
       |             |
       v             v
 filesystem MCP   shell MCP
  loopback only   loopback only
       |             |
       +------v------+
       isolated workspace

공개/비공개 경계

이 저장소는 작성자의 비공개 프로덕션 환경의 미러가 아닌, 깔끔한 공개 참조 배포판입니다. 비공개 도메인, 머신 ID, 자격 증명, 사고 증거, 프로덕션 배포 상태, 인접 개인 서비스, 소유자별 작업 공간 콘텐츠를 의도적으로 제외합니다.

재사용 가능한 경계는 간단합니다. 게이트웨이와 위임된 작업 공간 백엔드는 루프백에 유지되고, 원격 액세스는 별도로 인증된 터널 또는 리버스 프록시를 통해 제공됩니다.

Related MCP server: FieldCure MCP Filesystem Server

보안 모델

Haru MCP는 강력한 작업 공간 파일 시스템 및 셸 도구를 노출하므로 엔드포인트를 권한 있는 것으로 취급하세요.

• 게이트웨이는 루프백이 아닌 바인드 주소를 거부합니다.

• 작업 공간 백엔드 URL은 명시적인 루프백 HTTP 엔드포인트여야 하며 자격 증명을 포함할 수 없습니다.

• 선택적 공개 Host/Origin 허용 목록은 전송 계층 강화일 뿐입니다. 인증이 아닙니다.

• deploy/Caddyfile.example은 HTTP 403으로 실패 시 닫힙니다. 인그레스 계층이 실제로 클라이언트를 인증할 때만 교체하세요.

• 게이트웨이나 작업 공간 백엔드를 인터넷에 익명으로 노출하지 마세요.

• 위임된 작업 공간을 폐기 가능한 상태로 유지하고 호스트 구성, 자격 증명, 홈 디렉터리 및 프로덕션 데이터와 분리하세요.

이 첫 번째 공개 추출본은 참조 구현입니다. 비공개 프로젝트의 보수적 경계를 유지하지만, 운영자 검토 없이 임의의 배포가 프로덕션에 안전하다는 주장은 아닙니다.

설치 및 테스트

Python 3.10+가 필요합니다.

python -m venv .venv
. .venv/bin/activate
pip install -e '.[test]'
pytest

저장소 로컬 검증 진입점을 실행할 수도 있습니다:

./deploy/verify.sh

구성

예제 환경 파일에서 시작하세요:

cp deploy/haru-mcp.env.example .env

기본적으로 게이트웨이는 127.0.0.1:8765/mcp에서 수신하고 포트 8766의 두 루프백 MCP 백엔드 엔드포인트에 위임합니다. 해당 백엔드는 전용 작업 공간 루트로 범위가 지정되어야 합니다.

인증된 리버스 프록시 또는 터널이 공개 호스트 이름을 루프백 게이트웨이로 전달하는 경우 둘 다 설정하세요:

HARU_MCP_PUBLIC_HOST=mcp.example.com
HARU_MCP_PUBLIC_ORIGIN=https://mcp.example.com

이 설정은 Host/Origin 검증만 확장합니다. 인증을 추가하지 않습니다.

실행

haru-mcp

공개 도구 표면은 의도적으로 작습니다: 게이트웨이 상태, 작업 공간 디렉터리 나열/읽기/쓰기/편집/이동/stat, 그리고 루프백 MCP 백엔드에 위임된 격리된 셸 실행입니다.

배포 예제

deploy/haru-mcp.service.example은 강화된 systemd 서비스 형태를 보여줍니다. deploy/Caddyfile.example은 운영자가 인증된 인그레스 설계를 제공할 때까지 의도적으로 실패 시 닫힙니다.

라이선스

이 공개 저장소에는 아직 라이선스가 선택되지 않았습니다. 라이선스 부여는 더 넓은 배포 전에 소유자가 후속 조치할 사항입니다.