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

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

---

---

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. 整体架构：谁跟谁说话？

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

3. MCP Server 内部结构示意

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

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

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

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

一句话对比

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

你可以简单记：

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

---

抽象层级 & 职责对比

维度	MCP	LangGraph	CrewAI	AutoGen
类型	协议 / 能力层	框架 + Runtime	框架 + 产品化工具	框架
关注点	工具 / 资源 / Prompt 标准化	有状态图、检查点、人工介入、生产级编排	多 Agent 分工协作、任务流水线	多 Agent 对话模式、事件驱动
面向对象	模型客户端 & 外部系统	Agent / State / Node / Edge	Agent / Task / Crew	Agent / 对话 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 下，避免路径越界。

环境准备

mkdir mcp-local-project
cd mcp-local-project

python -m venv .venv
# Windows
# .venv\Scripts\activate
# macOS / Linux
source .venv/bin/activate

pip install "mcp[cli]"

核心代码示例：server.py

# server.py
"""
一个针对本地项目的简单 MCP Server 示例：
- 使用 FastMCP（官方 Python SDK）
- 暴露项目文件浏览 / 阅读 / 搜索为 MCP 工具和资源
"""

import os
from pathlib import Path
from typing import List, Dict

from mcp.server.fastmcp import FastMCP

# ====== 配置你的项目根目录 ======
# 优先用环境变量 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()
    if not str(candidate).startswith(str(BASE_DIR)):
        raise ValueError("路径越界：只能访问项目根目录之下的文件")
    return candidate


# 创建 MCP Server（名字随便起，建议有意义一点）
mcp = FastMCP(name="LocalProjectServer", json_response=True)


# ====== 工具 1：列出项目文件 ======
@mcp.tool()
def list_project_files(
    subdir: str = ".",
    max_files: int = 100,
) -> List[str]:
    """
    列出项目目录下的文件（相对路径）。

    - subdir: 相对项目根目录的子目录，例如 "src"、"tests"
    - max_files: 最多返回多少个文件，防止结果太大
    """
    root = _safe_path(subdir)

    if not root.exists():
        raise FileNotFoundError(f"子目录不存在: {subdir}")

    files: List[str] = []
    for path in root.rglob("*"):
        if path.is_file():
            rel = path.relative_to(BASE_DIR).as_posix()
            files.append(rel)
            if len(files) >= max_files:
                break

    return files


# ====== 工具 2：读取单个项目文件 ======
@mcp.tool()
def read_project_file(
    path: str,
    max_bytes: int = 20000,
) -> str:
    """
    读取项目中的某个文本文件。

    - path: 文件相对项目根目录的路径，例如 "src/app/main.py"
    - max_bytes: 最多返回多少字节内容，避免一次性把巨型文件塞进上下文
    """
    file_path = _safe_path(path)

    if not file_path.is_file():
        raise FileNotFoundError(f"文件不存在: {path}")

    data = file_path.read_text(encoding="utf-8", errors="replace")

    if len(data) > max_bytes:
        data = data[:max_bytes] + "\n\n...[内容已截断]..."

    return data


# ====== 工具 3：在项目中做简单字符串搜索 ======
@mcp.tool()
def search_in_project(
    pattern: str,
    max_results: int = 20,
) -> List[Dict[str, str]]:
    """
    在项目中做简单的字符串搜索（不区分大小写）。

    - pattern: 要搜索的子串
    - max_results: 最多返回多少条匹配结果
    """
    if not pattern:
        raise ValueError("pattern 不能为空")

    results: List[Dict[str, str]] = []
    lower_pattern = pattern.lower()

    allowed_suffixes = {".py", ".md", ".txt", ".json", ".yaml", ".yml", ".toml"}

    for f in BASE_DIR.rglob("*"):
        if not f.is_file():
            continue

        # 只在常见文本文件中搜索，避免扫二进制/图片
        if f.suffix and f.suffix.lower() not in allowed_suffixes:
            continue

        try:
            text = f.read_text(encoding="utf-8", errors="ignore")
        except Exception:
            continue

        idx = text.lower().find(lower_pattern)
        if idx == -1:
            continue

        start = 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,
            }
        )

        if len(results) >= max_results:
            break

    return results


# ====== 资源示例：项目 README ======
@mcp.resource("project://readme")
def project_readme() -> str:
    """
    返回项目根目录下的 README 内容（如果存在）。
    """
    for name in ("README.md", "readme.md", "README.txt", "Readme.md"):
        candidate = BASE_DIR / name
        if candidate.exists():
            return candidate.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_project
export MCP_PROJECT_ROOT=/Users/john/my_project
# Windows PowerShell:
# $env:MCP_PROJECT_ROOT="C:\Users\john\my_project"

2. 启动 MCP Server

python server.py
# 默认在 http://localhost:8000/mcp 暴露 MCP 端点

3. 用 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 能力平台”的关键一步。