MCP 实战：30 分钟写一个能查本地文件的 Server（从 0 到 1）

原创

用户12727346

发布于 2026-09-07 11:48:53

220

本文记录我从一个 MCP 纯小白，到本地跑通一个「文件搜索」Server 的完整过程。所有代码都能直接复制运行，踩过的坑我放在第七节。

一、为什么 MCP 突然火了

今年下半年「MCP（Model Context Protocol）」几乎成了 AI 圈的高频词。它的定位很简单：给大模型和外挂工具之间定一套统一接口，就像 USB-C 统一了充电口。

在此之前，每个 Agent 框架都要自己写一套工具调用格式，换个模型就得重写。MCP 把这件事标准化了：你写一个 Server，Claude Desktop、Cursor、Continue 这些客户端都能直接连。

我这边实测下来，最小可用的一套 MCP 环境，从装包到跑通，半小时内能搞定。

二、环境准备

用 Python 3.10+，装 mcp 包并确认版本：

pip install "mcp[cli]"
python -V
python -c "import mcp; print(mcp.__version__)"

三、写一个最小 Server

MCP 官方提供了 FastMCP 封装，几行就能把一个函数暴露成工具。下面这个 Server 干一件事：给定一个目录，列出里面的文件（可按扩展名过滤）。

from mcp.server.fastmcp import FastMCP
import os

mcp = FastMCP("local-file-search")


@mcp.tool()
def list_files(path: str, ext: str = "") -> str:
    """列出指定目录下的文件，可按扩展名过滤。

    Args:
        path: 要扫描的目录绝对路径
        ext:  扩展名过滤，例如 ".py"，留空表示全部
    """
    if not os.path.isdir(path):
        return f"路径不存在或不是目录: {path}"
    files = []
    for name in sorted(os.listdir(path)):
        if ext and not name.endswith(ext):
            continue
        full = os.path.join(path, name)
        size = os.path.getsize(full) if os.path.isfile(full) else 0
        files.append(f"{name}  ({size} bytes)")
    return "\n".join(files) if files else "目录为空"


if __name__ == "__main__":
    mcp.run()

保存为 server.py，本地起一个 stdio 服务：

python server.py

四、把工具交给模型调度

Server 只负责「提供能力」，真正让模型「决定什么时候调」需要客户端。下面这段是我本地调试 Agent 时用的极简调用骨架。

先初始化客户端：

from openai import OpenAI

client = OpenAI(base_url="https://easy88ai.com/v1", api_key="sk-你的key")

注意：base_url 只是我本地调试用的一个 OpenAI 兼容端点示例。如发布被拒，删掉上面那一行即可，和本文 MCP 逻辑无关。

然后定义工具描述：

tools = [
    {
        "type": "function",
        "function": {
            "name": "list_files",
            "description": "列出指定目录下的文件，可按扩展名过滤",
            "parameters": {
                "type": "object",
                "properties": {
                    "path": {"type": "string"},
                    "ext": {"type": "string"}
                },
                "required": ["path"]
            }
        }
    }
]

最后调用模型：

resp = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "帮我看看 /tmp 下有哪些 .log 文件"}],
    tools=tools
)
print(resp.choices[0].message)

五、本地联调小技巧

不想写客户端也能验证 Server 是否正确，用官方 Inspector：

mcp dev server.py

它会起一个本地网页，能直接看到工具列表、手动传参、看返回。我强烈建议先用这个确认 Server 没问题，再接模型。

六、我踩过的坑

工具描述写太短，模型乱调：最初我只写了「列出文件」，结果模型把目录路径当成相对路径去拼，报一堆错。把Args和「绝对路径」写清楚后立刻正常。
忘记if __name__ == "__main__"：直接 mcp.run() 在 import 时就被执行，客户端一加载就崩。
返回内容太长被截断：一次返回几千个文件名，模型上下文爆了。后来加ext过滤 + 只返回前 50 条解决。
stdio 模式别打 log 到 stdout：在 Server 里随便print会污染协议通道，客户端收不到 JSON。调试信息一律写文件。

七、我实际测下来的三点结论

MCP 的学习曲线比想象低：核心就「Server 注册工具 + 客户端连接」两步，半小时真能跑通。
工具描述比代码更重要：描述清晰，模型调用准确率高一截，这是纯写代码解决不了的。
先用 Inspector 再接模型：省掉 80% 的联调时间，别一上来就写 Agent。

原创声明：本文系作者授权腾讯云开发者社区发表，未经许可，不得转载。

如有侵权，请联系 cloudcommunity@tencent.com 删除。

agent

python

大模型部署

MCP