企业官网建设流程全解析

做过 AI 工具集成的朋友应该都有印象：最早让模型去读写本地文件，大家第一反应都是“接一个 REST 接口，用 JSON 传参数”。这个方案不是不能跑，但跑起来以后，维护成本会逐渐失控。我最近在做一个模拟项目 X 的时候，恰好要做“AI 助手把工作区里的文件读一遍、改完再写回去”这类需求，最初按 REST + JSON Schema 做了一版，结果后续改了三次；后来换成 MCP 协议重写文件读写服务，整个过程顺畅到一个下午就完成验收。标题里说“别把时间浪费在写 JSON 上”，倒不是说 JSON 这个格式要被消灭，而是说：你没必要花大量精力去设计接口、维护文档、来回调整字段，MCP 的机制把这些事情变成了协议本身该管的部分。

所以这篇就用“文件读写”这个最小用例，把 MCP 协议到底解决了什么问题、它的能力发现和工具调用机制是怎么运转的、以及在真实落地时会踩哪些坑，完整拆开讲一遍。适合两类人看：一类是被 JSON 接口集成折腾过的后端开发者，另一类是刚准备把 AI 能力接进本地工具链、想知道 MCP 到底是怎么工作的同学。

1. 从 JSON 接口到 MCP：我在文件读写需求里碰到的三次“加码”

很多教程一上来就讲 MCP 多厉害，但你没踩过 JSON 方案的坑，就很难理解它到底好在哪。我先把那次内部演示项目里的真实经历讲清楚。

1.1 第一版：一个 read/write 接口，JSON 其实也能跑

最开始需求很简单：给 AI 一个入口，让它能读某个文件、能写入某个文件。常规做法就是开两个 REST 接口，POST/read_file，传一个 body 进去，大概是这个样子：

{ "path": "/workspace/demo.txt", "encode": "base64", "offset": 0, "limit": 1000 }

返回也是一坨 JSON，里面塞着content、encoding、total_chars之类的字段。单个接口看起来不复杂，麻烦的是配套东西多：你得为它写接口文档、写调用示例，模型侧的调用方还得准备一套 JSON Schema 用来理解参数含义。而且模型不是人，它看不到注释，只能靠字段名和 description 猜。为了让模型不传错，那时候光path这一个字段的描述我就改了四遍：一会儿写“绝对路径”，一会儿又补“不要带引号”，一会儿又解释“目录分隔符请用 /”。

这个过程真正消耗时间的部分，不是写接口本身，而是在“让人理解”和“让模型理解”之间反复对齐。第一版总共花了大概两天，写代码只占半天。

1.2 第二版：当参数开始“联动”，JSON 的描述成本直线上升

需求很快迭代了：AI 不能只知道目标文件路径，它得先看目录里有哪些文件，才能决定读哪个、改哪个。于是又加了一个list_dir接口，返回目录条目数组。看起来只是多一个接口，但模型实际工作时是一连串动作：列目录、读文件、修改、写回。

我很快发现，JSON 方案做“多步联动”会面临一个尴尬问题：每一步之间没有天然的关联机制。假设模型第一步调了list_dir拿到一个文件名report.md，第二步调read_file时，这个report.md和接口请求之间的对应关系完全要靠模型自己的上下文记忆，接口本身是无状态的。

为了缓解，我开始在业务层加东西：定义action字段来区分“读取后修改”“读取后返回原文”，定义session_id来跟踪一次问答过程中产生的多次文件操作。你还得写一层编排逻辑，判断模型上一次拿到的目录快照是否过期。到这一步，JSON 接口已经不单纯在传数据了，它开始被迫承担“描述程序行为”“维护流程状态”的责任，而这恰恰不是 JSON 设计上擅长的事。

1.3 第三版：多工具协同、权限控制、上下文传递，JSON 全面失控

再往后加了写文件时的权限限制：只允许操作/workspace目录下的内容，不允许随意覆盖。这在一个普通 REST 接口里会变成请求头里的 token 校验、中间件的路径白名单、参数校验里的合法性判断，分散在至少三层代码里。

同一时间，AI 那侧还要处理“工具调用结果怎么反馈给主对话”的问题：读了一个超大文件，返回内容太多会撑爆上下文；写文件失败，返回的错误还要能被模型理解，自动纠错重试。这些逻辑如果都放在 JSON 接口里，等于是拿业务代码去弥补接口设计本身的缺陷。到第三版的时候，光维护接口文档和字段定义就已经占了我三分之一的时间。

那段时间我最大的感受是：JSON 是一个很优秀的数据交换格式，但它不该承载工具调用的语义层。工具调用需要的不是“你给我一段结构化数据”，而是“你告诉我你现在有什么能力、需要什么参数、我该怎么正确调用你”。这些东西让每个业务方各自发明一套字段去描述，迟早会失控。

所以当我把这套文件读写需求改用 MCP 实现的时候，才真正理解了标题里那句话：别把时间浪费在写 JSON 上，不是说 JSON 这种格式没用，而是别让 JSON 去承担“协议”该干的活。

2. MCP 真正改的不是“格式”，而是“谁在说话”

和很多人的第一印象不同，MCP 协议并没有彻底抛弃 JSON。工具调用的参数、返回结果照样是结构化数据。真正的变化在于：MCP 把“接口文档”和“调用约束”变成了协议内置的一部分，让模型不再是面对一堆冷冰冰的字段，而是面对一组有语义、能协商、可发现的能力。

2.1 能力发现：AI 第一次能“问”你有哪些服务

传统的调用流程里，模型对接一个能力，依赖开发人员提前写清楚“这个接口叫什么、参数是什么、调用了会怎样”。一旦接口变更，参数不兼容，模型就很容易产生幻觉，或者干脆报错。MCP 协议定义了一套标准发现机制：客户端连接服务端后，通过list_tools这个内置方法，能动态拿到当前服务端支持的所有工具、每个工具的参数 schema、用途描述。

我那个文件读写服务里有三个工具：read_file、write_file、list_dir。模型连上来之后，不需要我在对话里反复强调“你可以读文件、可以写文件”，它自己会“看”到服务端声明的能力清单，而且每个工具都带一段自然语言描述。这个能力发现机制的最大价值在于：工具的增、删、改对调用方完全透明。我后面加了一个last_modified参数进去，客户端那侧一行代码都没改，模型下一次调用时会自动根据最新 schema 去填参数。

2.2 参数语义化：文件读写终于不用再“翻译”成 JSON 暗号

JSON 接口最大的隐性成本，就是“翻译层”。开发者在接口文档里写path字段代表文件路径，模型侧看到的只是一个字符串字段名；开发者写content代表要写入的内容，模型也看不到任何前因后果，只能靠有限的几百字 description 去猜。

MCP 的工具声明长这样：

{ "name": "read_file", "description": "读取指定路径的文本文件，可限制最大读取字符数", "inputSchema": { "type": "object", "properties": { "path": { "type": "string", "description": "要读取的文件绝对路径，例如 /workspace/demo.txt" }, "max_chars": { "type": "integer", "description": "最多读取多少字符，传 -1 表示读取整个文件", "default": -1 } }, "required": ["path"] } }

这段声明不算花哨，但它本身就是“接口文档 + 参数校验规则 + 自然语言提示”三合一的产物。模型读到description里的信息后，既能理解参数含义，也知道该以什么格式组织调用。相比我给 REST 接口维护的那堆 Markdown 文档，MCP 把这套描述直接做成了机器可读、模型可直接消费的格式。

从一次实际调用也能看出差异：原来我传给 REST 接口的 body 是一个无状态、无上下文的 JSON 数据包，而 MCP 里模型调用write_file时，参数仍然是一个 JSON 对象，但背后连带着完整的工具语义——服务端知道自己在执行“文件写入”，模型也知道这个调用会改变磁盘状态，双方的期待是一致的。

2.3 服务端状态：一次会话里的文件操作不再“失忆”

再回到我那个多步联动的难点。MCP 没有把状态管理做成强约束，但它给了一个自然的载体：会话（session）。客户端和服务端建立一次会话后，多个工具调用可以在同一会话里按顺序执行，服务端完全可以在内存里保留一些上下文，比如上次打开的文件路径、最近的目录快照、某些临时标记位。

这在读写文件场景中非常实用。我可以在服务端实现一个“当前工作目录”的概念：list_dir调用之后，服务端悄悄更新内部状态；后续read_file如果传的是相对路径，就基于这个工作目录去解析。模型不需要在每次调用时重复携带完整上下文，JSON 方案里那些session_id、action字段自然就不需要了。真正有状态的服务端才能匹配真正连续的 AI 工作流，这也是 MCP 相比“无状态 REST + 人工状态层”更贴合 AI 场景的原因。

3. 一个简单的读写文件 MCP 服务：从零到能跑的完整过程

理论讲了这么多，直接上一份能跑的代码。这个示例用的是 Python 和社区通用的 MCP SDK，我先写服务端，再写客户端，完整链路跑通之后你会明显感觉到：整个过程中几乎没有“设计接口字段”的时间消耗，大半精力都放在了功能本身。

3.1 先写服务端还是客户端？我的建议是先定工具边界

动手之前先想清楚一件事：这个服务到底暴露哪些工具、分别能做什么。我的建议是宁可先小后大，不要一开始就做一个“万能文件工具”。

我当时定的边界很简单：服务端只暴露三个工具，read_file、write_file、list_dir。没有delete_file，没有rename_file，也没有search_file。原因有两点：第一，工具数量越少，模型越容易把注意力集中在当前任务上；第二，MCP 的精髓在于“随需扩展”，后面真需要删文件再加一个工具也不迟，加的时候客户端不用做任何适配。

3.2 服务端：read_file、write_file、list_dir 三个函数就够了

下面是服务端代码的核心部分。注意list_tools方法把工具名、描述、参数 schema 一次性声明清楚，call_tool方法则根据模型传来的工具名和参数做实际执行：

# mcp_server_example.py import asyncio from pathlib import Path import mcp.types as types from mcp.server import Server import mcp.server.stdio server = Server("file-tool-server") @server.list_tools() async def list_tools() -> list[types.Tool]: return [ types.Tool( name="read_file", description="读取指定路径的文本文件，可限制最大读取字符数", inputSchema={ "type": "object", "properties": { "path": {"type": "string", "description": "文件的绝对路径"}, "max_chars": {"type": "integer", "description": "最多读取字符数，-1代表全文", "default": -1}, }, "required": ["path"], }, ), types.Tool( name="write_file", description="把一段文本内容写入指定文件，会覆盖旧内容", inputSchema={ "type": "object", "properties": { "path": {"type": "string", "description": "文件的绝对路径"}, "content": {"type": "string", "description": "需要写入的完整文本内容"}, }, "required": ["path", "content"], }, ), types.Tool( name="list_dir", description="列出指定目录下的文件和子目录名称", inputSchema={ "type": "object", "properties": { "path": {"type": "string", "description": "目录绝对路径"}, }, "required": ["path"], }, ), ] @server.call_tool() async def call_tool(name: str, arguments: dict) -> list[types.TextContent]: if name == "read_file": p = Path(arguments["path"]).resolve() data = p.read_text(encoding="utf-8") if arguments.get("max_chars", -1) != -1: data = data[: arguments["max_chars"]] return [types.TextContent(type="text", text=data)] if name == "write_file": p = Path(arguments["path"]).resolve() p.parent.mkdir(parents=True, exist_ok=True) p.write_text(arguments["content"], encoding="utf-8") return [types.TextContent(type="text", text=f"已写入 {len(arguments['content'])} 个字符")] if name == "list_dir": p = Path(arguments["path"]).resolve() entries = [e.name for e in p.iterdir()] return [types.TextContent(type="text", text="\n".join(entries))] raise ValueError(f"未知工具: {name}") async def main(): async with mcp.server.stdio.run_server( server, mcp.server.models.InitializationOptions( server_name="file-tool-server", server_version="0.1.0", ), ): pass if __name__ == "__main__": asyncio.run(main())

这里面有几个值得留意的细节：

• description一定不要随便写。模型判断什么时候调用这个工具、传什么参数，主要靠的就是这段描述。写“读取文件”四个字和写清楚“读取指定路径的文本文件，可限制最大读取字符数”在效果上有本质差异。
• 返回统一用TextContent，好处是模型能直接读懂文本内容，不需要再解析嵌套结构。如果内容需要结构化返回，也可以自定义 content 子类，但文件读取最简单、最稳的形态就是返回纯文本。
• 所有路径都做了.resolve()，尽量规避相对路径注入的风险。

3.3 客户端：一次对话，完成“查目录、读文件、写回修改”的连续操作

服务端跑起来之后，客户端一侧连的是 stdio 还是远程 HTTP，只影响连接建立方式，工具调用逻辑完全一致。

# mcp_client_example.py import asyncio from mcp import ClientSession, StdioServerParameters from mcp.client.stdio import stdio_client async def main(): server_params = StdioServerParameters( command="python", args=["mcp_server_example.py"], env=None, ) async with stdio_client(server_params) as (read, write): async with ClientSession(read, write) as session: await session.initialize() tools = await session.list_tools() print("发现工具:", [t.name for t in tools]) res = await session.call_tool("list_dir", {"path": "/workspace"}) print("工作区内容:", res.content[0].text) res = await session.call_tool("read_file", {"path": "/workspace/demo.txt", "max_chars": 500}) print("文件原文:", res.content[0].text) await session.call_tool("write_file", { "path": "/workspace/demo.txt", "content": "这是一段由 MCP 客户端写入的新内容" }) print("写入完成") if __name__ == "__main__": asyncio.run(main())

如果你连接的是部署在远程机器上的 MCP 服务，只需要把stdio_client换成sse_client或支持 HTTP 的客户端，连接地址变成服务端暴露的 URL 即可。对客户端来说，工具发现的逻辑没有任何差别，session.list_tools()会动态拿远程服务的能力清单，你的代码不用跟着远端的改动变。

跑完这个例子，你大概能体会到所谓“MCP 的威力”：整个调用链路上，没有一份需要人工同步维护的接口文档，没有一层“把业务动作翻译成 JSON 暗号”的胶水代码。服务端声明能力，客户端发现能力，模型基于语义决定调用，这一整套循环是协议帮你转起来的，你要写的只剩下实际业务逻辑。

4. 同一需求，两种方案的实测对比

代码跑通之后，我在自己电脑上做了一组对比测试：把同一个“AI 整理工作区文件”的需求，分别用 REST + JSON 方案和 MCP 方案实现，衡量了接入耗时、工具扩展成本、调用成功率和排错体验。结果用下面这个表直观呈现：

其中最让我意外的是“调用准确率”这一项。REST 方案下，模型在调用write_file时，偶尔会把content字段误填成 JSON 对象，而不是纯文本字符串；换成 MCP 之后这类问题少了很多。原因是 MCP 工具的定义里直接写明了“这是一段需要写入的完整文本内容”，模型不需要自己去推断这个字段的前因后果，它看到的本来就是一段人类可理解的能力描述。

另一个差别在“工具扩展”上。有个晚上我突然觉得应该让 AI 能看到文件大小，于是给list_dir的返回结果加了一列字节数。服务端改完，客户端代码根本没动。REST 方案里这种改动至少要牵动接口文档、示例代码、模型提示词三处。写 JSON 本身不慢，慢的是围绕 JSON 铺开的整个“接口生态”——文档、状态、权限、版本兼容，这些才是真正吃时间的地方。

还有一点值得单独说：MCP 方案下，模型如果调错了工具，它自己很容易从错误信息里恢复。比如我故意让write_file写入一个不存在的目录，服务端返回错误“目标目录不存在”，模型会自动调用list_dir去看父目录、甚至mkdir类工具去创建目录。这种自纠错能力在 REST 方案里几乎见不到，因为接口错误信息通常是一段冰冷的异常，根本不给模型下一步行动的线索。

5. MCP 的适用边界与坑：别把万能钥匙当锤子

MCP 虽然好，但不是所有场景都该上。它解决的是“AI 与工具能力之间的动态协商”问题，如果一个场景没有这个诉求，引入 MCP 反而增加复杂度。

5.1 这四个坑，我在读写文件场景里都踩过

一个协议的价值，不仅在于顺境里好用，更在于坑能不能被提前避开。下面几个是我实际踩过的：

• 路径安全。MCP 工具一旦暴露给模型，就等于把文件系统的某个角落开放给了 AI。如果我只是在call_tool里直接Path(arguments["path"]).resolve()然后操作，模型完全可能传一个/etc/passwd之类的路径。后来我加了一层根目录限制：只有当目标路径以允许的 WORKSPACE 为前缀时才继续执行，否则直接返回拒绝。
• 大文件读取。最蠢的一版是直接p.read_text()把整个十几 MB 的文件塞给模型。结果是上下文窗口直接被打爆，客户端那边卡死好一阵。正确做法是给read_file增加offset、limit之类参数，让模型分片读取，或者限制默认读取长度。
• stdio 子进程环境问题。用 stdio 模式启动服务端时，子进程加载的环境可能不完整，尤其在 GUI 环境里启动时 PATH 缺失，导致服务端找不到 Python 解释器。处理方式是显式把启动参数里的env补全一遍，继承当前进程环境并附加必要路径。
• 错误信息不够结构化。一开始我在call_tool里抛异常，客户端拿到的是一段堆栈信息，模型完全看不明白。后来统一改成返回TextContent且文本里带上错误码和可修复提示，比如ERROR_DIR_NOT_FOUND: 目录不存在，可先调用 list_dir 查看可用目录。模型看到这种错误，下一步行动的成功率显著提高。

5.2 什么场景保持 JSON 就够了

我做过的另一个内部小工具，只是定期把一份业务数据转成固定格式的 JSON 文件，再交给另一个系统消费。这个场景完全没有 AI 参与，也没有动态能力协商的需求，塞一套 MCP 进去就是画蛇添足。

总结一下，如果你的调用方是固定的、接口变更频率很低、人可以直接阅读文档，那 REST + JSON 依然是最务实的选择。尤其在后端系统之间的数据交换里，JSON Schema 的校验能力已经足够成熟，没必要引入额外的协议层。

5.3 什么场景可以放心上 MCP

反过来，下面这些信号一旦出现，我建议尽早切到 MCP：

• 调用方是 AI 模型，且它需要自主决定调用哪些能力；
• 工具数量会频繁增长，你不想每次加接口都全链路改一遍；
• 一个任务涉及多个工具的多步协作，比如“列出目录、读取文件、修改、写回”；
• 不同客户端都要共享同一组工具能力，你希望能力发现和调用约束都由协议统一处理。

5.4 我的选型建议

我现在的判断标准很简单：先问一句“谁在调用这个能力”。如果调用方是模型或智能体，默认走 MCP；如果调用方是确定的后端服务，继续用 JSON 就行。两种方式不冲突，反而可以在一个系统里共存——稳定的内部数据接口继续走 JSON，AI 需要动态编排的那部分服务全部切成 MCP。

最后再分享一个我在实际项目里总结的小经验：MCP 服务端不要一上来就做成大而全的“万能文件工具”。先定义三五个精准的小工具，把“列目录、读文件、写文件”这条主链路跑通，跑通之后再根据真实使用情况往里加能力。我见过不少人第一次接触 MCP 时兴奋过头，一口气把查询、删除、重命名、批量操作全塞进去，结果模型在选择工具时反而频繁出错。克制一点，让每个工具的功能边界足够清晰，MCP 带给你的体验才会是顺滑的，而不是换一种方式重新变得混乱。