Skip to main content
Glama
deenesjakoruzh
cornhub69-x

BotDuaChuot MCP

by cornhub69-x
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

BotDuaChot 호스트 MCP

HOST_WORKSPACE_DIR 범위 내에서 ChatGPT가 사용자의 머신에서 직접 작업할 수 있게 해주는 최소한의 MCP 서버입니다.

이 저장소는 두 가지 주요 기능을 제공합니다:

  1. 호스트에서 파일 읽기, 쓰기, 검색 및 명령 실행.

  2. duachuot_knowledge를 통해 머신에 설치된 도구의 실제 인벤토리와 함께 실무 가이드 제공.

레이아웃

app/
├── host/                 # File, command, policy and tool-inventory logic
├── geo/                  # Geo Engine (convert, geodesic, exif, reverse, timezone)
├── ops/                  # OPSEC gate
├── platform/             # OS/distro/arch/shell + tool resolution
├── tools/                # MCP adapters: health, host, knowledge, geo, probes, ops
├── config.py
├── mcp_server.py
└── main.py

knowledge/
├── WORKING_GUIDE.md
├── HOST_ENVIRONMENT.md
├── TOOL_CATALOG.json
├── GEO_PLAYBOOK.md
├── FORENSICS_PLAYBOOK.md
└── OSINT_PLAYBOOK.md

skills/
├── ctf-geo/
├── ctf-forensics-plus/
├── ctf-osint-plus/
└── ctf-stego-plus/

datasets/
└── landmarks.json

resources/
└── RESOURCE_MAP.json (generated from the host ctf-tools repo)
└── landmarks.json

install.sh
scripts/
├── install_basic.sh
├── install_cli.sh
├── uninstall_cli.sh
├── restart_server_only.sh
├── start_tunnel_server.sh
├── dev.sh
├── install_datasets.py
└── test.sh

Related MCP server: local-drive-mcp

설치

1. 원라인 설치(권장)

curl -fsSL https://raw.githubusercontent.com/cornhub69-x/botduachuot_mcp/main/install.sh | bash

기본적으로 스크립트는 main 브랜치를 ~/.botduachuot_mcp에 클론하고, .venv를 생성하며, 의존성을 설치하고, 600 권한으로 .env를 생성한 다음, ~/.local/bin/duachuot에 CLI를 링크합니다. 동일한 명령을 다시 실행하면 fast-forward 방식으로 설치가 업데이트됩니다. 작업 트리에 커밋되지 않은 파일이 있으면 설치 프로그램은 사용자 데이터를 덮어쓰지 않기 위해 중단됩니다.

환경 변수로 사용자 지정할 수 있습니다:

curl -fsSL https://raw.githubusercontent.com/cornhub69-x/botduachuot_mcp/main/install.sh | \
  DUACHUOT_INSTALL_DIR="$HOME/apps/botduachuot_mcp" \
  DUACHUOT_BIN_DIR="$HOME/.local/bin" \
  DUACHUOT_BRANCH=main \
  bash

지원되는 변수: DUACHUOT_REPO_URL, DUACHUOT_INSTALL_DIR, DUACHUOT_BIN_DIR, DUACHUOT_BRANCH. DUACHUOT_SKIP_PIP_UPGRADE=true는 테스트 환경이나 준비된 패키지 캐시가 있는 오프라인 환경에서만 사용해야 합니다.

2. 로컬 저장소에서 수동 설치

cd botduachuot_mcp
./install.sh

scripts/install_basic.sh는 호환성을 위해 유지되며 메인 설치 프로그램으로 직접 전달됩니다.

3. 구성 및 설치 후 확인

PATH에 ~/.local/bin이 있는지 확인하세요:

export PATH="$HOME/.local/bin:$PATH"

세션 간에 유지하려면 이 줄을 ~/.bashrc 또는 ~/.zshrc에 추가하세요.

서비스를 노출하기 전에 .env를 구성하세요. 기본 템플릿은 인증을 요구합니다:

REQUIRE_AUTH=true
GATEWAY_TOKEN=<secret-random-token>
HOST_WORKSPACE_DIR=/home/user

그런 다음 확인하세요:

duachuot version
duachuot config validate
duachuot doctor

Cloudflare 터널을 통한 실행

./run_mcp_tunnel.sh
./run_mcp_tunnel.sh --status
./run_mcp_tunnel.sh --url
./run_mcp_tunnel.sh --stop

커넥터 URL은 다음과 같습니다:

https://<random>.trycloudflare.com/mcp

Streamable HTTP는 상태 비저장(stateless)으로 구성되며 JSON을 직접 반환합니다. 모든 ChatGPT 요청은 독립적으로 작동합니다. 일반 도구 호출에는 mcp-session-id가 필요하지 않으며 SSE 스트림도 유지되지 않습니다.

MCP_JSON_RESPONSE=true
MCP_STATELESS_HTTP=true

REST API

REST API는 MCP 서버와 호스트 서비스를 공유하며 동일한 서버/터널에서 실행됩니다. 기본 경로:

/api/v1

OpenAPI 문서:

/api/v1/openapi.json

주요 엔드포인트:

메서드

엔드포인트

용도

GET

/api/v1/health

서버 상태

GET

/api/v1/capabilities

도구, 작업 공간 및 제한

GET

/api/v1/files

디렉터리 목록

GET

/api/v1/files/content

텍스트 파일 읽기

PUT

/api/v1/files/content

파일 생성 또는 덮어쓰기

PATCH

/api/v1/files/content

파일의 텍스트 바꾸기

POST

/api/v1/files/append

파일에 내용 추가

POST

/api/v1/directories

디렉터리 생성

GET

/api/v1/search

작업 공간에서 텍스트 검색

POST

/api/v1/commands/check

명령 확인

POST

/api/v1/commands/run

호스트에서 명령 실행

GET

/api/v1/knowledge

가이드 및 도구 인벤토리 읽기

REQUIRE_AUTH=true인 경우 다음 헤더 중 하나를 사용하세요:

Authorization: Bearer <GATEWAY_TOKEN>
X-Gateway-Token: <GATEWAY_TOKEN>

예시:

BASE_URL="https://<tunnel>.trycloudflare.com"
TOKEN="<GATEWAY_TOKEN>"

curl -H "Authorization: Bearer $TOKEN" \
  "$BASE_URL/api/v1/files?path=GitHub"

curl -X PUT \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"path":"Workspace/demo.txt","content":"hello REST\n"}' \
  "$BASE_URL/api/v1/files/content"

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"command":"git status --short","cwd":"GitHub/botduachuot_mcp"}' \
  "$BASE_URL/api/v1/commands/run"

MCP 도구

health_check
get_capabilities
duachuot_list_directory
duachuot_read_file
duachuot_write_file
duachuot_replace_in_file
duachuot_append_file
duachuot_make_directory
duachuot_search_text
duachuot_check_command
duachuot_run_command
duachuot_knowledge

duachuot_run_command에는 approval="approved" 매개변수가 없습니다. 정책은 전적으로 서버 측에서 결정됩니다.

조사 도구(포렌식 + OSINT + 지리 정보)

BotDuaChot는 21개의 전용 조사 도구를 추가하며, 모두 완전히 오프라인에서 결정론적으로 작동합니다:

# Geo Engine (offline, no network required)
duachuot_geo_extract         # EXIF GPS, exiftool/exiv2 cross-check, DOP/HPE, timezone, landmarks
duachuot_geo_scan            # scan arbitrary text/logs/SRT/NMEA/MGRS/UTM for coordinates
duachuot_coord_convert       # DMS/decimal/UTM/MGRS + datum transform (WGS84/ED50/NAD27)
duachuot_geo_calc            # geodesic distance/bearing + uncertainty from DOP/HPE
duachuot_geo_reverse         # offline reverse geocoding (landmarks + country resolution)
duachuot_geo_verify          # conclude only with >= 2 independent facts; fewer -> BLOCKER
duachuot_geo_landmark_check  # radius check around a landmark
duachuot_timezone_at         # offline timezone/UTC offset from coordinates

# Probes
duachuot_media_probe         # file + exiftool JSON + ffprobe
duachuot_pcap_probe          # conversations/endpoints/DNS + GPS hints (NMEA, Wi-Fi probes)
duachuot_disk_probe          # fsstat + fls
duachuot_mem_probe           # Volatility 3 (info/pslist)
duachuot_stego_probe         # binwalk + steghide, WAV LSB detection, LSB/MP3 extraction
duachuot_ocr_probe           # tesseract + QR (zxing-cpp)
duachuot_win_probe           # SAM/SYSTEM hives, LNK, prefetch (pure-Python, Linux/Windows)

# OPSEC + platform
duachuot_ops_check           # blocks telemetry / attack tools / discovery while ctf-live / flags in commands
duachuot_ops_jitter          # human-like delay between network queries
duachuot_ops_redact          # redact secret/flag before writing logs
duachuot_platform            # probe OS/arch/distro/shell + tool availability (native/WSL/missing)
duachuot_plan                # generate an investigation plan by artifact type
duachuot_resource_lookup     # resolve a managed ctf-tools resource from RESOURCE_MAP.json

리소스 레지스트리: resources/RESOURCE_MAP.json은 호스트의 ctf-tools 저장소에서 scripts/generate_resource_map.py에 의해 생성됩니다(스킬, 스크립트, 도구, bin 항목, 노트). 조회는 경로 + 호출 템플릿 + 사용 가능 여부를 반환합니다. 누락된 리소스는 조용한 폴백이 아닌 차단(BLOCKER)입니다.

전체 플레이북: knowledge/GEO_PLAYBOOK.md, knowledge/FORENSICS_PLAYBOOK.md, knowledge/OSINT_PLAYBOOK.md. 번들 스킬: skills/ctf-geo, skills/ctf-forensics-plus, skills/ctf-osint-plus, skills/ctf-stego-plus.

OPSEC(CTF 중 필수)

  • 기본 ctf-live: 공개 소스 조회(sherlock/maigret/whois/dnsrecon/검색 엔진) 금지, 범위 내 자동 공격 도구 금지, 자동 플래그 제출 금지 — 항상 사람을 통해서만.

  • investigation 모드(OSINT_MODE=true)는 운영자가 지정한 범위로 OSINT 조회를 허용합니다.

  • 네트워크 쿼리 사이에는 duachuot_ops_jitter()(800–3000ms)을 기다립니다.

  • 모든 좌표 결론은 2개 이상의 독립적인 사실이 필요합니다(duachuot_geo_verify로 검증).

duachuot_knowledge

duachuot_knowledge(section="overview")
duachuot_knowledge(section="guide")
duachuot_knowledge(section="tools", query="python", include_versions=true)
duachuot_knowledge(section="search", query="docker")

이 도구는 knowledge/의 문서를 읽고 TOOL_CATALOG.json을 머신의 실제 PATH와 대조합니다.

테스트

./scripts/test.sh
./scripts/quality_gate.sh
./scripts/manual_test_installer.sh

manual_test_installer.sh는 /tmp에 임시 저장소와 HOME을 사용합니다. 실제 Cloudflare 터널을 시작, 중지 또는 재시작하지 않습니다.

주요 구성

HOST_WORKSPACE_DIR=/home/light
HOST_RESTRICT_TO_WORKSPACE=true
HOST_COMMAND_POLICY=guarded
MAX_TIMEOUT_SECONDS=60
MAX_OUTPUT_BYTES=500000
REQUIRE_AUTH=true
GATEWAY_TOKEN=<secret>

guarded는 명백히 파괴적인 작업에 대한 보호 계층일 뿐이며, 샌드박스가 아닙니다. MCP 서버는 프로세스를 시작한 사용자의 권한으로 실행됩니다.

참고: docs/ARCHITECTURE.md 및 SECURITY.md.

duachuot CLI

이 저장소는 브리지/터널을 운영하고 REST API를 호출하기 위한 통합 CLI를 제공하며, curl을 직접 작성할 필요가 없습니다.

편집 가능한 엔트리 포인트 설치:

.venv/bin/python -m pip install -e . --no-deps

두 가지 방법 중 하나로 실행:

./bin/duachuot --help
.venv/bin/duachuot --help

로컬 운영 그룹:

duachuot start
duachuot status
duachuot url
duachuot server restart   # restart the bridge only, keep the tunnel URL
duachuot restart --yes    # restart the tunnel too, URL may change
duachuot stop

REST API 그룹:

duachuot health
duachuot --public health
duachuot capabilities --tools
duachuot fs ls GitHub
duachuot fs cat GitHub/project/README.md --lines 1:40
duachuot fs write GitHub/demo.txt --text "hello"
printf 'next\n' | duachuot fs append GitHub/demo.txt --stdin
duachuot fs search FastMCP --path GitHub/botduachuot_mcp
duachuot cmd check 'git status --short'
duachuot cmd run 'git status --short' --cwd GitHub/botduachuot_mcp
duachuot knowledge tools --query python --versions

운영 지원 그룹:

duachuot logs server -n 100
duachuot logs follow server
duachuot config show
duachuot config validate
duachuot doctor
duachuot completion bash

모든 명령은 --json을 지원합니다. 전역 옵션은 하위 명령 앞이나 뒤에 배치할 수 있습니다:

duachuot --public health --json
duachuot health --public --json

기본적으로 CLI는 http://127.0.0.1:<MCP_PORT>의 로컬 REST 엔드포인트를 호출합니다. --public을 사용하면 logs/tunnel_url.txt에서 현재 URL을 가져오고, --base-url을 사용하면 다른 엔드포인트를 지정할 수 있습니다.

주요 종료 코드:

0  success
1  operation failed
2  invalid arguments
3  cannot reach the server
4  authentication failed
5  blocked by policy
6  resource not found
7  timeout
8  conflict

duachuot cmd run의 경우, 서버가 요청 수준에서 명령을 성공적으로 실행했을 때 CLI 종료 코드는 명령의 실제 종료 코드를 그대로 반영합니다.

전체 설계: docs/CLI_DESIGN_PLAN.md.

추가 CLI 문서: docs/CLI_MANUAL_TEST_PLAN.md 및 docs/CLI_IMPLEMENTATION_REPORT.md.

운영 및 복구

통합 품질 게이트:

./scripts/quality_gate.sh
./scripts/quality_gate.sh --runtime
./scripts/quality_gate.sh --full

엄격한 의사 진단 및 구성:

duachuot doctor --local-only
duachuot doctor --strict
duachuot config validate --strict

민감한 구성이 삭제된 진단 정보 수집:

./scripts/collect_diagnostics.sh

설치, 브리지 전용 재시작(터널 유지), 복구, 롤백 및 프로덕션 체크리스트는 docs/OPERATIONS_RUNBOOK.md에 설명되어 있습니다.

아키텍처, 보안 및 릴리스

  • 런타임 아키텍처 및 경계: docs/ARCHITECTURE.md

  • 보안 모델 및 강화: SECURITY.md

  • 운영, 복구 및 롤백: docs/OPERATIONS_RUNBOOK.md

  • 릴리스 체크리스트: docs/RELEASE_CHECKLIST.md

GitHub Actions는 푸시 및 풀 리퀘스트 시 품질 게이트를 실행합니다. Dependabot은 Python 및 GitHub Actions 의존성을 추적합니다.

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • local-drive-mcp

    sofakingmc0804
    A
    license
    Not graded
    quality
    C
    maintenance
    MCP server enabling ChatGPT to interact with local filesystem via controlled file operations like read, write, edit, and search, with configurable guardrails for safety.
    MIT

  • Shared Credit Tool

    Minglink
    A
    license
    Not graded
    quality
    C
    maintenance
    Local MCP server enabling Codex and ChatGPT to read/write files, execute commands, manage processes, use Git, and inspect images on the user's machine with full privileges.
    Apache 2.0