news 2026/2/26 11:26:37

一文搞懂 MCP：从入门到实战（含本地项目 MCP Server 示例）

作者头像

张小明

前端开发工程师

1.2k 24
文章封面图
一文搞懂 MCP：从入门到实战（含本地项目 MCP Server 示例）

用 MCP 打通本地项目与大模型：从概念到实战

一文搞清：MCP 是什么、如何和 LangGraph / CrewAI / AutoGen 配合、以及如何给本地项目写一个可用的 MCP Server。

这里写目录标题

  • 用 MCP 打通本地项目与大模型：从概念到实战
  • 1. MCP 是什么？
  • 2. MCP 的四层理解路径
      • 难度 1：白话视角
      • 难度 2：工程师视角
      • 难度 3：系统设计视角
        • 1. 数据立方体 → 工具立方体
        • 2. 调用流程
        • 3. Agent 框架中的位置
      • 难度 4：协议与生态视角
  • 3. MCP 工作原理图（Mermaid）
      • 1. 整体架构：谁跟谁说话？
      • 2. 一次“工具调用”的完整时序
      • 3. MCP Server 内部结构示意
      • 4. 本地开发环境中的位置
  • 4. MCP 与 LangGraph / CrewAI / AutoGen 的关系
      • 一句话对比
      • 抽象层级 & 职责对比
      • 工具接入方式：为什么说“能组合拳”
      • 典型使用场景选型建议
  • 5. 实战：给本地项目写一个 MCP Server
      • 环境准备
      • 如何运行 & 测试
      • 如何接入 ChatGPT / IDE / Agent 框架
      • 如何继续扩展
  • 6. 参考架构与最佳实践
  • 7. 结语

1. MCP 是什么？

MCP（Model Context Protocol）是一个开放协议，用来标准化：

「大模型 ↔ 外部世界（工具 / 数据 / 应用）之间如何说话与协作」

你可以把它类比成：

  • 浏览器世界里的 HTTP + API
  • 数据库世界里的 SQL
  • 在“AI + 工具”世界里，MCP 扮演“统一插座 + 协议层”的角色

有了 MCP，大模型不再只是“会聊天”，而是可以：

  • 读写文件、本地项目代码
  • 访问数据库、搜索引擎、内部 API
  • 调用自动化脚本、测试、构建流水线
  • 在受控范围内操作你的本地/企业系统

一句话：

MCP 让模型从「只能说」变成「能干活」。

2. MCP 的四层理解路径

难度 1：白话视角

从小白角度看，MCP 就是一个：

“给 AI 插各种电器的万能插座”

  • 以前：
    • AI 只能在上下文里“想象”文件和数据
  • 现在：
    • AI 可以通过 MCP 实际去打开文件、查数据库、调 API
    • 当然，这些能力都是你显式授权、显式暴露的工具

它解决的问题是：

  • 不同 AI 产品、不同模型厂商各自定义工具接入方式 → 混乱
  • 工程师每接一次模型就要重写一次工具层 → 浪费
  • 安全边界模糊 → 难以审核与合规

MCP 给的是：

  • 统一约定：“工具长什么样、怎么描述、怎么调用”
  • 对话式调用流程：由模型自己决定什么时候调用哪个工具

难度 2：工程师视角

从工程角度看，MCP 做了三件事：

  1. 把外部世界抽象成三类资源

    • Tools（工具）：可执行动作
      • 例如：run_sql、search_docs、create_file、send_email
    • Resources（资源）：可浏览的数据或状态
      • 例如：文件系统、数据库表、知识库、项目结构
    • Prompts（模板）：可复用的提示模板
      • 例如：generate_unit_test、summarize_contract等

  2. 统一调用方式

    模型向 MCP Server 发起标准化请求（类似 JSON-RPC）：

    • listTools/callTool
    • listResources/readResource
    • listPrompts/callPrompt

  3. Client 与 Server 解耦

    • 上层：任何 MCP Client（ChatGPT、Claude、IDE 插件、Agent 框架……）
    • 下层：你的 MCP Server（封装 DB、本地项目、API、脚本……）

两者中间用 MCP 协议连接，中间层可以任意替换：

  • 换模型：工具层不用重写
  • 换工具实现：上层编排逻辑不用大改

难度 3：系统设计视角

从架构视角看，MCP 是一个**“AI 运行时能力层（AI Runtime Capability Layer）”**：

1. 数据立方体 → 工具立方体

传统 BI 里有“数据立方体”（Data Cube）：
现在你可以理解为 MCP 在构建“能力立方体”：

  • 每个 MCP Server 暴露自己的一组 Tools / Resources / Prompts
  • 多个 MCP Server 可以串联在一起，共同构成一个能力网格
2. 调用流程

典型调用链是：

用户 -> 模型 -> MCP Client -> MCP Server -> 工具/资源 -> MCP Server -> MCP Client -> 模型 -> 用户

中间模型会：

  • 决定「要不要用工具」
  • 选择「用哪个工具」
  • 构造参数，解析返回结果
  • 把结果用自然语言 / 结构化形式呈现给用户
3. Agent 框架中的位置

在 LangGraph / CrewAI / AutoGen 等框架里，
MCP 可以作为“所有工具的统一底座”：

  • LangGraph 节点内部调用 MCP Tools
  • CrewAI 的 Agent 绑定的 Tools 底层用 MCP
  • AutoGen 的代码执行 / 工具调用也可通过 MCP

这样，工具开发只做一遍，各种框架通吃。

难度 4：协议与生态视角

再严谨一点，从协议和标准的角度看：

  • MCP 基于JSON-RPC 双向流
  • 规范了几个核心能力：
    • 工具发现与调用：listTools/callTool
    • 资源浏览：listResources/readResource
    • Prompt 模板：listPrompts/callPrompt
    • 事件流（部分实现）：订阅更新、状态变化等
  • 工具、资源、Prompt 的描述采用结构化 Schema（常见是 JSON Schema）

在生态层面：

  • MCP 被多家模型厂商采纳为标准接口
  • IDE / Agent 平台 / 企业 AI 应用可以直接对接 MCP Server
  • MCP Server 可以开源、复用、组合，成为“AI 世界的微服务”

3. MCP 工作原理图（Mermaid）

以下是几张常用的架构/时序图，全部用 Mermaid 编写，可直接在支持 Mermaid 的 Markdown 环境中渲染。

1. 整体架构：谁跟谁说话？

对话
按照 MCP 协议发起请求
JSON-RPC 双向通道
调用
访问
使用
用户
大模型 (如 GPT / Claude)
MCP 客户端 (ChatGPT / IDE 插件 / 中间层)
MCP 服务器
Tools：执行动作 (API / 脚本 / 服务)
Resources：数据源 (文件 / DB / 知识库)
Prompts：可复用提示模板
外部系统 / 服务
外部数据源 (文件 / 数据库 / 对象存储)

2. 一次“工具调用”的完整时序

用户大模型MCP 客户端MCP 服务器Tool/Resource自然语言问题（例：查一下最近的订单统计）解析意图 + 规划是否需要调用工具发起 MCP 工具调用请求(callTool: "get_orders_stats", args)通过 JSON-RPC 转发 callTool 请求执行具体工具 / 访问资源(如查数据库 / 读文件 / 调 API)返回结构化结果（JSON 等）JSON-RPC 响应（工具结果）将结果交回模型结合用户问题 + 工具结果进行推理返回自然语言回答 + 必要的数据/表格用户大模型MCP 客户端MCP 服务器Tool/Resource

3. MCP Server 内部结构示意

MCP 服务器
listTools / callTool / listResources 等
JSON-RPC 处理层
Tools 描述：name + description + inputSchema
Resources 描述：listResources / readResource
Prompts 描述：可复用 Prompt 模板
执行层：脚本 / API Client / 命令行等
数据访问层：文件系统 / 数据库 / 搜索引擎
Prompt 模板引擎
MCP 客户端

4. 本地开发环境中的位置

MCP Server on Local Machine
内置 Chat / Copilot
MCP 协议
MCP 本地服务器
Git / 本地代码仓库 Tool
项目构建 / 测试脚本 Tool
本地文件系统 Resource
内部 API Resource
项目专用 Prompt 模板
开发者
IDE / 开发工具 (VSCode / Cursor 等)
LLM + MCP 客户端
本地代码仓库 / 文件
企业内网系统 / 服务

4. MCP 与 LangGraph / CrewAI / AutoGen 的关系

很多人会问：“MCP 和 LangGraph / CrewAI / AutoGen 是竞品吗？”

答案是：不是同一层的东西，更像是“可以叠加的组合拳”。

一句话对比

  • MCP：
    标准化协议，解决“模型 ↔ 工具 / 数据”怎么连的问题。
  • LangGraph：
    Agent / 工作流编排框架，用“有状态图”描述复杂流程。
  • CrewAI：
    多 Agent 协作框架，主打“像组织一个团队那样组织 Agent”。
  • AutoGen：
    多 Agent 对话与协作框架，更偏研究和复杂协作模式。

你可以简单记：

MCP = 能力层（工具协议）
LangGraph / CrewAI / AutoGen = 编排层（流程与 Agent 逻辑）

抽象层级 & 职责对比

维度MCPLangGraphCrewAIAutoGen
类型协议 / 能力层框架 + Runtime框架 + 产品化工具框架
关注点工具 / 资源 / Prompt 标准化有状态图、检查点、人工介入、生产级编排多 Agent 分工协作、任务流水线多 Agent 对话模式、事件驱动
面向对象模型客户端 & 外部系统Agent / State / Node / EdgeAgent / Task / CrewAgent / 对话 Session
可替代关系通用标准层内部可以调用 MCP 工具可把 MCP 工具作为 Agent 的工具集合可用 MCP 作为工具层

工具接入方式：为什么说“能组合拳”

  • 在MCP 视角：
    • MCP 只规定“工具长什么样 + 怎样调用”，不规定编排逻辑。
  • 在Agent 框架视角：
    • LangGraph / CrewAI / AutoGen 各自有自己的Tool抽象；
    • 这些 Tool 的底层完全可以统一为MCP 调用。

这意味着：

你可以只实现一套 MCP Server，然后：

  • 在 LangGraph 里当作工具使用
  • 在 CrewAI 里当作 Agent 的工具集合
  • 在 AutoGen 里作为工具执行后端
  • 在 ChatGPT / Claude / IDE 中直接被模型调用

工具开发成本只做一遍，跨平台复用。

典型使用场景选型建议

可以按下面思路做初步选型：

  1. 工具层要不要标准化？

    如果你满足以下任一情况：

    • 未来会接多个模型 / 多家厂商；
    • 会有多个入口（ChatGPT / 内部前端 / IDE / Agent 框架）；

    那么：建议优先铺 MCP，作为统一能力层。

  2. 编排层如何选？

    • 流程复杂、多步骤、需要持久化 / 回溯 / 人工审核
      → 更适合用LangGraph。
    • 偏向“多角色团队协作式自动化”（调研 → 撰写 → 审核 → 发布）
      → 很适合CrewAI。
    • 需要做多 Agent 协作的研究、实验新范式
      →AutoGen非常合适。

  3. 组合拳架构（推荐）

    • 底层：MCP Server 封装所有系统能力；
    • 中间：LangGraph / CrewAI / AutoGen 作为 orchestrator；
    • 顶层：ChatGPT / 内部前端 / IDE 等各种入口共享这一套 MCP 能力。

5. 实战：给本地项目写一个 MCP Server

下面是一个可直接运行的示例，用Python + 官方 MCP SDK（FastMCP），
把你本地项目目录暴露成三类工具 + 一个资源：

  • 工具：
    • list_project_files：列项目文件；
    • read_project_file：读文件内容；
    • search_in_project：在项目内简单全文搜索。
  • 资源：
    • project://readme：项目 README 内容。

注意：所有路径都被限制在指定的BASE_DIR下，避免路径越界。

环境准备

mkdirmcp-local-projectcdmcp-local-project python -m venv .venv# Windows# .venv\Scripts\activate# macOS / Linuxsource.venv/bin/activate pipinstall"mcp[cli]"

核心代码示例：server.py

# server.py""" 一个针对本地项目的简单 MCP Server 示例： - 使用 FastMCP（官方 Python SDK） - 暴露项目文件浏览 / 阅读 / 搜索为 MCP 工具和资源 """importosfrompathlibimportPathfromtypingimportList,Dictfrommcp.server.fastmcpimportFastMCP# ====== 配置你的项目根目录 ======# 优先用环境变量 MCP_PROJECT_ROOT；否则默认使用当前文件所在目录BASE_DIR=Path(os.getenv("MCP_PROJECT_ROOT",Path(__file__).parent)).resolve()def_safe_path(relative:str)->Path:""" 将相对路径转成绝对路径，并确保仍然位于 BASE_DIR 内部，防止目录穿越。 """candidate=(BASE_DIR/relative).resolve()ifnotstr(candidate).startswith(str(BASE_DIR)):raiseValueError("路径越界：只能访问项目根目录之下的文件")returncandidate# 创建 MCP Server（名字随便起，建议有意义一点）mcp=FastMCP(name="LocalProjectServer",json_response=True)# ====== 工具 1：列出项目文件 ======@mcp.tool()deflist_project_files(subdir:str=".",max_files:int=100,)->List[str]:""" 列出项目目录下的文件（相对路径）。 - subdir: 相对项目根目录的子目录，例如 "src"、"tests" - max_files: 最多返回多少个文件，防止结果太大 """root=_safe_path(subdir)ifnotroot.exists():raiseFileNotFoundError(f"子目录不存在:{subdir}")files:List[str]=[]forpathinroot.rglob("*"):ifpath.is_file():rel=path.relative_to(BASE_DIR).as_posix()files.append(rel)iflen(files)>=max_files:breakreturnfiles# ====== 工具 2：读取单个项目文件 ======@mcp.tool()defread_project_file(path:str,max_bytes:int=20000,)->str:""" 读取项目中的某个文本文件。 - path: 文件相对项目根目录的路径，例如 "src/app/main.py" - max_bytes: 最多返回多少字节内容，避免一次性把巨型文件塞进上下文 """file_path=_safe_path(path)ifnotfile_path.is_file():raiseFileNotFoundError(f"文件不存在:{path}")data=file_path.read_text(encoding="utf-8",errors="replace")iflen(data)>max_bytes:data=data[:max_bytes]+"\n\n...[内容已截断]..."returndata# ====== 工具 3：在项目中做简单字符串搜索 ======@mcp.tool()defsearch_in_project(pattern:str,max_results:int=20,)->List[Dict[str,str]]:""" 在项目中做简单的字符串搜索（不区分大小写）。 - pattern: 要搜索的子串 - max_results: 最多返回多少条匹配结果 """ifnotpattern:raiseValueError("pattern 不能为空")results:List[Dict[str,str]]=[]lower_pattern=pattern.lower()allowed_suffixes={".py",".md",".txt",".json",".yaml",".yml",".toml"}forfinBASE_DIR.rglob("*"):ifnotf.is_file():continue# 只在常见文本文件中搜索，避免扫二进制/图片iff.suffixandf.suffix.lower()notinallowed_suffixes:continuetry:text=f.read_text(encoding="utf-8",errors="ignore")exceptException:continueidx=text.lower().find(lower_pattern)ifidx==-1:continuestart=max(0,idx-80)end=min(len(text),idx+len(pattern)+80)snippet=text[start:end].replace("\n"," ")results.append({"path":f.relative_to(BASE_DIR).as_posix(),"snippet":snippet,})iflen(results)>=max_results:breakreturnresults# ====== 资源示例：项目 README ======@mcp.resource("project://readme")defproject_readme()->str:""" 返回项目根目录下的 README 内容（如果存在）。 """fornamein("README.md","readme.md","README.txt","Readme.md"):candidate=BASE_DIR/nameifcandidate.exists():returncandidate.read_text(encoding="utf-8",errors="replace")return"未在项目根目录找到 README 文件。"if__name__=="__main__":# 使用 HTTP 作为传输层，默认监听 http://localhost:8000/mcp# 某些客户端/IDE 也可以用 transport="stdio"mcp.run(transport="streamable-http")

如何运行 & 测试

  1. 指定要暴露的项目根目录
# 假设你的项目在 /Users/john/my_projectexportMCP_PROJECT_ROOT=/Users/john/my_project# Windows PowerShell:# $env:MCP_PROJECT_ROOT="C:\Users\john\my_project"
  1. 启动 MCP Server
python server.py# 默认在 http://localhost:8000/mcp 暴露 MCP 端点
  1. 用 MCP Inspector 调试（推荐）
npx -y @modelcontextprotocol/inspector

在浏览器中：

  • 填写 MCP Server URL：http://localhost:8000/mcp

  • 连接后可以：

  • 查看listTools/listResources

  • 手动调用list_project_files/read_project_file/search_in_project

  • 读取project://readme资源

如何接入 ChatGPT / IDE / Agent 框架

在支持 MCP 的客户端中配置：

  • MCP Server 地址：http://localhost:8000/mcp

之后，模型就可以：

  • 直接阅读你的本地项目代码；
  • 根据上下文自动调用搜索工具；
  • 结合文件内容给你 refactor / bug fix / 文档生成建议。

在 Agent 框架中，例如 LangGraph / CrewAI / AutoGen，可以：

  • 封装一个“调用 MCP 工具”的通用函数；
  • 把 MCP Server 暴露的工具当作这些框架中的 tools 使用。

如何继续扩展

在上述示例基础上，你可以很自然地增加更多工具，例如：

  • run_tests()：运行项目测试（pytest / npm test），返回摘要；
  • build_project()：触发构建脚本（注意要严格白名单）；
  • search_legal_clauses()：如果是律所项目，对合同模板库做结构化检索；
  • get_api_endpoints()：解析路由配置，导出 API 列表给模型参考。

设计原则：

  1. 所有文件访问走_safe_path，只允许在BASE_DIR内活动；
  2. 所有有副作用的操作走白名单（只允许执行明确列出的脚本/命令）；
  3. 工具输入参数尽量结构化 & 明确类型，利于模型构造正确参数。

6. 参考架构与最佳实践

一个推荐的整体架构是：

  1. 底层：能力层（MCP Servers）

    • db-mcp-server：封装数据库访问；
    • fs-mcp-server：封装文件系统 / 文档库；
    • project-mcp-server：封装本地项目相关能力；
    • thirdparty-mcp-server：封装第三方 API（邮件、日程、CRM……）。

  2. 中间：编排层（Agent / Workflow 框架）

    • LangGraph：处理长流程、有状态、有人工审核的业务；
    • CrewAI：处理“多角色团队协作式”的业务场景；
    • AutoGen：用于研究性、多 Agent 协作模式实验。

  3. 顶层：入口层

    • ChatGPT / Claude / 公司内部前端；
    • IDE（VSCode / Cursor / JetBrains）；
    • 内网 Bot（Slack / Teams / 钉钉 / 企业微信）。

所有入口共用一套 MCP 能力层，
升级工具或接新系统只需要在 MCP Server 扩展即可。

7. 结语

如果只用一句话概括这部分内容：

MCP 是一个统一的“AI 能力层协议”，
让工具只写一次、到处可用，
并能和 LangGraph / CrewAI / AutoGen 等框架组合成强大的 Agent 系统。

你现在已经具备：

  • 对 MCP 在整个 Agent 生态中位置的认知；
  • 一个可运行的本地项目 MCP Server 示例；
  • 接入与扩展的基本思路。

接下来，你可以试着：

  1. 在自己的真实项目里改造这个示例；
  2. 把它接入 IDE / Agent 框架；
  3. 逐步把“日常重复工作”迁移到 MCP + Agent 上。

这将是从“会用大模型”迈向“打造 AI 能力平台”的关键一步。

版权声明: 本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如若内容造成侵权/违法违规/事实不符，请联系邮箱：809451989@qq.com进行投诉反馈，一经查实，立即删除！
网站建设 2026/2/20 19:29:13

终极免费字幕下载神器：OpenSubtitlesDownload完整使用指南

终极免费字幕下载神器：OpenSubtitlesDownload完整使用指南 【免费下载链接】OpenSubtitlesDownload Automatically find and download the right subtitles for your favorite videos! 项目地址: https://gitcode.com/gh_mirrors/op/OpenSubtitlesDownload 还…

作者头像 李华
网站建设 2026/2/26 20:15:28

Photoshop图层批量导出革命：智能工具带来的终极效率突破

Photoshop图层批量导出革命：智能工具带来的终极效率突破 【免费下载链接】Photoshop-Export-Layers-to-Files-Fast This script allows you to export your layers as individual files at a speed much faster than the built-in script from Adobe. 项目地址: h…

作者头像 李华
网站建设 2026/2/21 14:39:28

时间序列预测中的数据转换艺术：从标准化输出到业务价值

时间序列预测中的数据转换艺术：从标准化输出到业务价值 【免费下载链接】Time-Series-Library A Library for Advanced Deep Time Series Models. 项目地址: https://gitcode.com/GitHub_Trending/ti/Time-Series-Library 在电商平台的销量预测中&#xff0c…

作者头像 李华
网站建设 2026/2/25 8:14:30

KISS FFT：轻量高效的信号处理开发利器

KISS FFT：轻量高效的信号处理开发利器 【免费下载链接】old-kissfft [DEPRECATED MIRROR] You want https://github.com/mborgerding/kissfft! 项目地址: https://gitcode.com/gh_mirrors/ol/old-kissfft 在信号处理领域，快速傅里叶变换&#xff…

作者头像 李华
网站建设 2026/2/22 5:16:41

企业工单系统新选择：Ferry如何用5分钟解决团队协作难题

企业工单系统新选择：Ferry如何用5分钟解决团队协作难题 【免费下载链接】ferry_web ferry ui展示。 项目地址: https://gitcode.com/gh_mirrors/fe/ferry_web 你是否经历过这样的场景？客户反馈的问题在多个部门间反复流转，却始终找不到…

作者头像 李华
网站建设 2026/2/10 5:59:37

5分钟掌握系统监控工具选型：SkyWalking与Sentry终极指南

5分钟掌握系统监控工具选型：SkyWalking与Sentry终极指南 【免费下载链接】skywalking APM, Application Performance Monitoring System 项目地址: https://gitcode.com/gh_mirrors/sky/skywalking 你是否曾在深夜被紧急告警惊醒，却不知从何入手排…

作者头像 李华