快速上手：開發第一個 MCP Server

本文提供了一個完整的 MCP Server 實現示例，通過 Python 代碼和 Cline 測試，展示了 MCP 如何用於增強 AI 應用的能力，特別是 Tool 能力的集成和調用。

MCP 爲連接 AI 應用與數據源提供了一個通用的開放標準，用單一協議取代了碎片化的集成。通過這個機制， 能力小的 AI 應用會變成更強的應用

在整個 MCP 的架構中，我們的 AI 應用（如 Cline）作爲 MCP Hosts，通過內部的 MCP Client 去接入不同的 MCP Server，從而達到增強能力的目的

根據 MCP 協議，當 AI 應用連接到 MCP Server 後，能夠獲取多種能力，比如 Tool，Prompts、Resources 等

  1. 常見 AI 應用對 MCP Server 能力的支持情況

目前 MCP 還在發展過程中，我們可以通過官方看到常見 AI 應用目前可以使用的能力情況。

應用對於 Tool 能力的使用，目前是最廣泛的：

  1. 代碼實現 MCP Server

我們要實現一個簡單的 server，他將有一個 tool，可以通過訂單號查詢物流信息。

這個 server 在整個架構中的位置，就是下圖中綠色的塊：

2.1 配置環境

首先，讓我們安裝 uv 並設置我們的 Python 項目和環境：

安裝 uv 工具（windows）

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

重新開啓一個終端，並確認 uv 已經安裝成功

PS G:\workspace\idea\py\hello-mcp-server> uv version
uv 0.6.6 (c1a0bb85e 2025-03-12)

❝

在 macos/linux 環境中安裝 uv

curl -LsSf https://astral.sh/uv/install.sh | sh

❝

uv 是一個用 Rust 編寫的極快的 Python 包和項目管理器。

官網：https://github.com/astral-sh/uv

創建項目，初始化環境：

# 初始化項目
uv init hello-mcp-server

# 創建Python虛擬環境
cd hello-mcp-server
uv venv

# 激活虛擬環境
.venv\Scripts\activate

# 安裝依賴
uv add mcp[cli]

2.2  新建 MCP Server : hello_mcp_server.py

我們新建一個 Server，並增加 tool 來模擬通過訂單號查詢物流信息的功能

2.2.1 定義一個 server

導入包並定義 mcp 實例

"""
pip install mcp[cli]
"""
from mcp.server.fastmcp import FastMCP
from pydantic import Field

# Initialize FastMCP server
mcp = FastMCP("hello-mcp-server", log_level="ERROR")

2.2.2 定義工具

通過@mcp.tool()註解，把一個函數註冊爲 Tool

# 註冊工具的裝飾器，可以很方便的把一個函數註冊爲工具
@mcp.tool()
asyncdef query_logistics(order_id: str = Field(description="訂單號")) -> str:
    """查詢物流信息。當用戶需要根據訂單號查詢物流信息時，調用此工具
    
    Args:
        order_id: 訂單號
    
    Returns:
        物流信息的字符串描述
    """
    # 統一的物流信息數據
    tracking_info = [
        {"time": "2024-01-20 10:00:00", "status": "包裹已攬收", "location": "深圳轉運中心"},
        {"time": "2024-01-20 15:30:00", "status": "運輸中", "location": "深圳市"},
        {"time": "2024-01-21 09:00:00", "status": "到達目的地", "location": "北京市"},
        {"time": "2024-01-21 14:00:00", "status": "派送中", "location": "北京市朝陽區"},
        {"time": "2024-01-21 16:30:00", "status": "已簽收", "location": "北京市朝陽區三里屯"}
    ]

    # 格式化物流信息
    result = f"物流單號：{order_id}\n\n物流軌跡：\n"
    for item in tracking_info:
        result += f"[{item['time']}] {item['status']} - {item['location']}\n"

    return result

2.2.3 使用 MCP Inspector 進行測試

MCP Inspector 是一個用於測試和調試 MCP 服務器的交互式開發工具。

https://modelcontextprotocol.io/docs/tools/inspector

啓動 MCP Inspector：

執行命令：mcp dev hello_mcp_server.py

(hello-mcp-server) PS G:\workspace\idea\py\hello-mcp-server> mcp dev hello_mcp_server.py
Starting MCP inspector...
Proxy server listening on port 3000

🔍 MCP Inspector is up and running at http://localhost:5173 🚀

通過瀏覽器打開 http://localhost:5173

連接 MCP Server:

點擊 “Connect” 啓動 MCP Server 並建立連接

  1. 使用標準輸入輸出作爲傳輸層

  2. 使用命令是 uv

3.uv 命令的參數

查詢所有的 Tool：

  1. 點擊 “Tools” 能力標籤

  2. 點擊 “List Tools”，查詢 server 中所有的 tool（調用了協議的tools/list 端點）

  3. 顯示出所有的 tool

執行 Tool：

  1. 選擇需要測試的 tool

  2. 輸入入參：ORDER-123456，點擊 “Run Tool”（調用了協議的tools/call 端點）

3.Tool 成功返回結果

  1. 使用 Cline 測試 Server

打開 Cline，點擊上邊的 “MCP Server”

選擇 “Installed”

點擊 “Configure MCP Servers”

右邊會彈出配置文件

將自己剛寫的服務器相關配置填進去，保存

"hello-mcp-server": {
"name": "第一個MCP服務",
"key": "hello-mcp-server",
"command": "uv",       
"args": [
    "--directory",
    "G:\\workspace\\idea\\py\\hello-mcp-server\\",
    "run",
    "--with",
    "mcp",
    "mcp",
    "run",
    "hello_mcp_server.py"
  ],
"disabled": false,
"autoApprove": []
}

整個完整命令相當於：

uv --directory G:\workspace\idea\py\hello-mcp-server\ run --with mcp mcp run hello_mcp_server.py

分爲 3 段：

  1. uv --directory G:\workspace\idea\py\hello-mcp-server\

    指定工作目錄

  2. run --with mcp

    運行時必須要有 mcp 包被安裝

  3. mcp run hello_mcp_server.py

    使用 mcp 啓動 server

左邊會生成對應的服務列表，點擊 “Done” 退出

在 Cline 對話框中輸入提示詞：查一下訂單爲 “ORDER-123456” 的物流信息

Cline 開始調用 MCP Server，點擊 “Approve” 同意

MCP Server 調用成功

3.1 Cline 連接 MCP Server 的相關 Client 源碼

Cline(相當於 MCP 架構中的 Host) 源碼中，MCP 相關的代碼在src/services/mcp/McpHub.ts中，MCP Clinet 連接 MCP  Server 的代碼在connectToServer:

private async connectToServer(name: string, config: StdioServerParameters): Promise<void> {
  ...

try {
   // 創建新的MCP客戶端實例，設置客戶端名稱和版本信息
   const client = new Client(
    {
     name: "Cline",
     version: this.providerRef.deref()?.context.extension?.packageJSON?.version ?? "1.0.0",
    },
    {
     capabilities: {},        // 客戶端沒有給服務端暴露能力
    },
   )

   // 創建標準輸入輸出傳輸實例，配置命令、參數和環境變量
   // 這個是我們配置文件的內容
   const transport = new StdioClientTransport({
    command: config.command,
    args: config.args,
    env: {
     ...config.env,
     ...(process.env.PATH ? { PATH: process.env.PATH } : {}),
    },
    stderr: "pipe", 
   })

            ......
            
   // 啓動傳輸層，建立實際的進程間通信通道
   await transport.start()
   
   ...

   // 建立MCP客戶端連接
   // 連接成功後更新服務器狀態爲已連接，清除錯誤信息
   // 初始化並獲取服務器提供的工具和資源列表
   await client.connect(transport)
   connection.server.status = "connected"
   connection.server.error = ""

   // 初始化獲取工具資源列表
   connection.server.tools = awaitthis.fetchToolsList(name)
   connection.server.resources = awaitthis.fetchResourcesList(name)
   connection.server.resourceTemplates = awaitthis.fetchResourceTemplatesList(name)
  } catch (error) {
   ......
  }
 }

到目前爲止我們實現了一個能提供 Tool 能力的 MCP Server

本文由 Readfog 進行 AMP 轉碼，版權歸原作者所有。
來源：https://mp.weixin.qq.com/s/7TaBJykV6gTxl2g5vEZGWA

猜你喜歡