Skip to main content
Glama
deenesjakoruzh
cornhub69-x

BotDuaChuot MCP

by cornhub69-x
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

BotDuaChuot Host MCP

A minimal MCP server that lets ChatGPT operate directly on your machine, scoped to HOST_WORKSPACE_DIR.

This repository has two main functions:

  1. Read, write, search files and run commands on the host.

  2. Provide working guidance plus a real inventory of tools installed on the machine via duachuot_knowledge.

Layout

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

Related MCP server: local-drive-mcp

Installation

1. One-line install (recommended)

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

By default the script clones the main branch into ~/.botduachuot_mcp, creates a .venv, installs dependencies, creates a .env with 600 permissions, and links the CLI at ~/.local/bin/duachuot. Re-running the same command updates the installation via fast-forward; if the working tree has uncommitted files, the installer stops to avoid overwriting user data.

It can be customized with environment variables:

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

Supported variables: DUACHUOT_REPO_URL, DUACHUOT_INSTALL_DIR, DUACHUOT_BIN_DIR, DUACHUOT_BRANCH. DUACHUOT_SKIP_PIP_UPGRADE=true should only be used in test environments or offline setups with a prepared package cache.

2. Manual install from a local repository

cd botduachuot_mcp
./install.sh

scripts/install_basic.sh is kept for compatibility and forwards directly to the main installer.

3. Configuration and post-install checks

Make sure ~/.local/bin is in your PATH:

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

Add this line to ~/.bashrc or ~/.zshrc to keep it across sessions.

Configure .env before exposing the service. The default template requires authentication:

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

Then verify:

duachuot version
duachuot config validate
duachuot doctor

Running through Cloudflare Tunnel

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

The connector URL looks like:

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

Streamable HTTP is configured stateless and returns JSON directly. Every ChatGPT request works independently: no mcp-session-id is required and no SSE stream is kept for regular tool calls.

MCP_JSON_RESPONSE=true
MCP_STATELESS_HTTP=true

REST API

The REST API shares the host services with the MCP server and runs on the same server/tunnel. Base path:

/api/v1

OpenAPI document:

/api/v1/openapi.json

Main endpoints:

Method

Endpoint

Purpose

GET

/api/v1/health

Server status

GET

/api/v1/capabilities

Tools, workspace and limits

GET

/api/v1/files

List directory

GET

/api/v1/files/content

Read text file

PUT

/api/v1/files/content

Create or overwrite file

PATCH

/api/v1/files/content

Replace text in file

POST

/api/v1/files/append

Append content to file

POST

/api/v1/directories

Create directory

GET

/api/v1/search

Search text in workspace

POST

/api/v1/commands/check

Check a command

POST

/api/v1/commands/run

Run a command on the host

GET

/api/v1/knowledge

Read guides and tool inventory

When REQUIRE_AUTH=true, use one of these headers:

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

Example:

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 tools

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 has no approval="approved" parameter. Policy is decided entirely server-side.

Investigation tools (Forensics + OSINT + Geo)

BotDuaChuot adds 21 dedicated investigation tools, fully offline and deterministic:

# 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

Resource Registry: resources/RESOURCE_MAP.json is generated from the host ctf-tools repository by scripts/generate_resource_map.py (skills, scripts, tools, bin entries, notes). Lookups return path + invoke template + availability; missing resources are BLOCKERs, never silent fallbacks.

Full playbooks: knowledge/GEO_PLAYBOOK.md, knowledge/FORENSICS_PLAYBOOK.md, knowledge/OSINT_PLAYBOOK.md. Bundled skills: skills/ctf-geo, skills/ctf-forensics-plus, skills/ctf-osint-plus, skills/ctf-stego-plus.

OPSEC (mandatory during CTF)

  • Default ctf-live: no public-source lookups (sherlock/maigret/whois/dnsrecon/search engines), no automated attack tools against scope, no automatic flag submission — always through a human.

  • investigation mode (OSINT_MODE=true) opens OSINT lookups scoped to what the operator specifies.

  • Between network queries: wait for duachuot_ops_jitter() (800–3000 ms).

  • Every coordinate conclusion needs >= 2 independent facts (verified via 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")

This tool reads the documents in knowledge/ and matches TOOL_CATALOG.json against the machine's actual PATH.

Testing

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

manual_test_installer.sh uses a temporary repository and HOME in /tmp; it never starts, stops or restarts a real Cloudflare tunnel.

Key configuration

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 is only a protection layer against obviously destructive operations, not a sandbox. The MCP server runs with the privileges of the user that starts the process.

See also: docs/ARCHITECTURE.md and SECURITY.md.

duachuot CLI

The repository ships a unified CLI to operate the bridge/tunnel and call the REST API without hand-writing curl.

Install the editable entry point:

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

Run it either way:

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

Local operations group:

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 group:

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

Operations support groups:

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

Every command supports --json. Global options can be placed before or after the subcommand:

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

By default the CLI calls the local REST endpoint at http://127.0.0.1:<MCP_PORT>. Use --public to take the current URL from logs/tunnel_url.txt, or --base-url to point at another endpoint.

Main exit codes:

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

For duachuot cmd run, when the server executed the command successfully at the request level, the CLI exit code mirrors the real exit code of the command.

Full design: docs/CLI_DESIGN_PLAN.md.

Operations and recovery

Unified quality gate:

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

Strict doctor and config:

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

Collect diagnostics with sensitive configuration redacted:

./scripts/collect_diagnostics.sh

Installation, bridge-only restart (keeping the tunnel), recovery, rollback and the production checklist are described in docs/OPERATIONS_RUNBOOK.md.

Architecture, security and releases

  • Runtime architecture and boundaries: docs/ARCHITECTURE.md

  • Security model and hardening: SECURITY.md

  • Operations, recovery and rollback: docs/OPERATIONS_RUNBOOK.md

  • Release checklist: docs/RELEASE_CHECKLIST.md

GitHub Actions runs the quality gate on push and pull request; Dependabot tracks Python and GitHub Actions dependencies.

This server cannot be deployed

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Maintenance

ActivityMaintained
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