Skip to main content
Glama
deenesjakoruzh
cornhub69-x

BotDuaChuot MCP

by cornhub69-x
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

BotDuaChuot Host MCP

Минимальный MCP-сервер, который позволяет ChatGPT работать напрямую на вашей машине, ограниченный HOST_WORKSPACE_DIR.

Этот репозиторий выполняет две основные функции:

  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, устанавливает зависимости, создаёт .env с правами 600 и связывает CLI в ~/.local/bin/duachuot. Повторный запуск той же команды обновляет установку через 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. Конфигурация и проверки после установки

Убедитесь, что ~/.local/bin есть в вашем PATH:

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 Tunnel

./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 настроен без сохранения состояния и возвращает 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

Основные конечные точки:

Method

Endpoint

Purpose

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". Политика полностью определяется на стороне сервера.

Инструменты расследования (Forensics + OSINT + Geo)

BotDuaChuot добавляет 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, заметки). Поиск возвращает путь + шаблон вызова + доступность; отсутствующие ресурсы являются БЛОКЕРАМИ, а не тихими запасными вариантами.

Полные руководства: 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–3000 мс).

  • Каждый вывод о координатах требует >= 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 использует временный репозиторий и HOME в /tmp; он никогда не запускает, не останавливает и не перезапускает реальный туннель 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.

CLI duachuot

Репозиторий содержит единый CLI для управления мостом/туннелем и вызова REST API без ручного написания 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 обращается к локальной REST-конечной точке по адресу http://127.0.0.1:<MCP_PORT>. Используйте --public, чтобы взять текущий URL из logs/tunnel_url.txt, или --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 запускает контроль качества при push и pull request; 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