一句话定位

把独立的 local-shell-mcp MCP 服务（提供 shell、文件、浏览器自动化、远程机器、Agent Skills 等工具）桥接到 DeepSeek Harness 的 Web 客户端，并在对话窗口里嵌入一个实时协作的 Live Workspace 面板。

核心能力

• 把上游 MCP 服务的全部工具按 mcp__lsm__* 命名空间自动注册到 DSH 工具列表，模型可直接调用
• 把上游服务声明的指令段作为系统提示的一部分注入，模型能感知当前可用的工具与上下文
• 在 DSH 会话面板的"Live Workspace"标签里渲染一个嵌入式实时工作台，支持查看终端、文件、任务进度并向模型发问
• 每个 DSH 会话独享一条上游 MCP 连接，会话结束自动断开，并带心跳和断线重连
• 监听上游 tools/list_changed 通知，热更新本地工具列表而无需重启插件
• 上游返回的图片、音频、resource 等非文本内容会被丢弃并替换为占位说明，避免污染对话上下文

技术实现

• 语言: JavaScript（Node.js，ESM）
• 关键依赖: @modelcontextprotocol/sdk（MCP 客户端）、zod（结果校验）、node:crypto、node:fs/promises
• 架构模式: DSH bundle patch + 客户端注入双端结构；服务端通过 tools / systemPrompt / webServer / agents 四个钩子把 MCP 桥接进来，客户端通过 slots / sessions / conversation 在对话面板里挂载 React 视图
• 入口文件: dsh/index.js（服务侧桥接）、dsh/client.js（客户端 React 视图）、cordis.patch.yml（注入声明）

适用场景

当你已经在本机或容器里跑着 local-shell-mcp 服务，想让 DeepSeek Harness 直接调用它来做命令行、文件操作、浏览器自动化、远程机器控制时，装上这个插件就能把整套工具和实时工作台搬进 DSH 网页。多账号协作或需要把模型执行过程可视化展示时尤其方便。

前置依赖与兼容性

安装方式

dsh plugin --profile web add github:fwerkor/local-shell-mcp

配置项

本插件无需普通用户手工配置；以下高级字段在 cordis.patch.yml 的 config 下生效（也可通过同名 DSH_LSM_* 环境变量覆盖默认值）：

环境变量快捷覆盖：DSH_LSM_MCP_URL / DSH_LSM_BROWSER_URL / DSH_LSM_AUTHORIZATION / DSH_LSM_TOOL_CALL_TIMEOUT_MS / DSH_LSM_KEEPALIVE_INTERVAL_MS。

常见问题

Q: 装上之后 DSH 里能看到什么？

A: 对话面板里会多出一个"Live Workspace"标签，里面是 local-shell-mcp 的实时协作界面（终端、文件、任务进度等）。模型可用的工具列表也会按 mcp__lsm__ 前缀自动追加上游声明的全部工具。

Q: 必须先启动 local-shell-mcp 服务吗？

A: 是的。本插件只是桥接，不内置 MCP 服务，依赖 localhost:8765（默认）的上游 MCP 服务。可以通过 DSH_LSM_MCP_URL 环境变量或 cordis.patch.yml 里的 url 字段改成别的地址。

Q: 每个 DSH 会话是独立的吗？

A: 是的。插件为每个 DSH Session 单独建立一条上游 MCP 连接，并用专属的会话亲和请求头标识，最多同时维护 64 个活跃会话连接，超出时会按最近使用时间淘汰已结束的会话。

Q: 工具结果里包含图片或音频怎么办？

A: 插件只把文本片段转发给模型，图片、音频、resource 类型的内容会被替换成"[image: …, content discarded]"这类占位说明，避免大块二进制塞进对话上下文。

Q: 需要给本地服务加 Bearer Token 吗？

A: 可选。在 DSH 进程环境里设置 DSH_LSM_AUTHORIZATION 即可透传到上游 MCP 请求头；也可以在 cordis.patch.yml 的 headers 字段直接写死。

Q: 上游 MCP 工具列表会变化时，DSH 端会自动更新吗？

A: 会。插件订阅了上游的 tools/list_changed 通知，发现变更会重新拉取并热更新本地的 mcp__lsm__* 工具列表，不需要重启插件或重连会话。

Q: Live Workspace 加载不出来怎么办？

A: 先确认上游 MCP 服务可达并且 live_workspace_reconnect 工具返回了凭证。如果上游是远程 HTTPS 而 DSH 在浏览器里访问，还需要正确设置 DSH_LSM_BROWSER_URL，否则 iframe 跨域或协议不匹配会失败。

上手难度

入门 — 安装一行命令即可，主要工作是先在本地启动一个能访问的 local-shell-mcp MCP 服务，DSH 端无需写额外配置。

已知问题与限制

• 上游声明的工具若要求"基于任务"（task-based）执行模式，本桥接会直接抛错并不调用，因为当前实现只支持普通请求/响应式的工具调用
• 同时活跃的 DSH 会话连接上限为 64；当 64 个会话都还活跃且仍想接入新会话时，会直接抛出"too many live sessions"错误而不是排队等待
• 上游返回的图片、音频、resource_link 等非文本内容会被丢弃，模型拿到的只是占位说明，无法直接查看或转交
• cordis.patch.yml 的 browserUrl 不能携带用户名密码，否则配置校验阶段就会报错
• 工具名做了长度与字符归一化（mcp__lsm__ 前缀 + 截断 + 哈希），过长的上游工具名在 DSH 端看到的名称会和原始名不同

---

local-shell-mcp gives ChatGPT Developer Mode and other MCP clients controlled access to a real execution environment. It exposes a dedicated workspace with shell, persistent shell, filesystem, search, patch, Playwright, audit, durable logical sessions with optional Goal plans, public file links, and outbound remote-worker access. Git is handled through ordinary shell commands instead of a parallel wrapper API.

Runtime: Docker / VS Code extension / binary / Python / stdio
  -> exposure: localhost, HTTPS proxy/tunnel, or stdio pipe
  -> client: ChatGPT or another MCP client
  -> controlled workspace at /workspace or configured root
  -> optional remote workers connected over outbound HTTP(S)

The intended safety boundary is the container or VM, not the host.

Why use it

Quick start

Install the official launcher or Python package when you want a host runtime:

npx local-shell-mcp --help
pipx install local-shell-mcp
lsm --help

The npm and Python distributions both expose local-shell-mcp; installed packages also expose lsm as the short command. The npm distribution is only a verified launcher for the matching standalone release binary, not a second server implementation.

Clone the repository and prepare configuration:

git clone https://github.com/fwerkor/local-shell-mcp.git
cd local-shell-mcp
cp .env.example .env

Set at least these values in .env:

LOCAL_SHELL_MCP_PUBLIC_BASE_URL=https://your-public-host.example.com
LOCAL_SHELL_MCP_AUTH_MODE=oauth
LOCAL_SHELL_MCP_OAUTH_ADMIN_PIN=change-me-long-random-pin
LOCAL_SHELL_MCP_OAUTH_JWT_SECRET=change-me-64-hex-random-secret
CLOUDFLARE_TUNNEL_TOKEN=

Start the server:

mkdir -p workspaces/default
docker compose up -d
curl -i http://127.0.0.1:8765/healthz

Start the bundled Cloudflare Tunnel sidecar when you need public HTTPS access:

docker compose --profile tunnel up -d

The public MCP endpoint is:

https://your-public-host.example.com/mcp

Full setup instructions are in the documentation. Runtime choices are documented separately from client connections.

Human interface

The service includes two compatible human interfaces backed by the same authenticated API and state:

• Web UI is a native browser dashboard for system health, machines, workloads, recent MCP activity, and alerts.
• OpenTUI is the full terminal-oriented interface with Dashboard, Files, Terminals, Remotes, and Audit screens. It remains available in the browser as a selectable console and as the native local-shell-mcp tui command.

Open the browser interface on the service origin:

http://127.0.0.1:8765/ui

The OAuth screen lets you choose Web UI or OpenTUI before authorization. After login, switch modes at any time from the interface selector. Native Web UI routes use URL hashes such as #/overview and #/console, so a selected mode or page can be bookmarked. The OpenTUI console retains the existing authenticated xterm.js/PTY transport, mouse interaction, automatic resizing, reconnects, fullscreen mode, and mobile shortcut row.

Standalone release executables embed the native OpenTUI runtime, while Docker images provide it inside the image. Start the service, then launch it without a human login prompt:

local-shell-mcp tui

Files remains an LSM-native three-pane file manager inside OpenTUI for local and remote machines. It renders bounded PNG/JPEG/GIF/WebP thumbnails and provides consistent file operations through the shared service API. Manual actions entered through either human interface are excluded from the MCP audit log; Activity, Audit, and the terminal audit rail show model-originated MCP activity.

See the human interface guide.

ChatGPT setup

For full shell, filesystem, remote-worker, and Playwright tools, use ChatGPT Developer Mode or another full MCP client. ChatGPT is a client connection; choose and start a runtime first.

session_manage provides one durable logical task context for agent work. A Session is deliberately independent of machine and working directory: it stores the task objective, semantic progress reports, recent execution Activity, and an optional Plan. session_id is the only durable task identity. To continue work in another ChatGPT conversation, the user explicitly passes the existing session_id, and the new agent calls session_manage(action="resume", session_id=...). Agents do not list or auto-select Sessions from other conversations. They should report the active session_id after start/resume, at meaningful progress checkpoints, and before ending a turn, while using session_manage(action="report", session_id=...) for semantic progress rather than copying every tool result into the summary. Ordinary tools receive the same task identity as logical_session_id.

When the client supports MCP Apps, workspace_open(session_id=...) opens the execution view for the explicitly selected Session as a floating MCP App and can expand to fullscreen. The v3 name open_live_workspace remains a hidden, non-enumerated compatibility alias for ChatGPT clients with a cached recipient; new integrations see and use only workspace_open. The Live Workspace is a reconnectable viewer and collaboration surface, not the owner of task state: closing it or reconnecting MCP does not discard Session progress, Activity, or its Plan. Ordinary MCP tools remain the execution API, while the app adds live operational activity, persistent terminals, file/diff inspection, jobs, remotes, audit data, and the active Session id. Clients that do not render MCP Apps continue to use the normal tool surface unchanged.

plan_manage(session_id=...) optionally enables Goal mode on that explicit Session for substantial multi-step work. An active Plan is the goal: its steps can be revised as execution changes and, while a Live Workspace is attached, the app can request continuation after 15 minutes without agent tool activity. Automatic continuation is capped at 10 continuation attempts (accepted or rejected) and resumes the same Session before continuing. Blocked, completed, and cancelled Plan statuses are never nudged; an active Plan whose steps are all completed or skipped remains eligible for cleanup continuation so a resumed agent can call plan_manage(action="finish"). A Session does not require a Plan.

1. Expose the server through HTTPS.
2. Keep OAuth enabled.
3. Add the MCP endpoint: https://your-public-host.example.com/mcp.
4. Complete the OAuth authorization flow.
5. Start with a bounded task and inspect the audit log when needed.

Read the dedicated ChatGPT connector guide.

DeepSeek Harness plugin

The repository root is also a DSH plugin bundle. With a normal LSM HTTP/MCP service running on the same host, install it directly into a DSH profile:

dsh plugin --profile web add 'github:fwerkor/local-shell-mcp#main'

The bundle uses an LSM-aware Streamable HTTP bridge and keeps the complete LSM tool surface, including remote_manage, remote_transfer, browser tools, and Dynamic MCP tools. Each DSH Session receives a stable v4 logical-session identity, so its Logical Session, active run, Activity, and native Live Workspace view stay isolated from other DSH conversations and survive DSH-side MCP transport recreation. DSH sees model tools under the normal mcp__lsm__* namespace. For production, pin the Git spec to a reviewed release or commit.

See the DeepSeek Harness integration guide.

VS Code extension runtime

Release assets include local-shell-mcp-<version>.vsix. The extension is a runtime launcher for the current VS Code workspace. It starts the same server, checks /healthz, copies the MCP URL, and copies a ready-to-paste ChatGPT setup prompt.

Basic flow:

Install executable -> install VSIX -> open a workspace -> Start Server -> copy MCP URL

For public ChatGPT access, expose the local server through an HTTPS tunnel and set local-shell-mcp.publicBaseUrl in VS Code settings. Keep local-shell-mcp.allowFullContainer disabled for direct host usage; enable it only inside disposable containers or VMs.

Remote workers

Remote worker mode is enabled by default. Create a one-time invite on the control server, paste the generated command on a remote machine, then use the normal tools with their optional machine argument. Only worker administration retains remote_* names.

This is intended for:

• HPC login nodes or compute nodes behind firewalls.
• NPU/GPU servers without inbound connectivity.
• Lab machines that can make outbound HTTPS requests.
• Temporary build hosts or remote test environments.

See the remote workers guide.

Agent Skills

Skills are discovered from three ordered sources: project-level /workspace/.agents/skills, the LSM-managed /workspace/.local-shell-mcp/agent_config/skills, and global ~/.config/agents/skills. Higher-priority sources override lower-priority Skills with the same name, and symlinked Skill directories and files are supported.

This makes the universal Skills CLI layout work directly, for example npx skills add owner/repo --agent universal -y. Use skill_list to discover installed Skills, skill_load to load one instruction set, and skill_read to read a related file by the returned Skill-relative path. Changes are detected on the next call; no per-Skill MCP tools are registered and no client reconnect is required.

See the Agent Skills guide.

Tool surface

The public MCP surface includes:

• Live Workspace: workspace_open opens the reconnectable MCP App for the current logical Session.
• Shell and jobs: run_shell, run_python, persistent shell_*, and tracked job_* tools. Use run_shell for Git CLI operations.
• Filesystem: file_list, file_tree, file_glob, file_grep, unified file_read, native-vision image_view, file_write, unified file_edit, file_delete, and file_patch.
• Transfer: remote_transfer for files or directories across controller and worker endpoints.
• Dynamic MCP: mcp_manage, mcp_tool_search, mcp_tool_inspect, and mcp_tool_call. External tools are discovered progressively and never expand LSM's own tools/list surface.
• Browser: persistent high-level browser_session, browser_snapshot, and browser_act; browser_run_script is the low-level Playwright escape hatch.
• File links: link_create, link_list, link_revoke.
• Remote workers: remote_manage with invite, list, rename, and revoke actions; normal execution tools accept optional machine.
• Agent Skills: skill_list, skill_load, skill_read.
• Sessions: session_manage for durable task context, progress handoff, agent-run takeover, and cross-run inheritance.
• Planning: plan_manage for optional Session-owned Goal mode and automatic continuation.
• Diagnostics: environment_get (including version information), secret_scan, and audit_tail.

The detailed tool reference, including purpose, inputs, returns, combinations, and notes for every tool, is available in the docs.

Related projects

The following independently maintained projects explore adjacent session and orchestration models around LSM:

• rijuyuezhu/local-shell-mcp uses a different, execution-oriented session model that binds workspace context and related resources to explicit sessions. It has its own tool surface and release lifecycle.
• DongYaoZe/localshell-web-supervisor is a local reliability and orchestration layer for browser-driven agents using Local Shell MCP. It supervises replaceable browser workers while reconciling durable LSM sessions, Goals/jobs, and actual workspace/Git state, with guarded lease, handoff, takeover, and recovery flows. It is not part of the LSM runtime or release lifecycle.

Security model

This project intentionally exposes powerful tools. Treat the connected model as having control of the container or VM.

Default protections include:

• Workspace scoping to /workspace unless full-container mode is explicitly enabled.
• Command timeouts, output limits, and concurrency limits.
• Default command/path denylists for host-control fragments.
• Shell subprocess environment filtering for service-side secrets.
• Dynamic stdio MCP servers inherit only a minimal OS environment plus explicitly configured per-server variables; configured environment/header values are stored in a mode-0600 state file and redacted from tool results and Audit arguments.
• Audit logs at /workspace/.local-shell-mcp/audit.jsonl.
• Secret scanning helpers before commits and pushes.
• Tokenized file links with TTL/download limits and revocation.

Hard rules:

1. Do not mount /var/run/docker.sock.
2. Do not mount the host root filesystem.
3. Do not expose the service with LOCAL_SHELL_MCP_AUTH_MODE=none on a public network.
4. Do not put long-lived credentials in environment variables visible to the model.
5. Prefer single-repository deploy keys or short-lived tokens.
6. Run the service in a disposable container or VM.
7. Treat the local-shell-mcp-credentials Docker volume as sensitive.

For vulnerability reporting, read SECURITY.md.

Configuration

Copy .env.example for the standard setup. The configuration reference documents every environment variable and the optional YAML format for advanced deployments.

Important options:

Development

Install development dependencies and run checks:

python -m venv .venv
. .venv/bin/activate
pip install -e '.[dev,docs]'
ruff check .
pytest -q
mkdocs build --strict

Build the VS Code extension:

npm --prefix vscode-extension install
npm --prefix vscode-extension run compile

Contribution workflow is documented in CONTRIBUTING.md.

Project documents

• Documentation site
• Contributing guide
• Security policy
• Code of conduct
• Support guide
• OAuth setup
• License