Scripthold — Secure MCP Server for Local Workspaces

Code from the web. Work locally. Recover safely.

Scripthold is a Model Context Protocol (MCP) server that gives web, desktop, and CLI agents controlled access to explicitly authorized local workspaces. It reads and writes legacy text safely, exposes deterministic repository-oriented workflows, supports authenticated Streamable HTTP as well as stdio, and can optionally run durable asynchronous local tasks.

AI clients see Настройки — not ???? or Íàñòðîéêè.

Scripthold detects encodings from bytes and decoded-text evidence rather than filenames, presents text to the MCP client as UTF-8, and preserves or deliberately converts encoding, BOM, and line endings through bounded-memory and durable filesystem operations.

• 36 tools and 3 guided prompts over one authoritative catalog in Scripthold 3.1.6.
• 168 registered encodings, including UTF-32 LE/BE and broad portable legacy coverage; automatic detection remains intentionally more conservative than explicit codec support.
• 101 active source-intelligence providers across programming languages, dialects, DSLs, document/config formats, and composites, with capability-specific evidence and fail-closed ambiguity.
• Secure filesystem boundaries with resolved-root containment, deterministic traversal, Windows reparse/junction handling, staged mutation, conflict detection, and no-replace creation.
• Verified change workflows with deterministic fingerprints, one-shot edit approval, strict patch packages, persistent backup integration, and typed verification.
• Offline backup recovery with deterministic persisted review plans, immutable source evidence, fully verified reconstruction into a separate staged destination, mandatory full audit, no-replace promotion, and path-free provenance.
• Durable asynchronous execution with idempotent admission, an owner-only task store, bounded queue/logs, independent supervisor/worker/executor lifecycle, recovery, logical locks, and cancellation.
• Fail-closed Streamable HTTP with bearer authentication, loopback defaults, exact Host/Origin checks, bounded resources, no CORS, and explicit TLS/proxy requirements for non-loopback exposure.

Scripthold was built with Scripthold.

Lineage: Scripthold originated from the original mcp-file-tools project, created by Dimitar Grigorov, and retains its GPL-3.0 lineage and permanent attribution. See Project Direction.

Current release and development state

Scripthold 3.1.6 is the current public release. It exposes 36 tools, 3 guided prompts, 168 registered encodings, and 101 active source-intelligence providers over the same stdio and Streamable HTTP surface. source_symbols provides bounded declaration/navigation workflows; source_query adds structural search, supported project relations, fingerprint-verified context, and coherent process-local index generations. Capability claims remain provider-specific and fail closed where evidence is insufficient.

R1-R28 and the subsequent pre-R29 verification-architecture maintenance program are complete. No release-scoped milestone is currently active; R29-R33 remain planned. See CHANGELOG.md for release changes, docs/ROADMAP.md for current/future work, docs/ROADMAP_HISTORY.md for concise engineering history, and the subsystem contracts for detailed behavior.

Quality and security

The push-event Test Suite is the exact-commit release-candidate gate. It covers Windows/Linux/macOS native regression and race testing, Go vet, standalone Staticcheck, the repository's focused golangci-lint policy, govulncheck, deterministic fuzz checks, six supported-target cross-builds, workflow/shell validation, and native/container smoke before the aggregate Release candidate job can pass.

CodeQL adds Go code scanning on main pushes, a weekly schedule, and manual runs. Vulnerability reporting and responsible-disclosure guidance are in SECURITY.md. Secret scanning, allowed-root confinement, durable mutation/backup invariants, encoding safety, and transport security remain part of the repository's normal verification model rather than badge-only claims.

Transport and authorization model

Both transports use the same BuildServer path and expose the same tools, prompts, limits, encoding behavior, error model, and execution policy.

Allowed directories are a process-wide authorization boundary. Sessions separate protocol lifecycle and cancellation; they are not per-agent filesystem ACLs. If two agents require technical isolation, run separate Scripthold processes with narrower roots and, for concurrent Git writes, separate checkouts or worktrees.

MCP 2026-07-28 is supported through the stable Go SDK. Native HTTP serves stateless modern requests beside retained stateful legacy sessions under the same outer authentication, Host/Origin, resource, logging, and execution controls. See docs/MCP_2026_07_28_ADOPTION.md and docs/HTTP_SECURITY.md.

Tool catalog

File and directory operations

• read_text_file — stream decoded text with bounded output and optional line numbers.
• read_multiple_files — deterministic bounded batch reads with per-file status.
• write_whole_file — replace complete file contents through the shared encoder.
• edit_file — read-only exact edit preview with approval fingerprints and a one-shot capability.
• edit_file_apply — apply only the exact prepared edit identified by previewId.
• patch_package — read-only inspect/dry-run/verify for declared multi-file edits.
• patch_package_apply — apply only a prepared patch-package capability.
• list_directory — list directory entries with filtering and deterministic sorting.
• tree — compact .gitignore-aware deterministic tree output.
• get_file_info — read file or directory metadata.
• filesystem_package — read-only bounded preparation for coordinated no-replace create/copy/move/delete filesystem changes.
• filesystem_package_apply — apply one prepared filesystem package by one-shot previewId.
• search_files — bounded .gitignore-aware glob search.
• source_symbols — bounded read-only source outline, digest, find, and fingerprint-bound show navigation.
• source_query — bounded R27 read-only structural search, supported project relations, and fingerprint-verified task-context assembly.
• fingerprint_paths — deterministic SHA-256 state fingerprints.
• verify_state — bounded typed JSON/text/Git-diff/fingerprint checks.
• backup_store — read-only status/history/compare/audit plus restore/GC preparation for the optional persistent store.
• backup_restore_apply — apply one prepared original-target restore.
• backup_gc_apply — apply one prepared generation-bound backup GC plan.
• grep_text_files — paged regex search with deterministic partial-coverage reporting.

Encoding and service tools