# 远程 MCP 物理上读不到员工本地文件 — 设计 MCP 工具前必须先想清楚传输路径

## 触发场景

为 internal-app-platform PRD 设计部署链路时，连续 N 轮迭代后才发现：远程 MCP server 部署在 FFOA 服务器侧，**收到的 tool call 参数只能是字符串/JSON**——拿不到员工电脑文件系统。

但前几版 PRD 一直在写：
- "MCP `deploy(dir=本地路径)` 工具在员工本地目录执行 staging"
- "MCP 工具内置 git add + 文件名硬拒 + 内容扫描"
- "5 秒预览后回车继续"

这些描述全部隐含 "MCP 能直接访问员工 fs"——但**这是物理上不成立的假设**。审视架构图时才看出来：MCP server 跟员工电脑之间只有 HTTP/SSE 一条线，文件流不在这条线上。

## 修正动作

把"文件传输"从 MCP 的职责剥出来，明确：
- MCP **只颁发凭据 + 编排**
- 文件传输走 **git push 协议**（员工本地 Claude Code 用 Bash tool 执行）
- staging 责任**下沉到 Gitea pre-receive hook**（服务端唯一真相源）

最终架构干净了：MCP 是胶水层，git 是文件管道，hook 是安全网。

## 可复用经验

**设计任何"远程 MCP server + 本地 Claude Code 协作"的工具集前，先在白板上画一张物理拓扑图**：
- 哪些组件能访问员工本地文件？（Claude Code 本身 / 它自己的 Read/Bash/Edit 工具）
- 哪些组件**不能**？（远程 MCP / 远程 API）
- 文件要跨越这条边界时走什么协议？

**反模式**：把 MCP 工具描述成 "deploy(dir=...)" 之类参数——这暗示"工具会去读 dir 内容"。物理上不行。应改成 "deploy_prepare() 返回凭据，由 Claude Code 自己拿凭据传文件"。

**正确套路**：
- 文件少量 / 结构化 → MCP 参数直接传（base64 / JSON）
- 文件大量 / 二进制 → 走原生协议（git push / S3 presigned URL / etc.），MCP 只发凭据
- 客户端需要执行 shell → MCP 返回**结构化操作描述**（不返回 shell 命令字符串，杜绝注入面）

## 适用范围

未来设计任何远程 MCP 工具时强制 review。也适用于 OpenAI Function Calling、自研 agent tool 等"工具运行在 server 端、文件在 client 端"的拓扑。