# Local File MCP

Local File MCP 是面向本地开发、科研和数据分析的受控文件/进程 MCP 服务。

稳定版本：**V1.5.0**。

## V1.5 Agent Runtime

V1.5 在既有 RWX/Exec capability 之上加入 Host-driven Coding Agent：persistent Task/Plan、managed Git worktree、结构化 patch/diff、named verification profile、acceptance review、crash recovery 与 terminal workspace cleanup。Agent 通过 canonical Task Context / `next_actions` 驱动 PEVC Loop，不获得 arbitrary shell、raw Git、source-checkout write 或自行扩权能力。

V1.5 暴露 16 个高层 `agent_*` Tool；与既有 29 个 Tool 合计 **45 个 Tool**。详见 `docs/agent-runtime.md`、`docs/agent-protocol.md` 与 `docs/tools.md`。

## Control Center

Control Center 在 V1.6 development 中提供 Service / Agent Tasks / Permissions / Execution / Policy / Diagnostics / Audit 七页、zh-CN / en-US、配置事务与 Windows 打包。Agent Tasks 读取 persistent Agent state，自动派生项目显示名，并只通过既有 fail-closed Agent Protocol 执行受门禁的 Workspace cleanup；不新增 Agent schema 或 MCP Tool。源码启动：`scripts/start_control_center.ps1`；构建：`scripts/build_control_center.ps1`。详见 `docs/control_center.md`。

## 能力

- 16 个只读 Tool：目录、文本、CSV、Excel、PDF、图片、PyTorch checkpoint/tensor。
- V1.1/V1.2 mutation Tool：安全创建、替换、追加、复制、移动、trash、删除、恢复与审计查询。
- V1.3 `exec_command`：显式授权、受审计的本地 CLI 执行。
- V1.5 Agent Protocol：16 个高层 Task/Plan/Workspace/Verification/Review/Lifecycle Tool。
- 当前 MCP 共 45 个 Tool。

## V1.3 Exec

`exec_command(command, cwd, timeout=30, max_output_chars=100000)` 只启动一个直接进程，不经过 shell。

执行策略：
- `cwd` 必须同时拥有 read/write 权限，deny rule 优先。
- executable allowlist 来自 `config/execution.toml`，服务启动时逐项解析为固定可信路径；任一条目不可用即明确报错并拒绝启动。
- `cmd.exe`、PowerShell、pwsh 不属于 V1.3 direct-process 策略。
- stdin 关闭；stdout/stderr 分别限制保留长度。
- Windows 进程先以 `CREATE_SUSPENDED` 创建，加入 Job Object 后才恢复主线程，消除 create→assign 逃逸窗口。
- timeout 会终止进程树；正常返回时也清理遗留 descendant。
- 所有 attempt/success/failure/timeout/permission rejection 均进入 MutationAudit。

示例授权工具：Python、pytest、Git、nvidia-smi、Pandoc。Pandoc 当前配置为：

```text
D:\Pandoc\Pandoc\pandoc.exe
```

授权后可直接执行：

```text
pandoc input.md -o output.html
```

V1.3 **不是 filesystem sandbox**。被授权程序及其子进程以 MCP 服务账户的 OS 权限运行，因此在调用存活期间可能访问 allowed roots 之外、但该账户本身可访问的资源。`permissions.toml` 对 `cwd` 做入口授权，不对已启动程序做文件系统隔离。

## 配置

```text
config/permissions.toml        文件系统 read/write/deny 策略
config/execution.toml          exec executable allowlist
config/agent_runtime.toml      Agent managed workspace root（本机配置）
config/verification.toml       named verification profiles（本机配置）
config/oauth.toml              OAuth 参数
config/secrets.toml            本地敏感配置
data/auth/                     OAuth 与 audit 持久化数据
data/control_center/           配置 revision 等本地 control-plane 状态
data/agent_runtime/            Agent canonical task state
```

`config/`、`data/auth/`、`data/control_center/` 与 `data/agent_runtime/` 自动拒绝普通文件 Tool 访问。

## 运行

本地 STDIO：

```cmd
cd /d D:\MCP
.venv\Scripts\python.exe server.py
```

生产 HTTP：

```text
https://mcp.liferoad.cloud/mcp
```

Windows 登录后由 Scheduled Task → `scripts/start_mcp.ps1` → `server_http.py` 启动，并由 supervisor/Cloudflare Tunnel 提供恢复与公网连接。长期 supervisor 每次启动都会回收已存在的旧 Local File MCP listener 后再启动新的 `server_http.py`，因此 Stop/Start Scheduled Task 会真正加载最新代码；`-Once` 健康检查不会执行该回收。

## 测试

```cmd
cd /d D:\MCP
.venv\Scripts\python.exe -m pytest -q
```

V1.5.0 冻结验收：完整 `tests/` 采用无重叠分片覆盖，`643 passed, 8 skipped, 1 warning`；单次全量调用仍可能触发 MCP connector TaskGroup transport 异常，因此冻结结论只使用拿到真实 pytest exit code 的分片结果。唯一 warning 为既有 PyTorch/NumPy 环境项。

## 文档

- `docs/tools.md`：Tool 与调用边界。
- `docs/architecture.md`：V1.3 架构和安全模型。
- `docs/control_center.md`：V1.4 Control Center、双语、诊断与 Windows EXE 发行说明。
- `logs/CHANGELOG.md`：稳定版本与开发变化。