Scripthold

Scripthold — 面向本地工作区的安全 MCP 服务

从网络获取代码。在本地工作。安全恢复。

Scripthold 是一个 Model Context Protocol (MCP) 服务，可让网页、桌面和命令行 Agent 受控访问经过明确授权的本地工作区。它能安全处理旧版文本编码、确定性文件更改、源代码导航、备份，以及通过 stdio 或经过身份验证的 Streamable HTTP 执行可选的持久化本地任务。

AI 客户端看到的是 Настройки，而不是 ???? 或 Íàñòðîéêè。

从这里开始：快速开始 · 查找工具 · 全部文档 · 安全策略。

Scripthold 提供的功能

Scripthold 4.x 提供 36 个工具和 3 个引导式提示词；最新发布版本请参阅 GitHub Releases。从 3.x 升级的客户端应遵循 4.0 迁移指南，了解统一确认工具。4.0.1 中，source_symbols outline 响应默认使用紧凑树形格式；传入 presentation: "detailed" 可保留先前的 files 和 symbols 字段。

• 168 种已注册的文本编码，支持基于内容的检测、UTF-32 LE/BE，并采用保守的歧义处理方式。
• 100 个活跃的源代码智能提供程序，用于有界声明导航、结构化搜索、所选项目关系和经过验证的上下文组装。
• 安全的工作区边界，包含规范根目录范围校验、Windows 重解析点/联接处理、确定性遍历和路径缺失验证。
• 与审批绑定的变更操作，使用预览/应用能力、精确指纹、冲突检查、暂存写入和如实的部分状态报告。
• 可选的持久化备份，支持历史记录、比较、审计、恢复、显式垃圾回收、固定和按精确 ID 删除。
• 持久化异步任务，支持幂等性、持久化状态、有界日志、恢复、锁定和取消。
• 可靠的长时间运行只读调用，通过可选的延迟操作存储和有界的保留结果检索实现。
• 经过身份验证的 Streamable HTTP，采用回环地址默认值、Bearer 身份验证、Host/Origin 验证、资源限制，以及非回环地址暴露所需的显式 TLS/代理要求。

Scripthold 源自原始的 mcp-file-tools 项目，该项目由 Dimitar Grigorov 创建，并沿袭 GPL-3.0 许可证。请参阅项目方向。

快速开始

选择一个已发布的二进制文件，或从源代码构建；然后配置 MCP 客户端，使其仅能访问你打算共享的目录。HTTP 和容器部署还需要完成下文所述的额外设置。

使用已发布的版本

从最新版本下载适用于你平台的构建文件，并根据 checksums.txt 验证。常规 GoReleaser 构建文件还附带经过签名的 Sigstore 构建来源证明包。

从源代码构建

git clone https://github.com/zoster81/scripthold.git
cd scripthold
go test ./...
go build -o scripthold ./cmd/scripthold

模块路径为 github.com/zoster81/scripthold。

本地 stdio 客户端

将每个已授权目录作为启动参数传入：

{
  "mcpServers": {
    "scripthold": {
      "type": "stdio",
      "command": "C:\\Tools\\scripthold_windows_amd64.exe",
      "args": ["D:\\Projects"]
    }
  }
}

启动根目录具有权威性。只有在进程启动时未传入目录参数的情况下，支持 roots 的 stdio 客户端才能提供动态根目录。

已验证的自我更新

受支持的独立安装可以选择启用自我更新。运行 scripthold update --adopt 前，请停止使用同一二进制文件的其他 Scripthold 进程。接管操作会准备本地状态，不会下载或替换可执行文件。

完成接管后，运行 scripthold update 来验证并分发可用版本。使用 scripthold update status 确认是否完成；仅当状态命令提示可恢复时，才运行 scripthold update recover。这些操作具有不同的安全性和验证要求。

有关受支持的安装方式、精确命令、故障处理和恢复规则，请参阅已验证的自我更新指南。

Streamable HTTP

HTTP 必须且只能配置一个 Bearer 令牌来源。最简的回环地址 PowerShell 启动命令如下：

$tokenPath = Join-Path $env:TEMP "scripthold.token"
$bytes = New-Object byte[] 32
$rng = [System.Security.Cryptography.RandomNumberGenerator]::Create()
try { $rng.GetBytes($bytes) } finally { $rng.Dispose() }
[System.IO.File]::WriteAllText($tokenPath, [Convert]::ToBase64String($bytes), [System.Text.UTF8Encoding]::new($false))

$env:MCP_HTTP_TOKEN_FILE = $tokenPath
$env:MCP_HTTP_ADDR = "127.0.0.1:8765"
.\scripthold_windows_amd64.exe --transport=streamable-http D:\Projects

MCP 端点为 http://127.0.0.1:8765/mcp；/healthz 和 /readyz 用于检查存活状态和就绪状态。每个 MCP 请求都要在 Authorization: Bearer <token> 中发送令牌。

在阅读 HTTP 安全之前，不要将 HTTP 暴露到回环地址之外。非回环地址使用需要显式选择启用，并要求配置 TLS 或可信代理边界。

OpenAI Secure MCP Tunnel

已清理的 PowerShell 示例位于 examples/ 下：

• start-local-stdio.ps1
• start-local-http.ps1
• start-openai-tunnel-stdio-plus-local-http.ps1
• start-openai-tunnel-http-plus-local-stdio.ps1

替换占位符前，请将示例复制到代码检出目录之外。切勿提交 Runtime API 密钥、Tunnel ID、Bearer 令牌或私有状态路径。

容器

docker build --build-arg VERSION=dev -t scripthold:dev .

docker run --rm -i \
  --read-only \
  --cap-drop=ALL \
  --security-opt=no-new-privileges \
  --tmpfs /tmp:rw,noexec,nosuid,size=64m \
  --mount type=bind,source=/absolute/project,target=/data \
  scripthold:dev --transport=stdio /data

镜像以非特权 UID/GID 10001 运行。

工具组

TOOLS.md 是包含架构、参数、示例、限制和错误行为的详细公开参考。下表介绍 4.x 工具目录（36 个工具）。从 3.3.6 升级的客户端必须将原有的 8 个 apply 命令迁移到 confirm_verified_operation。

类别	主要工具
文本/文件	read_text_file、read_multiple_files、write_whole_file、edit_file、grep_text_files
确认	confirm_verified_operation — 对任何已准备操作进行一次性批准
多文件变更	patch_package、filesystem_package
目录/状态	list_directory、tree、search_files、get_file_info、fingerprint_paths、verify_state
编码	detect_encoding、convert_encoding、detect_line_endings、change_line_endings、manage_bom、list_encodings
备份	backup_store、backup_delete
源代码智能分析	source_symbols、source_query
Markdown 智能分析	markdown_read、markdown_workspace、markdown_create、markdown_edit
持久化工作	task_run、task_list、task_get、task_logs、task_cancel、deferred_operation
服务	list_allowed_directories、check_for_updates

源代码智能分析

源代码智能分析可帮助 Agent 浏览源代码，而无需运行代码，也无需外部编译器、解析器或语言服务器。使用 source_symbols 配合 digest presentation: "compact" 映射项目文件；默认浏览树状文件大纲（也可请求 presentation: "detailed"，获取旧版大纲 JSON 结构），并检查选定的符号；使用 source_query 进行结构化搜索、查询受支持的项目关系、依赖关系图和已验证的上下文。查找未由结构化符号表示的任意文本或代码行为时，请使用 grep_text_files。

对于不受支持或含义模糊的关系，系统会拒绝处理，而不会猜测。Markdown 文件有专用的文档工具。请查看生成的语言能力矩阵，了解可用的源代码提供程序和分析覆盖范围。

Markdown 文档

Markdown 文件使用专用工具，而非 Source Intelligence 提供程序。使用 markdown_read 读取文档，或使用只读工具 markdown_workspace 检查文件之间的链接和关系。

要更改文档，请使用 markdown_edit 准备预览（新建文件则使用 markdown_create），检查拟议内容，然后将其 previewId 传递给 confirm_verified_operation。不安全、存在冲突或已过时的更改会被拒绝，而不会被静默重写。

示例和具体操作形式请参阅 Markdown 工具参考。有关 Markdown 语义、支持的编码以及 Marksplice 集成边界，请参阅 Markdown Intelligence。

安全模型

• 文件访问仅限于经过规范路径验证后明确授权的根目录。
• 符号链接、junction、重解析点、别名和缺失路径导致的越界访问均会被拒绝。
• 编码检测依据字节和解码后内容的证据，绝不依据文件名或扩展名。
• 修改会在提交前暂存并重新验证；最初不存在的目标路径采用 no-replace 语义。
• 预览／应用工作流会将已批准操作绑定到一次性能力，因此无法在应用时更改修改参数。
• 多文件修改不保证事务性回滚；如适用，失败时会报告已提交／未更改／状态未知。
• 可选的备份存储是位于公共根目录之外的独立受保护权限域。
• 默认禁用 task_run 执行。Shell 和脚本执行需要明确授权；HTTP 执行还需要额外启用 HTTP 执行。
• 默认情况下，HTTP 经过身份验证且仅限环回地址。

当前的架构边界概述见 架构。

关键配置

大多数安装只需设置少量环境变量：

变量	用途	默认值
MCP_TRANSPORT	stdio 或 streamable-http	stdio
MCP_DEFAULT_ENCODING	新建文本文件的编码	utf-8
MCP_HTTP_ADDR	HTTP 监听地址	127.0.0.1:8765
MCP_HTTP_TOKEN_FILE / MCP_HTTP_TOKEN	互斥的 bearer token 来源	未设置
MCP_HTTP_ALLOW_NON_LOOPBACK	满足其他安全要求时，允许绑定非环回地址	禁用
MCP_BACKUP_STORE_DIR	启用持久化备份存储	未设置
MCP_BACKUP_DEFAULT_POLICY	适用的、与审批绑定的修改操作的默认持久化备份策略	disabled
MCP_TASK_STORE_DIR	启用持久化任务存储	未设置
MCP_DEFERRED_STORE_DIR	为符合条件的长时间运行只读调用启用持久化所有权	未设置
MCP_ENABLE_RUN_SCRIPT	允许 task_run kind=script	禁用
MCP_ENABLE_SHELL	允许 task_run kind=shell	禁用
MCP_ENABLE_EXECUTION	允许这两种任务类型	禁用
MCP_HTTP_ENABLE_EXECUTION	HTTP 执行的额外门控	禁用

详细限制和子系统特定选项请参阅其对应文档：TOOLS.md、持久化任务和 HTTP 安全。

文档

使用文档指南，按任务查找说明，无论你是在配置客户端、选择工具、保护部署安全，还是为项目做贡献。

• 使用服务：工具参考、HTTP 安全和持久化任务。
• 了解和更改项目：架构、贡献指南和路线图。
• 发行历史：更新日志，版本专属步骤见迁移指南。

开发

所需的 Go 版本在 go.mod 中声明。

go mod verify
go test ./...
golangci-lint run ./...
go build -o scripthold ./cmd/scripthold

提交更改前，请参阅 CONTRIBUTING.md。

许可证

GPL-3.0 — 参见 LICENSE。