MCP 官方参考服务器 v2.3.0 升级实操：用 --read-only、--confine-roots 与 --allowed-hosts 给 Agent 的文件与联网工具加边界

# 查 npm 侧的实际版本（filesystem）
npm view @modelcontextprotocol/server-filesystem version
npm view @modelcontextprotocol/server-memory version

# 查 PyPI 侧的实际版本（fetch / git / time）
python -m pip index versions mcp-server-fetch
python -m pip show mcp-server-fetch

# 备份客户端配置后再改（路径按你的客户端调整）
cp claude_desktop_config.json claude_desktop_config.json.bak

# 用 uvx 拉起时显式指定这一版，便于复现
uvx [email protected] --help

# 命令行直跑（旗标可以放在目录前后任意位置）
mcp-server-filesystem --read-only /path/to/project /path/to/docs

# Claude Desktop 的 claude_desktop_config.json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "--read-only",
        "/path/to/project"
      ]
    }
  }
}

# 验收：让 Agent 列出工具，再试着写一次
# 预期：工具表里没有 write_file / edit_file，写入请求报未知工具

# 参考目录只读、工作目录可写（可重复加多个只读目录）
mcp-server-filesystem --read-only-dir /path/to/reference /path/to/workspace

# 客户端配置里的等价写法
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "--read-only-dir", "/path/to/reference",
        "/path/to/workspace"
      ]
    }
  }
}

# 验收 1：往受保护目录写文件，应被拒绝并给出目录名
# 验收 2：往工作目录写文件，应正常成功
# 验收 3：list_allowed_directory 之后会列出只读目录

# 把 Roots 关在启动目录里
mcp-server-filesystem --confine-roots /path/to/project /path/to/docs

# 三个开关叠加的典型生产写法
mcp-server-filesystem --read-only --confine-roots /path/to/project

# 验收：用支持 Roots 的旧协议客户端发一个越界 Root
# 预期：越界 Root 被忽略并记录；全部 Root 都无效时访问被收回

# 用 uvx 启动，只放行两个域
{
  "mcpServers": {
    "fetch": {
      "command": "uvx",
      "args": [
        "mcp-server-fetch",
        "--allowed-hosts", "docs.python.org", "*.wikipedia.org"
      ],
      "env": { "FETCH_TIMEOUT_MS": "60000" }
    }
  }
}

# 或用旗标设置全局超时（--allowed-hosts 可重复写）
uvx mcp-server-fetch --allowed-hosts docs.python.org --timeout-ms=60000

# 单次调用覆盖全局值（工具参数，单位毫秒）
# fetch(url="https://docs.python.org/3/", timeout_ms=5000)

# 验收：请求白名单外的主机，应被拒绝并报出被拒的主机名
# 验收：跳转链里出现白名单外的主机，同样应被拒绝

# 升级 PyPI 三个包
python -m pip install --upgrade mcp-server-fetch mcp-server-git mcp-server-time

# 升级 npm 侧（若用全局安装或锁文件，按项目方式执行）
npm install @modelcontextprotocol/[email protected]

# 确认依赖修复落在锁文件里
npm ls minimatch qs

# filesystem 本版还新增了 file:// 资源模板
# 用 resources/read 读 file:///path/to/project/README.md
# 注意 resources/list 刻意返回空，服务器不枚举磁盘

# 回归清单（逐条在客户端里跑一次）
# 1. tools/list 里写工具是否按预期消失
# 2. 受保护目录写入是否被拒
# 3. 白名单外主机与越界重定向是否被拒
# 4. git_merge / git_remote / get_time_ago 是否可用
# 5. 原有读取与目录列举是否正常