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

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

我是韩国人，不是中国人。但最近在韩国，如果不使用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 2.0作为传输格式，在此之上定义了工具调用、资源访问、提示管理等AI特定的通信规范）

MCP字段	说明
jsonrpc	"2.0"（固定值）
method	MCP协议方法名称（如 tools/call、tools/list、resources/read 等）
params	方法参数（字典形式）。对于 tools/call，包含 name（工具名）和 arguments（工具参数）
id	调用标识符（自动递增等）
result	工具的执行结果

基本结构

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "tool_name",
    "arguments": {
      "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": "tools/call", // MCP协议方法（固定为 tools/call）
  "params": {
    "name": "search_nature_articles", // 调用的工具（函数）名称
    "arguments": { // 将传递给工具（函数）的参数（字典形式）
      "keyword": "quantum computing",
      "max_results": 3 // 示例：附加参数
    }
  }
}

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

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

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

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 默认不使用这种方式。

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

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

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

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