Skip to main content
Glama
deenesjakoruzh
cornhub69-x

BotDuaChuot MCP

by cornhub69-x
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

BotDuaChuot Host MCP

Un servidor MCP mínimo que permite a ChatGPT operar directamente en tu máquina, limitado a HOST_WORKSPACE_DIR.

Este repositorio tiene dos funciones principales:

  1. Leer, escribir, buscar archivos y ejecutar comandos en el host.

  2. Proporcionar guía de trabajo además de un inventario real de las herramientas instaladas en la máquina mediante duachuot_knowledge.

Estructura

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

Instalación

1. Instalación en una línea (recomendada)

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

De forma predeterminada, el script clona la rama main en ~/.botduachuot_mcp, crea un .venv, instala las dependencias, crea un .env con permisos 600 y enlaza la CLI en ~/.local/bin/duachuot. Volver a ejecutar el mismo comando actualiza la instalación mediante fast-forward; si el árbol de trabajo tiene archivos sin confirmar, el instalador se detiene para evitar sobrescribir datos del usuario.

Se puede personalizar con variables de entorno:

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

Variables admitidas: DUACHUOT_REPO_URL, DUACHUOT_INSTALL_DIR, DUACHUOT_BIN_DIR, DUACHUOT_BRANCH. DUACHUOT_SKIP_PIP_UPGRADE=true solo debe usarse en entornos de prueba o en configuraciones sin conexión con una caché de paquetes preparada.

2. Instalación manual desde un repositorio local

cd botduachuot_mcp
./install.sh

scripts/install_basic.sh se mantiene por compatibilidad y reenvía directamente al instalador principal.

3. Configuración y comprobaciones posteriores a la instalación

Asegúrate de que ~/.local/bin esté en tu PATH:

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

Añade esta línea a ~/.bashrc o ~/.zshrc para mantenerlo entre sesiones.

Configura .env antes de exponer el servicio. La plantilla predeterminada requiere autenticación:

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

Luego verifica:

duachuot version
duachuot config validate
duachuot doctor

Ejecución mediante Cloudflare Tunnel

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

La URL del conector tiene este aspecto:

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

Streamable HTTP está configurado sin estado y devuelve JSON directamente. Cada solicitud de ChatGPT funciona de forma independiente: no se requiere mcp-session-id ni se mantiene un flujo SSE para las llamadas de herramientas habituales.

MCP_JSON_RESPONSE=true
MCP_STATELESS_HTTP=true

API REST

La API REST comparte los servicios del host con el servidor MCP y se ejecuta en el mismo servidor/túnel. Ruta base:

/api/v1

Documento OpenAPI:

/api/v1/openapi.json

Endpoints principales:

Método

Endpoint

Propósito

GET

/api/v1/health

Estado del servidor

GET

/api/v1/capabilities

Herramientas, espacio de trabajo y límites

GET

/api/v1/files

Listar directorio

GET

/api/v1/files/content

Leer archivo de texto

PUT

/api/v1/files/content

Crear o sobrescribir archivo

PATCH

/api/v1/files/content

Reemplazar texto en archivo

POST

/api/v1/files/append

Añadir contenido a un archivo

POST

/api/v1/directories

Crear directorio

GET

/api/v1/search

Buscar texto en el espacio de trabajo

POST

/api/v1/commands/check

Comprobar un comando

POST

/api/v1/commands/run

Ejecutar un comando en el host

GET

/api/v1/knowledge

Leer guías e inventario de herramientas

Cuando REQUIRE_AUTH=true, utiliza uno de estos encabezados:

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

Ejemplo:

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"

Herramientas 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 no tiene parámetro approval="approved". La política se decide íntegramente en el lado del servidor.

Herramientas de investigación (Forensics + OSINT + Geo)

BotDuaChuot añade 21 herramientas de investigación dedicadas, totalmente sin conexión y deterministas:

# 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

Registro de recursos: resources/RESOURCE_MAP.json se genera a partir del repositorio ctf-tools del host mediante scripts/generate_resource_map.py (habilidades, scripts, herramientas, entradas de bin, notas). Las búsquedas devuelven ruta + plantilla de invocación + disponibilidad; los recursos faltantes son BLOCKERs, nunca respaldos silenciosos.

Playbooks completos: knowledge/GEO_PLAYBOOK.md, knowledge/FORENSICS_PLAYBOOK.md, knowledge/OSINT_PLAYBOOK.md. Habilidades incluidas: skills/ctf-geo, skills/ctf-forensics-plus, skills/ctf-osint-plus, skills/ctf-stego-plus.

OPSEC (obligatorio durante CTF)

  • ctf-live predeterminado: sin consultas a fuentes públicas (sherlock/maigret/whois/dnsrecon/motores de búsqueda), sin herramientas de ataque automatizadas contra el alcance, sin envío automático de flags — siempre a través de un humano.

  • El modo investigation (OSINT_MODE=true) abre consultas OSINT limitadas a lo que especifique el operador.

  • Entre consultas de red: espera a duachuot_ops_jitter() (800–3000 ms).

  • Cada conclusión de coordenadas necesita >= 2 hechos independientes (verificados mediante 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")

Esta herramienta lee los documentos en knowledge/ y compara TOOL_CATALOG.json con el PATH real de la máquina.

Pruebas

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

manual_test_installer.sh usa un repositorio temporal y HOME en /tmp; nunca inicia, detiene ni reinicia un túnel real de Cloudflare.

Configuración clave

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 es solo una capa de protección contra operaciones claramente destructivas, no una sandbox. El servidor MCP se ejecuta con los privilegios del usuario que inicia el proceso.

Ver también: docs/ARCHITECTURE.md y SECURITY.md.

duachuot CLI

El repositorio incluye una CLI unificada para operar el puente/túnel y llamar a la API REST sin escribir curl a mano.

Instala el punto de entrada editable:

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

Ejecútala de cualquiera de las dos formas:

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

Grupo de operaciones locales:

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

Grupo de la API REST:

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

Grupos de soporte de operaciones:

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

Cada comando admite --json. Las opciones globales pueden colocarse antes o después del subcomando:

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

De forma predeterminada, la CLI llama al endpoint REST local en http://127.0.0.1:<MCP_PORT>. Usa --public para tomar la URL actual de logs/tunnel_url.txt, o --base-url para apuntar a otro endpoint.

Códigos de salida principales:

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

Para duachuot cmd run, cuando el servidor ha ejecutado el comando correctamente a nivel de solicitud, el código de salida de la CLI refleja el código de salida real del comando.

Diseño completo: docs/CLI_DESIGN_PLAN.md.

Documentación adicional de la CLI: docs/CLI_MANUAL_TEST_PLAN.md y docs/CLI_IMPLEMENTATION_REPORT.md.

Operaciones y recuperación

Puerta de calidad unificada:

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

Doctor y configuración estrictos:

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

Recopila diagnósticos con la configuración sensible enmascarada:

./scripts/collect_diagnostics.sh

La instalación, el reinicio solo del puente (manteniendo el túnel), la recuperación, la reversión y la lista de verificación de producción se describen en docs/OPERATIONS_RUNBOOK.md.

Arquitectura, seguridad y lanzamientos

  • Arquitectura en tiempo de ejecución y límites: docs/ARCHITECTURE.md

  • Modelo de seguridad y endurecimiento: SECURITY.md

  • Operaciones, recuperación y reversión: docs/OPERATIONS_RUNBOOK.md

  • Lista de verificación de lanzamiento: docs/RELEASE_CHECKLIST.md

GitHub Actions ejecuta la puerta de calidad en push y pull request; Dependabot rastrea las dependencias de Python y 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