从MCP基础到FastMCP实战应用

Dongwoo Jeong

已于 2025-05-01 23:47:45 修改

阅读量1k

点赞数 10

文章标签：开发语言 MCP AI Cluade Python python

于 2025-05-01 23:41:57 首次发布

本文链接：https://blog.csdn.net/2404_84768005/article/details/147655675

版权

MCP(https://github.com/modelcontextprotocol)

MCP（模型上下文协议） 是一种专为 基于LLM的工具调用外部工具而设计的协议 ，
本质上是 LLM ↔ 工具之间的RPC（远程过程调用） 的一种安全且一致的处理方式，
是一种 轻量级的JSON-RPC标准 。

我是韩国人，不是中国人。但最近在韩国，如果不使用MCP，就会被认为是跟不上潮流的人，MCP非常火热。我的博客虽然喜欢写大多数人能享受的编程理论文章，但由于理论文章的资料整理与验证需要耗费大量时间，再加上最近因为体力劳动没有太多时间，并且考虑到概念理解上Python非常适合，因此我打算用Python的FastMCP快速实现一个MCP。

1.一般来说，MCP结构如下所示：

[用户提示]

↓

[LLM]

↓

生成 "tool_call" （MCP）

↓ [

工具服务器执行（如FastMCP等）]

↓

生成MCP响应 → 传递给LLM

↓

LLM生成最终响应

2.MCP协议格式

实际上，MCP = JSON-RPC 2.0的子集
（即遵循JSON-RPC标准，但仅提供MCP特定的工具调用方式）

MCP字段	说明
`jsonrpc`	"2.0"（固定值）
`method`	要调用的工具名称
`params`	传递给工具的参数（字典形式）
`id`	调用标识符（自动递增等）
`result`	工具的执行结果

基本结构

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tool_name",
  "params": {
    "argument1": "value1",
    "argument2": 42
  }
}

2. 核心组成部分

1. `tool_call` (Claude → MCP服务器: 请求消息 )

当Claude判断需要调用工具时，会向MCP服务器发送以下的JSON-RPC 2.0请求消息 。

// Claude -> MCP服务器 (请求示例)
{
  "jsonrpc": "2.0",
  "id": 123, // 请求标识符（由Claude生成，与响应匹配）
  "method": "search_nature_articles", // 调用的工具（函数）名称
  "params": { // 将传递给工具（函数）的参数（字典形式）
    "keyword": "quantum computing",
    "max_results": 3 // 示例：附加参数
  }
}

2. `MCP Server` (本地或远程工具执行器)

Claude Desktop会在本地运行配置好的MCP服务器。
必须注册tool_name（即method字段值），并将其绑定到可执行函数。
在Python中，FastMCP可以轻松实现这一点。

@mcp.tool()
def search_nature_articles(keyword: str, max_results: int = 3): # 与params匹配
    ...

3. `MCP Response` (MCP服务器 → Claude: 响应消息 )

工具（函数）在MCP服务器上执行后，其结果将以JSON-RPC 2.0响应消息 的形式返回给Claude。包括成功或失败（错误）两种情况。

// MCP服务器 -> Claude (成功响应示例)
{
  "jsonrpc": "2.0",
  "id": 123, // 必须与请求消息中的id相同
  "result": "'quantum computing'相关论文3篇搜索结果:\n1. Title A...\n..." // 工具执行结果（字符串、数字、列表、对象等均可）
}

// MCP服务器 -> Claude (错误响应示例)
{
  "jsonrpc": "2.0",
  "id": 123, // 与请求id相同（如果无法识别，也可以为null）
  "error": { // 发生错误时包含'error'对象而不是'result'
    "code": -32000, // 示例：服务器错误代码
    "message": "Springer Nature API密钥认证失败" // 错误消息
  }
}

为什么需要MCP？

用表格总结如下：

问题	MCP的解决方案
LLM无法执行代码	通过调用外部工具解决
结构化输入/输出困难	使用JSON-RPC实现一致的参数传递
工具错误处理困难	提供明确的错误响应
工具增多导致结构复杂	基于名称的路由 + 分离的服务器架构解决
要素	内容
协议名称	MCP（模型上下文协议）
技术基础	JSON-RPC 2.0
目标	让LLM能够安全地调用外部工具并接收响应
执行方式	在本地服务器或本地进程中运行MCP兼容服务器
典型实现	FastMCP（Python），server-filesystem（JS）
通信对象	Claude Desktop / Claude API

本文将指导如何快速在 VS Code 环境中设置开发 Claude MCP 系统的步骤。
这是使用 FastMCP 构建 MCP 服务器并运行基于 Python 的工具所需的配置。

FastMCP 是一个完整的 Claude 专用 MCP 工具服务器实现。

FastMCP (Python) 不直接打开端口

FastMCP 不会直接打开 TCP 套接字或 HTTP 服务器。
相反，它通过 stdio（标准输入输出）与 Claude Desktop 进行通信 。
换句话说，Claude 内部会以 stdin/stdout 的方式启动 MCP 进程来进行通信。

通常，许多示例中会有以下结构：

mcp_server.py
mcp_client.py

这种结构仅用于练习或调试 JSON-RPC 协议，但并不会与 Claude 实际集成（仅用于测试目的）。

因此，为了实现与 Claude 的实际集成，使用 FastMCP 是最简单的方法之一。接下来我们将使用 FastMCP 实际构建一个 MCP。

总结

FastMCP 是专为 Claude 设计的轻量级工具，避免了复杂的网络设置。
它通过标准输入输出 (stdin/stdout) 与 Claude 桌面版通信。
使用 FastMCP 可以更高效地完成实际的 MCP 开发和集成。

1. 安装 VS Code

访问 https://code.visualstudio.com
下载并运行与操作系统对应的安装文件。

2. 安装 VS Code 及扩展

启动 VS Code 后，在左侧的扩展（Extensions）选项卡中搜索并安装以下内容：

Python (ms-python.python)
（可选）Pylance、IntelliCode（用于增强自动补全功能）

3. 创建并打开项目文件夹

在计算机上创建一个项目文件夹。在我的情况下，我将其命名为 PaperPort。

4. 虚拟环境设置

在 VSCode 菜单中选择终端(Terminal) -> 新建终端(New Terminal)，即可在 VS Code 内打开终端。
在终端中输入以下命令，创建一个名为 .venv 的虚拟环境

python -m venv .venv
# 或者 python3 -m venv .venv （根据系统不同）

一定要用 '.venv' 吗？ : venv 模块本身对虚拟环境文件夹的名称没有特别限制。你可以使用任何你想要的文件夹名称 。不过，如果文件夹名称前加了点（.），在 Linux 或 macOS 等 Unix 系统中会被视为隐藏文件夹，而 .venv 是一种常见的命名约定。

激活虚拟环境 : 创建虚拟环境后，你需要将其“激活”才能使用。根据终端类型不同，激活命令略有差异。

Windows (PowerShell):
```
.\.venv\Scripts\Activate.ps1
```
Windows (Command Prompt - cmd):
```
.\.venv\Scripts\activate.bat
```
macOS / Linux (bash/zsh):
```
source .venv/bin/activate
```
实际上，查看 .venv 文件夹中的文件并执行相应的文件会更快。在我的情况下，生成了 activate.bat 文件，因此我执行了该文件。

5. 设置所需的库

根据我对 fastmcp 示例的搜索结果，requests 库也是必需的，因此可以一起安装。

创建 requirements.txt 文件： 将安装的库列表保存到文件中，这样以后在其他环境中可以轻松地进行相同的设置，或者与他人共享。由于我的环境可能会有所不同，因此我会创建这个文件。

使用 requirements.txt 安装依赖的命令：
```
pip install -r requirements.txt
```
6. 获取 API 密钥

创建一个 .env 文件。.env 是环境变量文件，用于连接实际的密钥。
直接将密钥写入 Python 文件的方式存在安全问题。

6-1. Claude API 访问方法

访问 https://www.anthropic.com/api 。

创建密钥。

由于我的密钥是私人的，为了不展示，我特意创建了一个新账户。

访问 https://dev.springernature.com/ 并创建密钥。

同样，我的密钥不会展示。

7. 编写 MCP 工具代码

在项目文件夹中创建一个以 .py 结尾的 Python 文件。
我们的目标是创建一个 Nature 论文搜索工具，因此命名为 tool_nature.py。

from fastmcp import FastMCP
import requests
from urllib.parse import urlencode
import os
from dotenv import load_dotenv
import sys

# 加载环境变量
load_dotenv()

# 初始化 MCP 实例
mcp = FastMCP("Nature API Tool Server")


# 定义常量
BASE_URL = "http://api.springernature.com/metadata/json"
API_KEY = os.getenv("NATURE_API_KEY")

  
# 如果没有 API 密钥则立即退出
if not API_KEY:
    print("[FATAL] 环境变量 'NATURE_API_KEY' 未设置。", file=sys.stderr)
    raise RuntimeError("[CRITICAL] 环境变量 'NATURE_API_KEY' 未设置。请在 .env 或系统环境中注册密钥。")

@mcp.tool()
def search_nature_articles(keyword: str, max_results: int = 3) -> str:

    """
    使用 Nature（Open API）根据给定的关键字搜索论文标题和摘要。
    结果将以摘要形式返回。

    """
    query_params = {
        "q": keyword,
        "api_key": API_KEY,
        "p": max_results

    }

  

    try:
        response = requests.get(f"{BASE_URL}?{urlencode(query_params)}")
        response.raise_for_status()
        data = response.json()
        records = data.get("records", [])

  

        if not records:
            return f"未找到关于 '{keyword}' 的结果。"

        output_lines = [f"\n 搜索结果： {keyword}"]
        for i, article in enumerate(records):
            title = article.get("title", "无标题")


            # 摘要类型安全处理

            abstract_raw = article.get("abstract", "无摘要")
            if isinstance(abstract_raw, dict):
                abstract = abstract_raw.get("p", "无摘要")
            else:
                abstract = abstract_raw

            url_list = article.get("url", [])
            url = url_list[0].get("value") if url_list else "N/A"
            abstract_summary = (abstract[:400] + "...") if len(abstract) > 400 else abstract
            output_lines.append(f"\n{i+1}. {title}\n   URL: {url}\n   摘要: {abstract_summary}")

  

        return "\n".join(output_lines)
    except requests.exceptions.RequestException as e:
        print(f"[ERROR] API 请求时发生错误: {e}", file=sys.stderr)
        return f"[ERROR] API 请求时发生错误: {e}"
    except Exception as e:
        print(f"[ERROR] 数据处理时发生错误: {e}", file=sys.stderr)
        return f"[ERROR] 数据处理时发生错误: {e}"

  

# 启动 MCP 服务器

if __name__ == "__main__":
 # --------------------------------------------------------------------------
    # [重要] 下面的 print 语句中的 'http://localhost:3333' 地址相关说明:
    # 1. 该地址仅为示例，不是实际的 FastMCP 服务器访问地址。
    # 2. 当使用 Claude Desktop 执行此脚本作为 MCP 服务器时，
    #    FastMCP 不使用网络端口（HTTP），
    #    而是通过 stdio（标准输入输出）与 Claude Desktop 进行通信。
    # 3. 因此无法直接访问 'http://localhost:3333'。
    # 4. 该地址仅供参考，假设将来使用 FastAPI 构建网络服务器或扩展时，
    #    可将其视为占位符或示例。

    # --------------------------------------------------------------------------
    print(" 正在启动 Nature 工具服务器... http://localhost:3333")

    mcp.run()

7-1 ## .vscode/launch.json 示例（用于调试）

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "运行 MCP 工具",
      "type": "python",
      "request": "launch",
      "program": "${workspaceFolder}/tool_nature.py",
      "envFile": "${workspaceFolder}/.env"
    }
  ]
}

8. 配置 MCP 服务器

配置通过修改 claude_desktop_config.json 文件进行。

可以在以下路径创建该文件：

Windows: %APPDATA%\Claude\claude_desktop_config.json
MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json

或者： 点击 Claude 桌面左上角菜单 - 文件 - 设置 - 开发者 - 编辑配置按钮。

8-1. 手动注册 MCP 服务器（修改配置文件 `claude_desktop_config.json`）

Claude Desktop 可以通过配置文件手动注册 MCP 服务器。

（示例是我的文件路径。）

{
    "mcpServers": {
        "nature": {
            "command": "Python 路径",
            "args": [
                "py 文件所在的路径"
            ]
        }
    }
}

运行 tool_nature.py

9. 启动

首先需要在 VSCode 中运行 py 脚本。

然后可以在 Claude 桌面开发者界面看到正在运行的状态。

10. 现在可以做的事

摘要总结

Call tool search_nature_articles with keyword="感兴趣的领域关键词"

URL 返回

search_nature_articles(keyword="感兴趣的领域关键词")

获取两篇相关论文，并返回其摘要和 URL。

Bouns: 如果想在 "localhost:3333" 端口上通过 HTTP 接收请求，该怎么做？

这需要使用 FastAPI、Flask、aiohttp 等单独启动服务器 ，而不是使用 FastMCP：

from fastapi import FastAPI
from fastmcp import MCPMiddleware

app = FastAPI()
app.add_middleware(MCPMiddleware, tools=[...])

# 这样 FastAPI 就会在 http://localhost:3333 端口上监听请求

→ 这种方式适用于使用 transport="sse" 的情况。
→ 当前的 FastMCP 默认不使用这种方式。

平時上傳的文章性質與以往有很大的不同，因此感到有些遺憾。

我的博客文章通常面向所有語言的使用者，但最近發表了一些針對特定語言的內容，對此我感到對欣賞本博客的所有讀者有些抱歉。

最近因為忙於工地工作，沒有時間撰寫理論性的文章。

對期待我的讀者們表示歉意。