# MCP 入门案例：文件操作 Server

一个最小可运行的 MCP（Model Context Protocol）Server，用 Python 官方 v2 SDK 写成，
暴露三个文件操作工具，供 MCP Inspector 调试验证。

## MCP 三层架构速记

```
┌──────────────┐   stdio/HTTP   ┌──────────┐   子进程   ┌──────────────────┐
│   Host       │◀─────────────▶│  Client  │◀──────────▶│  Server (本项目)  │
│ Claude Desktop│               │(Host 内部)│  stdin/stdout│  filesystem.py   │
│  Inspector   │               │          │            │  暴露 Tools/...   │
└──────────────┘               └──────────┘            └──────────────────┘
```

- **Host**：跑大模型的应用（Claude Desktop、Inspector 等），内部管理 Client。
- **Client**：与某个 Server 建立 1:1 连接，按 MCP 协议收发消息。
- **Server**：你写的程序，向模型暴露三类能力。本例只用了最常用的 **Tool**：
  - `read_file` / `write_file` / `list_directory`

## 环境与安装

需要 Python ≥ 3.10（本机用 3.13）和 [uv](https://docs.astral.sh/uv/)。依赖已写在 `pyproject.toml`：

```bash
uv sync          # 安装依赖、创建虚拟环境
```

核心依赖是 `mcp[cli]>=2.0.0`（v2 用 `MCPServer` 取代了旧版 `FastMCP`）。

## 用 MCP Inspector 调试

Inspector 是官方图形化工具，能直接看到模型/客户端如何调用你的工具，无需配置 Claude Desktop。

```bash
uv run mcp dev servers/filesystem.py
```

启动后会打印一个本地网址（默认 http://127.0.0.1:6274 ），浏览器打开即可。在左侧
“Tools” 里能看到三个工具，点开 -> 填参数 -> 点 “Run Tool” 看返回。

建议按这个顺序试一遍，体会完整流程：

1. `list_directory`（path 留空走默认 `.`）-> 应看到 `hello.txt`
2. `read_file`，path 填 `hello.txt` -> 读到示例内容
3. `write_file`，path 填 `test.txt`、content 随便写 -> 提示写入成功
4. 再 `list_directory` -> 应看到新增的 `test.txt`
5. 安全测试：`read_file` path 填 `../secret` -> 应被拒绝（沙箱拦截路径穿越）

## 程序化验证（不走 Inspector）

不启动 Inspector，用 v2 内存 `Client` 直接连 server 对象跑一遍工具，适合快速回归：

```bash
uv run python tests/test_filesystem.py
# 或：uv run python -m tests.test_filesystem
```

## 目录结构

```
mcp-test/
├── pyproject.toml          # uv 项目 + 依赖声明
├── uv.lock                 # 依赖锁文件（提交进 git 保证可复现）
├── servers/
│   └── filesystem.py       # MCP Server：三个文件操作 Tool
├── tests/
│   └── test_filesystem.py  # 冒烟测试（内存 Client 直连）
├── workspace/              # 沙箱目录，所有文件操作只能在此内进行
│   └── hello.txt           # 示例文件（运行时产生的文件被 .gitignore 忽略）
└── README.md
```

所有工具的路径都解析到 `workspace/` 之内，并用 `resolve()` + 父目录校验拦截
`../` 之类的路径穿越。这是 MCP Server 编写的安全要点：**永远校验模型传进来的路径**。

## 关键代码点

- `from mcp.server import MCPServer` - v2 的入口（不是旧版 `mcp.server.fastmcp.FastMCP`）
- `@mcp.tool()` 装饰一个普通函数 - 函数名、docstring、类型注解就是工具的全部元数据
- `if __name__ == "__main__": mcp.run()` - 无参数即 stdio 传输；守卫不可省，
  因为 `mcp dev` 会先 `import` 本文件
- 调试走 `logging`（输出到 stderr）- **stdio 模式下 stdout 是协议链路，不能用 print**

## 下一步

把 Server 接入 Claude Desktop，在真实对话里用上它：

```bash
uv run mcp install servers/filesystem.py --name "filesystem"
```

这会自动写入 Claude Desktop 的 `claude_desktop_config.json`，重启 Desktop 后即可在对话中
让模型读写 `workspace/` 里的文件。

## 参考文档

- MCP 协议官网：https://modelcontextprotocol.io
- Python SDK 文档：https://py.sdk.modelcontextprotocol.io
- Inspector：https://github.com/modelcontextprotocol/inspector