MCP ToolHub

MCP ToolHub는 제한된 작업 공간 파일 시스템 작업, 읽기 전용 Git 검사, 구조화된 명령 실행 및 감사 추적을 제공하는 로컬 stdio 전용 Model Context Protocol 서버입니다. 파일 시스템 변경 작업 및 에이전트가 선택한 모든 외부 셸 명령은 기존의 대역 외 인간 승인 모델을 사용합니다.

ToolHub는 HTTP, SSE 또는 기타 네트워크 리스너를 노출하지 않습니다.

기능

• 작업 공간으로 제한된 파일 읽기, 디렉터리 나열, 쓰기 및 패치

• 읽기 전용 Git 상태 및 diff 작업

• 기본 거부 위험 분류를 사용하는 구조화된 셸 명령

• 원자적이며 만료되고 일회용인 승인 요청

• 별도의 신뢰된 관리자 CLI; MCP 자체 승인 도구 없음

• 제한되고 민감 정보가 제거된 JSON Lines 감사 이벤트

• Windows 및 POSIX 지원

Related MCP server: enterprise-agent-lab

요구 사항

• Python 3.12 이상(CI는 현재 3.12 및 3.13을 검증함)

• stdio 서버를 지원하는 MCP 클라이언트

• Git 도구 및 승인 게이트가 적용된 Git 셸 요청을 위한 git

설치

소스 체크아웃에서 uv로 설치합니다:

uv tool install .

또는 wheel을 빌드하여 설치합니다:

uv build
uv tool install dist/mcp_toolhub-0.1.0-py3-none-any.whl

설치 시 두 개의 실행 파일이 제공됩니다:

• mcp-toolhub — stdio MCP 서버

• mcp-toolhub-admin — 신뢰된 인간 승인 CLI

런타임 구성

작업 공간 루트

TOOLHUB_WORKSPACE_ROOT는 mcp-toolhub serve 및 관리자 CLI에 필수입니다. 기존 디렉터리의 절대 경로를 포함해야 합니다. ToolHub는 경로를 한 번 정규화하여 프로세스 수명 동안 고정합니다.

ToolHub는 의도적으로 현재 디렉터리, 소스 체크아웃 또는 설치 디렉터리를 기본값으로 사용하지 않습니다.

신뢰된 상태 루트

TOOLHUB_STATE_ROOT는 workspace-binding.json, approvals.json 및 audit.jsonl이 포함된 디렉터리를 선택적으로 지정합니다. 지정된 경우 절대 경로여야 합니다. 이 디렉터리는 첫 번째 유효 사용 시 정확히 하나의 정규 작업 공간에 영구적으로 바인딩됩니다. 다른 작업 공간에 재사용하면 실패 시 차단됩니다.

TOOLHUB_STATE_ROOT가 설정되지 않은 경우 ToolHub는 platformdirs의 플랫폼에 적합한 사용자별 상태 디렉터리를 기준으로 사용합니다. 각 정규 작업 공간은 플랫폼 정규화된 정규 작업 공간 경로에서 파생된 결정적 SHA-256 식별자로 이름이 지정된 workspaces/ 아래의 독립적인 네임스페이스를 받습니다. 이 식별자는 디렉터리 이름에 작업 공간 경로가 들어가는 것을 방지하지만, 인증 비밀이 아닌 네임스페이스 분리입니다. 작업 공간을 이동하거나 이름을 바꾸면 일반적으로 새 기본 네임스페이스가 생성됩니다.

상태 디렉터리는 필요에 따라 생성되고 정규화된 후 작업 공간 구성과 함께 고정됩니다. 상태 루트가 작업 공간 내부에 있으면 시작이 실패합니다. 서버와 관리자 CLI는 이 상태를 공유할 수 있도록 동일한 사용자로, 동일한 작업 공간 및 상태 구성으로 실행되어야 합니다.

POSIX 예제

export TOOLHUB_WORKSPACE_ROOT=/home/alice/projects/example
export TOOLHUB_STATE_ROOT=/home/alice/.local/state/mcp-toolhub
mcp-toolhub serve

Windows PowerShell 예제

$env:TOOLHUB_WORKSPACE_ROOT = "D:\work\example"
$env:TOOLHUB_STATE_ROOT = "$env:LOCALAPPDATA\mcp-toolhub"
mcp-toolhub serve

서버는 stdout에 배너나 사람이 읽는 로그 텍스트를 쓰지 않습니다. stdout은 MCP 프로토콜 메시지 전용으로 예약되어 있습니다. 예상되는 구성 오류는 stderr에 간결하게 보고되며 0이 아닌 종료 코드로 종료됩니다.

명령

mcp-toolhub --version
mcp-toolhub serve
python -m mcp_toolhub serve

mcp-toolhub-admin --help
mcp-toolhub-admin list
mcp-toolhub-admin approve REQUEST_ID
mcp-toolhub-admin reject REQUEST_ID

관리자 명령은 사람을 대상으로 하며 stdout에 일반 출력을 쓸 수 있습니다. MCP 전송 프로세스가 아닙니다.

MCP 클라이언트 구성

정확한 외부 구성 키는 클라이언트에 따라 다릅니다. 일반적인 POSIX stdio 항목은 다음과 같습니다:

{
  "mcpServers": {
    "toolhub": {
      "command": "mcp-toolhub",
      "args": ["serve"],
      "env": {
        "TOOLHUB_WORKSPACE_ROOT": "/home/alice/projects/example",
        "TOOLHUB_STATE_ROOT": "/home/alice/.local/state/mcp-toolhub"
      }
    }
  }
}

Windows 경로에는 JSON 이스케이프가 필요합니다:

{
  "mcpServers": {
    "toolhub": {
      "command": "mcp-toolhub",
      "args": ["serve"],
      "env": {
        "TOOLHUB_WORKSPACE_ROOT": "D:\\work\\example",
        "TOOLHUB_STATE_ROOT": "C:\\Users\\alice\\AppData\\Local\\mcp-toolhub"
      }
    }
  }
}

MCP 클라이언트가 셸의 PATH를 상속하지 않는 경우 절대 실행 파일 경로를 사용하십시오.

도구 목록

프로덕션 서버는 정확히 다음 12개의 MCP 도구를 노출합니다:

• toolhub.ping

• toolhub.audit_recent

• filesystem.list_directory

• filesystem.read_file

• filesystem.write_file

• filesystem.write_file_approved

• filesystem.apply_patch

• filesystem.apply_patch_approved

• git.status

• git.diff

• shell.run

• shell.run_approved

MCP 관리, 승인 또는 거부 도구는 없습니다.

인간 승인 워크플로

1. MCP 변경 또는 외부 셸 요청이 보류 중인 요청 ID를 반환합니다.

2. 관리자는 서버와 동일한 작업 공간 및 상태 환경으로 mcp-toolhub-admin list를 실행합니다.

3. 승인을 위해 관리자는 mcp-toolhub-admin approve REQUEST_ID를 실행합니다.

4. CLI는 보호된 요청을 표시하고 운영자가 APPROVE를 정확히 입력하도록 요구합니다.

5. MCP 호출자는 요청 ID로 해당 _approved 도구를 호출합니다. 성공적인 소비는 원자적이며 일회용입니다.

셸 요청의 경우 승인 표시에는 원래 프로그램, 정규화된 실행 파일, SHA-256, 바이트 크기, cwd 및 별도로 JSON 이스케이프된 인자 값이 포함됩니다. 인자를 모호한 셸 명령 문자열로 나타내지 않습니다.

보안 모델 및 제한 사항

구조화된 셸 명령

shell.run은 기본 거부 명령 정책을 사용합니다. LOW는 정확한 ToolHub 고유 기능으로 제한되며, 현재는 실행 중인 Python 버전 조회입니다. LOW는 PATH를 검색하지 않으며 외부 하위 프로세스를 생성하지 않습니다. 일반 Git, 셸 인터프리터, Windows 배치 스크립트, py 실행기 및 알 수 없는 프로그램은 절대 LOW가 아닙니다.

모든 외부 셸 명령은 MEDIUM 또는 HIGH이며 대역 외 관리자 승인이 필요합니다. 승인은 불변의 프로그램, 인자, cwd, 시간 제한, 작업 공간 및 주 실행 파일 스냅샷을 캡처합니다. 승인된 셸 요청은 스냅샷 검증 전에 원자적으로 소비됩니다. 이후의 어떤 실패도 이를 영구히 소비하므로 재시도하려면 새 승인이 필요합니다.

subprocess 실행 직전에 ToolHub는 주 실행 파일의 정규 경로, 크기 및 SHA-256을 검증합니다. 실행은 shell=False로 해당 절대 경로를 사용합니다. 이는 실행 직전에 검증된 주 실행 파일 신원이며, 운영 체제가 최종적으로 매핑하는 정확한 바이트에 대한 암호학적 보장은 아닙니다.

ToolHub가 보장하는 사항:

• LOW는 외부 하위 프로세스를 절대 생성하지 않습니다.

• 모든 외부 셸 실행에는 MEDIUM 또는 HIGH 승인이 필요합니다.

• 에이전트는 승인된 프로그램, 인자, cwd 또는 시간 제한을 교체할 수 없습니다.

• 승인은 원자적이며 만료되고 일회용입니다.

• 작업 공간 및 주 실행 파일 스냅샷은 필수이며 실패 시 차단됩니다.

• 주 실행 파일의 정규 신원과 해시는 실행 직전에 재검증됩니다.

• 파일 시스템 경로는 고정된 작업 공간 경계 내에 유지됩니다.

• 변경 경로는 심볼릭 링크 탐색을 거부하고 해당되는 경우 expected_hash 동시성 검사를 적용합니다.

ToolHub가 보장하지 않는 사항:

• 좁은 최종 검사-실행 경합 동안 동시 로컬 파일 시스템 공격자에 대한 정확한 바이트 신원.

• DLL, 인터프리터, 헬퍼, 플러그인, 구성 파일, 환경에 따라 선택되는 종속성 또는 후손 프로세스의 신원.

• 승인된 실행 파일 바이트가 무해하거나, 서명되었거나, 평판이 좋은 게시자로부터 온 것이라는 점.

관리자 승인 표시는 보호된 정규 경로, 해시, 크기, cwd 및 정확한 JSON 이스케이프된 인자 경계를 노출합니다. 에이전트가 읽을 수 있는 감사 이벤트는 외부 실행 파일 디렉터리를 생략하고 기본 이름, 해시, 크기, 범위 및 요청 ID 연관성을 유지합니다.

감사 동작

감사 이벤트는 신뢰된 상태 루트 아래의 audit.jsonl에 추가됩니다. 제한된 메타데이터를 포함하고, 식별 가능한 비밀 인자를 제거하며, 원시 프로세스 출력 대신 stdout/stderr 문자 수를 저장합니다. 감사 쓰기 실패는 도구 실행에 치명적이지 않습니다.

개발

모든 고정된 런타임 및 개발 종속성을 설치합니다:

uv sync --all-groups

필요한 검사를 실행합니다:

uv run ruff check .
uv run ruff format --check .
uv run python -m compileall -q src/mcp_toolhub
uv run pytest -q
uv build
git diff --check

의도적으로 포맷팅을 적용하려면:

uv run ruff format .

산출물 스모크 테스트

uv build 후 체크아웃 외부의 가상 환경으로 크로스 플랫폼 스모크 드라이버를 실행합니다.

POSIX:

uv run python scripts/artifact_smoke.py --dist-dir dist --venv /tmp/mcp-toolhub-wheel-env --repository .

Windows PowerShell:

uv run python scripts/artifact_smoke.py --dist-dir dist --venv "$env:TEMP\mcp-toolhub-wheel-env" --repository .

드라이버는 wheel 내용을 검사하고, 격리된 환경에 wheel만 설치하며, 콘솔/버전 동작을 확인하고, initialize, list_tools, ping, 구성된 작업 공간 접근, 잘못된 구성 및 서버/관리자 공유 상태 테스트를 저장소 외부에서 실행합니다.

문제 해결

• TOOLHUB_WORKSPACE_ROOT is required: MCP 클라이언트 환경에 절대 경로의 기존 작업 공간 경로를 추가하십시오.

• 작업 공간이 디렉터리가 아닌 경우: 디렉터리를 만들거나 경로를 수정하십시오.

• 상태 루트는 작업 공간 외부에 있어야 합니다: TOOLHUB_STATE_ROOT를 MCP 파일 시스템 도구가 접근할 수 없는 신뢰된 디렉터리로 이동하십시오.

• 상태 네임스페이스가 다른 작업 공간에 속합니다: 다른 명시적 TOOLHUB_STATE_ROOT를 선택하십시오. 바인딩은 절대 자동으로 재할당되지 않습니다.

• 클라이언트가 잘못된 stdio JSON을 보고하는 경우: 래퍼와 시작 스크립트가 stdout에 배너나 로그를 인쇄하지 않는지 확인하십시오.

• 관리자가 요청을 볼 수 없는 경우: 서버와 관리자가 동일한 사용자로, 동일한 작업 공간 및 상태 루트 설정으로 실행되는지 확인하십시오.

• 승인 후 실행 파일이 변경된 경우: 새 승인을 요청하십시오. 소비되었거나 무효화된 승인은 절대 재생되지 않습니다.

프로덕션 ToolHub는 의도적으로 HTTP, SSE, 공개 네트워크, 인증 서버, 컨테이너 오케스트레이션 또는 클라우드 호스팅 표면을 노출하지 않습니다.